@homespunapps/cli 1.0.0

package/dist/commands/attachment-delete.js

@@ -0,0 +1,37 @@
+// `homespun attachment delete <attachment-id>` — soft-delete a attachment.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = [];
+const KNOWN_BOOLS = [];
+export const blobDeleteHelp = `homespun attachment delete — soft-delete a attachment
+
+Usage:
+  homespun attachment delete <attachment-id> [options]
+
+Marks the attachment as deleted (DELETE /v1/attachments/:id). Idempotent: deleting an
+already-deleted attachment still returns success. Tokens minted against this attachment
+become unusable.
+
+Options:
+  --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, JSON):
+  { attachment_id, deleted: true }`;
+export async function runBlobDelete(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment delete");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'homespun attachment delete <attachment-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.deleteBlob(attachmentId);
+        printJson({ attachment_id: attachmentId, ...r });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/attachment-download.js

@@ -0,0 +1,53 @@
+// `homespun attachment download <attachment-id>` — fetch attachment bytes by id.
+import { writeFileSync } from "node:fs";
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = ["out"];
+const KNOWN_BOOLS = [];
+export const blobDownloadHelp = `homespun attachment download — fetch a attachment's bytes
+
+Usage:
+  homespun attachment download <attachment-id> [--out <path>] [options]
+
+GETs the attachment bytes. With --out <path> the bytes are written to that file and
+a JSON summary is printed on stdout; without --out the bytes are written to
+stdout verbatim (useful for piping into another tool — but binary on a TTY
+is rarely useful).
+
+Options:
+  --out <path>           Write bytes to <path> instead of stdout.
+  --url <url>            Relay base URL (overrides HOMESPUN_URL).
+  --api-key <key>        Agent API key (overrides HOMESPUN_API_KEY).
+  -h, --help             Show this help.
+
+Output:
+  Without --out: raw bytes to stdout.
+  With --out:    { attachment_id, written: <path>, bytes: <n> } to stdout.`;
+export async function runBlobDownload(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment download");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'homespun attachment download <attachment-id>'", "invalid_args");
+    }
+    const out = args.flags.get("out");
+    const client = makeClient(args);
+    try {
+        const buf = await client.downloadBlob(attachmentId);
+        if (out) {
+            writeFileSync(out, Buffer.from(buf));
+            printJson({
+                attachment_id: attachmentId,
+                written: out,
+                bytes: buf.byteLength,
+            });
+        }
+        else {
+            // Binary to stdout — useful for piping into another tool.
+            process.stdout.write(Buffer.from(buf));
+        }
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/attachment-list.js

@@ -0,0 +1,50 @@
+// `homespun attachment list` — enumerate YOUR agent's attachments.
+//
+// Lists attachments owned by the calling agent, newest first. Soft-deleted attachments
+// are excluded; tokens are not enumerated here (use 'homespun attachment token list
+// <attachment-id>' for that).
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, printJson, failFromError } from "../output.js";
+const KNOWN_FLAGS = ["cursor", "limit"];
+const KNOWN_BOOLS = [];
+export const blobListHelp = `homespun attachment list — enumerate YOUR agent's attachments
+
+Usage:
+  homespun attachment list [--cursor <token>] [--limit <n>] [options]
+
+Returns the agent's non-deleted attachments (newest first). Paginated via opaque
+cursor: when next_cursor is non-null in the response, pass it back as
+--cursor to get the next page.
+
+Options:
+  --cursor <token>       Opaque pagination cursor from a prior response.
+  --limit <n>            Page size (1..100). Defaults to the relay default
+                         (50).
+  --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, JSON):
+  { items: AttachmentRef[], next_cursor: string | null }`;
+export async function runBlobList(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment list");
+    const cursor = args.flags.get("cursor");
+    const limitRaw = args.flags.get("limit");
+    let limit;
+    if (limitRaw !== undefined) {
+        const n = Number(limitRaw);
+        if (!Number.isInteger(n) || n < 1 || n > 100) {
+            fail("--limit must be an integer in 1..100", "invalid_args");
+        }
+        limit = n;
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.listBlobs({ cursor, limit });
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/attachment-show.js

@@ -0,0 +1,37 @@
+// `homespun attachment show <attachment-id>` — print a attachment's metadata.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = [];
+const KNOWN_BOOLS = [];
+export const blobShowHelp = `homespun attachment show — print a attachment's metadata (no bytes)
+
+Usage:
+  homespun attachment show <attachment-id> [options]
+
+Looks up the attachment by id and prints its AttachmentRef metadata — owner, scope,
+mime, size, sha256, etc. Does NOT download the bytes; use 'homespun attachment
+download' for that.
+
+Options:
+  --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, JSON):
+  AttachmentRef`;
+export async function runBlobShow(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment show");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'homespun attachment show <attachment-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const ref = await client.getBlob(attachmentId);
+        printJson(ref);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/attachment-token.js

@@ -0,0 +1,133 @@
+// `homespun attachment token <mint|revoke|list>` — capability URLs for a attachment.
+//
+// A capability URL (/b/<token>) is a participant-facing way to fetch a attachment
+// without holding the agent's API key. Tokens are minted per-attachment, can be
+// time-bound (--ttl) and/or single-use (--once), and are stored hashed on
+// the relay — the plaintext token is returned ONCE on 'mint' and cannot be
+// recovered.
+//
+// This file is a sub-noun dispatcher under `homespun attachment`. The attachment dispatcher
+// hands us a ParsedArgs whose positionals[0] is "token" (our sub-noun
+// marker), so we read the verb from positionals[1] and the args from
+// positionals[2..]. Mirrors how participant.ts dispatches under `app
+// app participant`.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const MINT_FLAGS = ["ttl"];
+const MINT_BOOLS = ["once"];
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+export const blobTokenHelp = `homespun attachment token — manage a attachment's capability URLs
+
+Capability URLs let a participant (or any browser holding the URL) fetch a
+attachment without the agent's API key. Tokens are stored HASHED on the relay; the
+plaintext token is returned only ONCE from 'mint' — save the response before
+delivering the URL.
+
+Usage:
+  homespun attachment token <verb> <args>
+
+Verbs:
+  mint <attachment-id>          Mint a /b/<token> capability URL for one attachment.
+                          Optional: --ttl <seconds> (defaults by scope:
+                          30d app / 24h agent; the caller can only
+                          shorten), --once (token self-deletes on
+                          first successful GET). Returns { token, url,
+                          expires_at, ... } — ONCE.
+
+  revoke <attachment-id> <token-id>
+                          Invalidate one previously-minted token by id.
+                          Idempotent: revoking twice still returns success.
+
+  list <attachment-id>          Enumerate the tokens minted against one attachment,
+                          including revoked rows (for audit). Returns
+                          { attachment_id, items: [...] } where each item carries
+                          { token_id, token_prefix, expires_at, once,
+                          created_at, last_used_at, use_count, revoked_at }.
+                          The token plaintext is NEVER returned.
+
+Options:
+  --ttl <seconds>         (mint) per-token TTL; clamped by scope default.
+  --once                  (mint) token self-deletes on first GET.
+  --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 runBlobTokenMint(args) {
+    assertKnownFlags(args, MINT_FLAGS, MINT_BOOLS, "homespun attachment token mint");
+    const attachmentId = args.positionals[1];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'homespun attachment token mint <attachment-id>'", "invalid_args");
+    }
+    const ttlRaw = args.flags.get("ttl");
+    const ttl = ttlRaw === undefined ? undefined : Number(ttlRaw);
+    if (ttlRaw !== undefined && (!Number.isInteger(ttl) || ttl <= 0)) {
+        fail("--ttl must be a positive integer (seconds)", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.mintBlobToken(attachmentId, {
+            ttlSeconds: ttl,
+            once: args.bools.has("once"),
+        });
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runBlobTokenRevoke(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun attachment token revoke");
+    const attachmentId = args.positionals[1];
+    const tokenId = args.positionals[2];
+    if (!attachmentId || !tokenId) {
+        fail("missing arguments — 'homespun attachment token revoke <attachment-id> <token-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.revokeBlobToken(attachmentId, tokenId);
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runBlobTokenList(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun attachment token list");
+    const attachmentId = args.positionals[1];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'homespun attachment token list <attachment-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.listBlobTokens(attachmentId);
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runBlobToken(args) {
+    // positionals[0] is the verb (mint | revoke | list), positionals[1..] are
+    // the verb's args. (The attachment.ts dispatcher already shifted off the "token"
+    // marker before calling us.)
+    const verb = args.positionals[0];
+    switch (verb) {
+        case "mint":
+            await runBlobTokenMint(args);
+            break;
+        case "revoke":
+            await runBlobTokenRevoke(args);
+            break;
+        case "list":
+            await runBlobTokenList(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: homespun attachment token <mint|revoke|list> (run 'homespun attachment token --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown token verb '${verb}' — expected mint|revoke|list (run 'homespun attachment token --help')`, "invalid_args");
+    }
+}

package/dist/commands/attachment-upload.js

@@ -0,0 +1,65 @@
+// `homespun attachment upload` — POST /v1/attachments (multipart), two scopes.
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = ["file", "scope", "app-id", "filename", "mime"];
+const KNOWN_BOOLS = [];
+export const blobUploadHelp = `homespun attachment upload — upload a local file as a attachment
+
+Usage:
+  homespun attachment upload --file <path> [options]
+
+Required:
+  --file <path>          Local file to upload.
+
+Scope (default: agent):
+  --scope <s>            "agent" | "app".
+  --app-id <id>          Required when --scope=app.
+
+Optional:
+  --filename <name>      Display filename (otherwise basename of --file).
+  --mime <type>          Declared Content-Type. The relay sniffs the bytes
+                         regardless — this is advisory.
+  --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, JSON):
+  AttachmentRef — { attachment_id, scope, mime, size, sha256, ... }`;
+export async function runBlobUpload(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment upload");
+    const filePath = args.flags.get("file");
+    if (!filePath) {
+        fail("missing --file <path> — 'homespun attachment upload' requires a local file to upload", "invalid_args");
+    }
+    let bytes;
+    try {
+        bytes = readFileSync(filePath);
+    }
+    catch (e) {
+        fail(`failed to read --file '${filePath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+    }
+    const scopeRaw = args.flags.get("scope") ?? "agent";
+    if (scopeRaw !== "agent" && scopeRaw !== "app") {
+        fail(`unknown --scope '${scopeRaw}', expected one of: agent, app`, "invalid_args");
+    }
+    const scope = scopeRaw;
+    if (scope === "app" && !args.flags.get("app-id")) {
+        fail("--scope=app requires --app-id <id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const ref = await client.uploadBlob(bytes, {
+            scope,
+            appId: args.flags.get("app-id"),
+            filename: args.flags.get("filename") ?? basename(filePath),
+            mime: args.flags.get("mime"),
+        });
+        printJson(ref);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/attachment.js

@@ -0,0 +1,133 @@
+// `homespun attachment` — manage binary attachments (attachments) on the relay.
+//
+// A attachment is a typed binary file (image, PDF, audio, video, etc.) owned by an
+// agent and optionally bound to an App. Pages reference attachments
+// by id with `format: homespun-attachment-id`; participants can fetch a attachment through a
+// minted capability URL (/b/<token>) without needing the agent's API key.
+//
+// This file is a thin dispatcher — each verb's actual logic lives in its own
+// file (attachment-upload.ts, attachment-download.ts, attachment-show.ts, attachment-delete.ts) and
+// the token sub-noun is dispatched via attachment-token.ts.
+//
+// Most attachment verbs read their primary positional (the attachment_id) at
+// positionals[0]; we slice off our own verb before delegating so each verb
+// runner doesn't need to know it was reached through `homespun attachment`.
+import { runBlobUpload, blobUploadHelp } from "./attachment-upload.js";
+import { runBlobDownload, blobDownloadHelp } from "./attachment-download.js";
+import { runBlobShow, blobShowHelp } from "./attachment-show.js";
+import { runBlobList, blobListHelp } from "./attachment-list.js";
+import { runBlobDelete, blobDeleteHelp } from "./attachment-delete.js";
+import { runBlobToken, blobTokenHelp } from "./attachment-token.js";
+import { fail } from "../output.js";
+export const blobHelp = `homespun attachment — manage attachments (binary attachments) on the relay
+
+A attachment is a typed binary file (image, PDF, audio, video, ...) the agent has
+uploaded to the relay. Blobs are scoped:
+
+  agent     reusable across the agent's apps (default)
+  app       bound to one App; deleted with it
+
+Pages reference attachments by id (the relay's schema validates the id with
+\`format: homespun-attachment-id\`). For a participant-facing URL that bypasses the
+agent's API key, mint a token with 'homespun attachment token mint'.
+
+Usage:
+  homespun attachment <verb> [options]
+
+Verbs:
+  upload                 Upload a local file. Required: --file. Optional:
+                         --scope, --app-id, --filename, --mime. Prints
+                         { attachment_id, scope, mime, size, sha256, ... }.
+
+  download <attachment-id>     Download a attachment by id. Use --out <path> to write a
+                         file (default: writes to stdout — useful for piping).
+
+  show <attachment-id>         Print a attachment's metadata (HEAD-based — doesn't
+                         download the bytes).
+
+  list                   Enumerate YOUR agent's non-deleted attachments (newest
+                         first). Supports --cursor + --limit for pagination.
+
+  delete <attachment-id>       Soft-delete a attachment. Idempotent.
+
+  token <verb>           Capability URLs for a attachment (mint | revoke | list).
+                         'mint' returns a /b/<token> URL anyone can GET, with
+                         optional --ttl and --once. 'revoke' invalidates one
+                         token. 'list' enumerates a attachment's tokens (without
+                         the token plaintext, which is unrecoverable).
+
+Run \`homespun attachment <verb> --help\` for verb-specific options.
+
+Output: stdout is machine-readable JSON. Errors go to stderr as
+{"error":{"code","message"}} with a non-zero exit.`;
+/**
+ * Build a new ParsedArgs with the leading positional (the verb) stripped.
+ * The downstream verb runners read their primary positional (the attachment_id)
+ * at positionals[0], so we hand them an args object that looks exactly like
+ * they were called directly — mirrors app.ts's shiftPositionals.
+ */
+function shiftPositionals(args) {
+    // Propagate danglingValueFlags so the leaf runner's assertKnownFlags
+    // can still distinguish "unknown flag" from "missing value" — see the
+    // matching note in app.ts's shiftPositionals.
+    const out = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+    };
+    if (args.danglingValueFlags !== undefined) {
+        out.danglingValueFlags = args.danglingValueFlags;
+    }
+    return out;
+}
+export async function runBlob(args) {
+    const verb = args.positionals[0];
+    // `homespun attachment token --help` (verb-level help on the token sub-noun, with no
+    // further sub-verb). The general --help pre-empt in index.ts only fires
+    // when no positional follows the noun; here a positional ("token") is
+    // present, so the sub-noun must own its own --help routing.
+    if (verb === "token" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(blobTokenHelp + "\n");
+        return;
+    }
+    // `homespun attachment list --help` — same pattern (list takes no required positional
+    // so the general pre-empt would already fire, but for parity with app.ts
+    // we route through here when args carry the "list" positional explicitly).
+    if (verb === "list" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(blobListHelp + "\n");
+        return;
+    }
+    const inner = shiftPositionals(args);
+    switch (verb) {
+        case "upload":
+            await runBlobUpload(inner);
+            break;
+        case "download":
+            await runBlobDownload(inner);
+            break;
+        case "show":
+            await runBlobShow(inner);
+            break;
+        case "list":
+            await runBlobList(inner);
+            break;
+        case "delete":
+            await runBlobDelete(inner);
+            break;
+        case "token":
+            await runBlobToken(inner);
+            break;
+        case undefined:
+            fail("missing verb — usage: homespun attachment <upload|download|show|list|delete|token> (run 'homespun attachment --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown attachment verb '${verb}' — expected upload|download|show|list|delete|token (run 'homespun attachment --help')`, "invalid_args");
+    }
+}
+// Re-export per-verb helps so tests / docs can import them by canonical name
+// without knowing which file owns each verb.
+export { blobUploadHelp, blobDownloadHelp, blobShowHelp, blobListHelp, blobDeleteHelp, blobTokenHelp, };

package/dist/commands/claim.js

@@ -0,0 +1,68 @@
+// `homespun agent claim <code>` — bind this agent to a human via a one-shot
+// claim code the human generated in their settings UI.
+//
+// Flow (§6.1):
+//   1. Alice opens Settings → "Claim an agent" → relay mints a one-shot code,
+//      shows it to her once, 15-min TTL.
+//   2. Alice hands the code to the agent out-of-band (this CLI invocation
+//      is exactly that handoff).
+//   3. CLI calls POST /v1/agents/claim with the calling agent's API key.
+//   4. Relay binds Agent.ownerHumanId = alice.id, migrates app ownership.
+//
+// The CLI does NOT print the human's email or id — only the relay's response,
+// which is { ok, owner_human_id, claimed_at }. The agent's existing API key
+// keeps working.
+import { HomespunClient, HomespunApiError } from "@homespunapps/core";
+import { assertKnownFlags } from "../argv.js";
+import { resolveConfig } from "../config.js";
+import { printJson, fail } from "../output.js";
+const KNOWN_FLAGS = ["url", "api-key"];
+const KNOWN_BOOLS = [];
+export const claimHelp = `homespun agent claim — claim this agent for a human
+
+Usage:
+  homespun agent claim <code>
+
+Binds the calling agent to the human whose one-shot claim code is provided.
+The human generates the code in their settings UI (or via the relay's
+POST /v1/self/claim-codes endpoint) and hands it to the agent out-of-band.
+
+Arguments:
+  <code>              The one-shot claim code (begins with cc_). Required.
+
+Options:
+  --url <url>         Relay base URL. Falls back to HOMESPUN_URL / config file.
+  --api-key <key>     Agent API key. Falls back to HOMESPUN_API_KEY / config file.
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { ok: true, owner_human_id, claimed_at }
+
+Errors:
+  invalid_code             code is unknown, expired, or already consumed
+  agent_already_claimed    this agent already has an owning human
+
+Notes:
+  This is a one-way operation. To rotate the owner, revoke this agent
+  (\`homespun key revoke\`) and register a new one.`;
+export async function runClaim(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun agent claim");
+    const code = args.positionals[0];
+    if (!code) {
+        fail("missing required argument: <code> — run 'homespun agent claim --help'", "invalid_args");
+        return;
+    }
+    const creds = resolveConfig(args);
+    const client = new HomespunClient({ url: creds.url, apiKey: creds.apiKey });
+    try {
+        const result = await client.claimAgent(code);
+        printJson(result);
+    }
+    catch (err) {
+        if (err instanceof HomespunApiError) {
+            fail(err.message, err.code);
+            return;
+        }
+        throw err;
+    }
+}