@homespunapps/cli 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @homespunapps/cli
 
-Command-line client for the [Homespun](https://github.com/aerolalit/homespun) relay:
+Command-line client for the [Homespun](https://homespun.dev) relay:
 hand a human a rich interactive UI by URL and capture their answer as structured
 data — from any agent (cron job, chat bot, CI, headless server).
 
@@ -30,10 +30,19 @@ Add `--no-open` on a headless / SSH box and it just prints the URL.
 ## Setup
 
 ```sh
-export HOMESPUN_URL=https://homespun.dev   # or your self-hosted relay
+export HOMESPUN_URL=https://homespun.dev   # or a different relay origin
 homespun agent register --name "my-agent"            # provisions and saves an API key
 ```
 
+By default `homespun agent register` uses browser approval (an RFC 8628 style
+device flow): it prints a link and a short code like `ABCD-EFGH`; open the
+link on any device (your phone works), sign in, and approve. The agent comes
+out already linked to your account, ready to deploy. On an older relay
+without the flow the CLI falls back to direct registration automatically
+(such agents need a one-time `homespun agent claim <code>` afterwards; mint
+the code in the relay's Settings). `--no-device` forces the direct path,
+and `--secret <s>` (for `REGISTRATION_MODE=secret` relays) implies it.
+
 `homespun agent register` writes the URL + API key to
 `${XDG_CONFIG_HOME:-~/.config}/homespun/config.json`. Subsequent commands need
 only `HOMESPUN_URL` (or nothing) in the environment.
@@ -46,7 +55,9 @@ Uniform `homespun <noun> <verb> [options]`:
 
 ```
 homespun demo                      Zero-setup guided tour — see the round-trip live
-homespun agent register            Provision an agent API key and save it locally
+homespun agent register            Provision an agent API key (browser approval
+                                   by default; --no-device for direct) and save it
+homespun agent claim <code>        Bind this agent to a human via a one-shot code
 homespun agent logout              Clear the locally-saved URL + API key
 homespun create            Create an app — returns app_id, urls, tokens
 homespun show <id>         Non-blocking snapshot: metadata + event log
@@ -76,6 +87,5 @@ homespun watch "$SESSION" | jq 'select(.type == "human_response")'
 
 ## Links
 
-- Repo: <https://github.com/aerolalit/homespun>
-- Spec: <https://github.com/aerolalit/homespun/blob/main/docs/SPEC.md>
+- Docs: <https://docs.homespun.dev>
 - License: MIT

package/dist/commands/register.js

@@ -1,26 +1,46 @@
-// `homespun agent register` — self-provision an agent API key from the relay.
+// `homespun agent register` - provision an agent API key from the relay.
 //
 // This is the one command that needs no API key: it is the call that obtains
-// one. If the relay runs REGISTRATION_MODE=secret, pass the shared
-// registration secret via --secret or HOMESPUN_REGISTER_SECRET. On success the key
-// (and relay URL) are persisted under a named profile in the CLI config file,
-// so every later command works with only HOMESPUN_URL (or nothing) set.
+// one. Two paths:
+//
+//   DEVICE FLOW (default) - RFC 8628 style browser approval. The CLI asks the
+//   relay for a device_code + user_code pair, prints a verification URL the
+//   human can open on ANY device, and polls until the human approves. The
+//   resulting agent is already OWNED by the approving human (no separate
+//   `homespun agent claim` step needed).
+//
+//   DIRECT (fallback) - plain POST /v1/register, the pre-device-flow path.
+//   Used when the relay 404s the device endpoints (older relay), when a
+//   registration secret is supplied (REGISTRATION_MODE=secret relays), or on
+//   --no-device. Direct-registered agents are unowned until claimed.
+//
+// On success the key (and relay URL) are persisted under a named profile in
+// the CLI config file, so every later command works with only HOMESPUN_URL (or
+// nothing) set.
+import { hostname } from "node:os";
 import { registerAgent, HomespunApiError } from "@homespunapps/core";
 import { assertKnownFlags } from "../argv.js";
 import { DEFAULT_RELAY_URL } from "../config.js";
+import { runDeviceFlow } from "../device-flow.js";
 import { printJson, fail, failUpgradeRequired } from "../output.js";
 import { isValidProfileName, DEFAULT_PROFILE_NAME, readStore, resolveProfile, upsertProfile, } from "../store.js";
 import { VERSION } from "../version.js";
 const KNOWN_FLAGS = ["name", "secret"];
-const KNOWN_BOOLS = ["print-key"];
-export const registerHelp = `homespun agent register — register this agent with the relay and save the key locally
+const KNOWN_BOOLS = ["print-key", "no-device"];
+export const registerHelp = `homespun agent register - register this agent with the relay and save the key locally
 
 Usage:
   homespun agent register [options]
 
-Calls POST /v1/register, then saves the returned API key (and relay URL) under
-a named profile in the CLI config file — so afterwards every other command
-works with only HOMESPUN_URL set (no HOMESPUN_API_KEY needed).
+By default this runs the browser device-authorization flow: it prints a link
+and a short code, you (or the account owner) open the link on any device,
+sign in, and approve - and the agent comes out already linked to that
+account. Older relays without the flow fall back to plain POST /v1/register
+automatically (such agents need a separate 'homespun agent claim' afterwards).
+
+The returned API key (and relay URL) are saved under a named profile in the
+CLI config file - so afterwards every other command works with only HOMESPUN_URL
+set (no HOMESPUN_API_KEY needed).
 
 If --profile is omitted, the registered key goes under the currently-active
 profile (or 'default' for a fresh install). Pass --profile <name> to keep
@@ -28,8 +48,9 @@ multiple environments (dev/staging/prod) side by side; switch between them
 with 'homespun config use <name>' or '--profile <name>' / HOMESPUN_PROFILE.
 
 Options:
-  --name <n>          Agent display name on the relay. The relay defaults it
-                      if omitted.
+  --name <n>          Agent display name on the relay (shown on the approval
+                      screen). Defaults to cli-<hostname> for the device flow;
+                      the relay defaults it for the direct path.
   --profile <name>    Local profile name to save under. Defaults to the active
                       profile, or 'default' on a fresh install. Letters,
                       digits, _ and -, up to 32 chars.
@@ -37,23 +58,48 @@ Options:
                       profile, then the hosted Homespun relay. Self-hosters set
                       this.
   --secret <s>        Registration secret, sent as a Bearer token. Only needed
-                      when the relay uses REGISTRATION_MODE=secret. Falls back
-                      to the HOMESPUN_REGISTER_SECRET env var.
+                      when the relay uses REGISTRATION_MODE=secret. Implies the
+                      direct path (no browser approval). Falls back to the
+                      HOMESPUN_REGISTER_SECRET env var.
+  --no-device         Skip the browser approval and register directly
+                      (POST /v1/register). The agent is unowned until claimed.
   --print-key         Also echo the full api_key in the output. By default the
                       key is only persisted to the config file, never printed.
   -h, --help          Show this help.
 
 Output (stdout, JSON):
-  { agent_id, key_prefix, profile, saved_to }   (+ api_key when --print-key)
+  { agent_id, key_prefix, profile, saved_to, registered_via }
+  (+ api_key when --print-key)
 
 The API key is saved to the CLI config file (mode 0600); it is not printed
 unless --print-key is passed.`;
+/**
+ * Default agent name for the device flow: the consent screen must name what
+ * the human is approving, so an unnamed agent gets "cli-<hostname>" instead
+ * of the relay's unhelpful generic default. Control characters are stripped
+ * and the result clamped to the relay's 64-char cap.
+ */
+export function defaultDeviceAgentName(host = hostname()) {
+    let cleaned = "";
+    for (const ch of host.trim()) {
+        const codePoint = ch.codePointAt(0) ?? 0;
+        if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f))
+            continue;
+        cleaned += ch;
+    }
+    const name = `cli-${cleaned}`.slice(0, 64).trim();
+    return name.length > "cli-".length ? name : "cli-agent";
+}
+/** Compute the display prefix of an API key, mirroring the relay's rule. */
+function apiKeyPrefix(key) {
+    return key.startsWith("hs_") ? key.slice(0, 9) : key.slice(0, 8);
+}
 export async function runRegister(args) {
     assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun agent register");
     // Profile selection for the WRITE side: --profile flag → HOMESPUN_PROFILE env
     // → the store's current profile → DEFAULT_PROFILE_NAME ('default') for
     // a fresh install. We deliberately don't fall through to "no profile, use
-    // a fresh name" — the agent needs to end up somewhere callable, and
+    // a fresh name" - the agent needs to end up somewhere callable, and
     // 'default' is a stable, predictable home.
     const profileFlag = args.flags.get("profile") ?? process.env.HOMESPUN_PROFILE;
     const store = readStore();
@@ -61,7 +107,7 @@ export async function runRegister(args) {
         ? profileFlag
         : (store.currentProfile ?? DEFAULT_PROFILE_NAME);
     if (!isValidProfileName(profileName)) {
-        fail(`invalid profile name '${profileName}' — letters, digits, _ and -, up to 32 chars`, "invalid_args");
+        fail(`invalid profile name '${profileName}' - letters, digits, _ and -, up to 32 chars`, "invalid_args");
     }
     // URL precedence for the relay we're registering against:
     //   --url flag > HOMESPUN_URL env > target-profile's existing url > default.
@@ -74,21 +120,70 @@ export async function runRegister(args) {
         activeUrl = active?.profile.url;
     }
     catch {
-        // Selector didn't resolve — fine on register: we're about to create it.
+        // Selector didn't resolve - fine on register: we're about to create it.
         activeUrl = undefined;
     }
-    const url = args.flags.get("url") ??
+    const url = (args.flags.get("url") ??
         process.env.HOMESPUN_URL ??
         activeUrl ??
-        DEFAULT_RELAY_URL;
+        DEFAULT_RELAY_URL).replace(/\/$/, "");
     const name = args.flags.get("name");
     const secret = args.flags.get("secret") ??
         process.env.HOMESPUN_REGISTER_SECRET ??
         undefined;
+    // The device flow is the default. A registration secret implies a
+    // REGISTRATION_MODE=secret relay whose operator hands out direct access,
+    // and --no-device is the explicit opt-out (CI, headless-with-no-human).
+    const wantDevice = !args.bools.has("no-device") && (secret === undefined || secret === "");
+    if (wantDevice) {
+        try {
+            const outcome = await runDeviceFlow({
+                url,
+                name: name ?? defaultDeviceAgentName(),
+                cliVersion: VERSION,
+            });
+            if (outcome.supported) {
+                const savedTo = upsertProfile(profileName, { url, apiKey: outcome.agent_key }, true);
+                const out = {
+                    agent_id: outcome.agent_id,
+                    key_prefix: apiKeyPrefix(outcome.agent_key),
+                    profile: profileName,
+                    saved_to: savedTo,
+                    registered_via: "device",
+                };
+                if (args.bools.has("print-key")) {
+                    out["api_key"] = outcome.agent_key;
+                }
+                printJson(out);
+                return;
+            }
+            // 404 on /v1/device/code: an older relay. Fall through to the direct
+            // path with a note so the behavior change is visible, not silent.
+            process.stderr.write("note: this relay does not support browser approval (older relay); " +
+                "falling back to direct registration. The agent will need " +
+                "'homespun agent claim <code>' to get an owner.\n");
+        }
+        catch (e) {
+            if (e instanceof HomespunApiError) {
+                if (e.status === 426 && e.code === "cli_upgrade_required") {
+                    failUpgradeRequired(e);
+                }
+                if (e.status === 429) {
+                    fail("device authorization rate limit exceeded - try again later", "rate_limited", undefined, { hint: e.hint, retryable: true, docs_url: e.docsUrl });
+                }
+                fail(e.message, e.code, e.details, {
+                    hint: e.hint,
+                    retryable: e.retryable,
+                    docs_url: e.docsUrl,
+                });
+            }
+            fail(e instanceof Error ? e.message : String(e), "internal");
+        }
+    }
     let result;
     try {
         result = await registerAgent({
-            url: url.replace(/\/$/, ""),
+            url,
             ...(name !== undefined ? { name } : {}),
             ...(secret !== undefined && secret !== "" ? { secret } : {}),
             cliVersion: VERSION,
@@ -103,7 +198,7 @@ export async function runRegister(args) {
                 failUpgradeRequired(e);
             }
             if (e.status === 429) {
-                fail("registration rate limit exceeded — try again later", "rate_limited", undefined, { hint: e.hint, retryable: e.retryable, docs_url: e.docsUrl });
+                fail("registration rate limit exceeded - try again later", "rate_limited", undefined, { hint: e.hint, retryable: e.retryable, docs_url: e.docsUrl });
             }
             fail(e.message, e.code, e.details, {
                 hint: e.hint,
@@ -117,12 +212,13 @@ export async function runRegister(args) {
     // registered against this relay, so the only sensible follow-up is to
     // start using it. The previous behaviour (one global URL+key) is exactly
     // the single-profile case of this.
-    const savedTo = upsertProfile(profileName, { url: url.replace(/\/$/, ""), apiKey: result.api_key }, true);
+    const savedTo = upsertProfile(profileName, { url, apiKey: result.api_key }, true);
     const out = {
         agent_id: result.agent_id,
         key_prefix: result.key_prefix,
         profile: profileName,
         saved_to: savedTo,
+        registered_via: "direct",
     };
     if (args.bools.has("print-key")) {
         out["api_key"] = result.api_key;

package/dist/device-flow.js

@@ -0,0 +1,162 @@
+// Device-authorization registration (RFC 8628 style) - the browser-approval
+// path behind `homespun agent register`.
+//
+// The CLI asks the relay for a device_code + user_code pair, prints the
+// verification URL + code for the human (who can open it on ANY device),
+// and polls POST /v1/device/token until the human approves, denies, or the
+// codes expire. On approval the relay creates an agent OWNED by the
+// approving human and returns its key exactly once.
+//
+// Everything human-facing goes to stderr - stdout stays reserved for the
+// final JSON envelope, like every other command. fetch/sleep/print are
+// injectable so the polling loop is unit-testable with a mocked relay.
+import { HomespunApiError } from "@homespunapps/core";
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function defaultPrint(line) {
+    process.stderr.write(line + "\n");
+}
+/** POST JSON, returning { status, body } with the body parsed best-effort. */
+async function postJson(fetchImpl, url, body, cliVersion) {
+    const headers = {
+        "content-type": "application/json",
+    };
+    if (cliVersion !== undefined && cliVersion !== "") {
+        headers["x-homespun-cli-version"] = cliVersion;
+    }
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new HomespunApiError(0, "fetch_error", msg);
+    }
+    const text = await res.text().catch(() => "");
+    let parsed = null;
+    if (text !== "") {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = null;
+        }
+    }
+    return { status: res.status, body: parsed };
+}
+/** The relay-envelope error code/message, when the body carries one. */
+function envelopeError(body) {
+    const err = body?.error;
+    if (err && typeof err === "object") {
+        const e = err;
+        return {
+            code: typeof e.code === "string" ? e.code : "relay_error",
+            message: typeof e.message === "string" ? e.message : "relay error",
+        };
+    }
+    return null;
+}
+/** The RFC 8628 error string ({ error: "authorization_pending" }), if any. */
+function rfcErrorCode(body) {
+    const err = body?.error;
+    return typeof err === "string" ? err : null;
+}
+/**
+ * Run the device-authorization flow end to end. Returns `supported: false`
+ * when the relay 404s the code request (an older relay - the caller falls
+ * back to plain POST /v1/register). Throws HomespunApiError on every other
+ * failure, including denial and expiry, with actionable codes:
+ *
+ *   device_flow_denied    the human clicked Deny
+ *   device_flow_expired   nobody approved within the code's lifetime
+ */
+export async function runDeviceFlow(opts) {
+    const base = opts.url.replace(/\/$/, "");
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleepImpl ?? defaultSleep;
+    const print = opts.print ?? defaultPrint;
+    // ---- 1. Request the code pair -----------------------------------------
+    const start = await postJson(fetchImpl, `${base}/v1/device/code`, { name: opts.name }, opts.cliVersion);
+    if (start.status === 404) {
+        // Older relay without the device flow - signal the caller to fall back.
+        return { supported: false };
+    }
+    if (start.status !== 200) {
+        const env = envelopeError(start.body);
+        throw new HomespunApiError(start.status, env?.code ?? "relay_error", env?.message ?? `relay returned ${start.status} for /v1/device/code`);
+    }
+    const code = start.body;
+    if (!code ||
+        typeof code.device_code !== "string" ||
+        typeof code.user_code !== "string" ||
+        typeof code.verification_uri_complete !== "string") {
+        throw new HomespunApiError(200, "invalid_response", "relay returned an unexpected /v1/device/code body");
+    }
+    // ---- 2. Hand the human their marching orders ---------------------------
+    const expiresMin = Math.max(1, Math.round((code.expires_in ?? 900) / 60));
+    print("");
+    print("To approve this agent, open:");
+    print("");
+    print(`    ${code.verification_uri_complete}`);
+    print("");
+    print(`and confirm the code:  ${code.user_code}`);
+    print("");
+    print("You can open the link on any device (phone or laptop) and sign in there.");
+    print(`Waiting for approval... (expires in ${expiresMin} min; Ctrl-C to abort)`);
+    // ---- 3. Poll until a terminal answer -----------------------------------
+    let intervalSeconds = typeof code.interval === "number" && code.interval > 0 ? code.interval : 5;
+    const deadline = Date.now() + (code.expires_in ?? 900) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalSeconds * 1000);
+        // Re-check after sleeping: don't fire a poll we already know is past
+        // the code's lifetime (the relay would just answer expired_token).
+        if (Date.now() >= deadline)
+            break;
+        const poll = await postJson(fetchImpl, `${base}/v1/device/token`, { device_code: code.device_code }, opts.cliVersion);
+        if (poll.status === 200) {
+            const body = poll.body;
+            if (typeof body?.agent_key !== "string" ||
+                typeof body?.agent_id !== "string") {
+                throw new HomespunApiError(200, "invalid_response", "relay returned an unexpected /v1/device/token body");
+            }
+            print("Approved.");
+            return {
+                supported: true,
+                agent_id: body.agent_id,
+                agent_key: body.agent_key,
+                name: typeof body.name === "string" ? body.name : opts.name,
+            };
+        }
+        const rfc = rfcErrorCode(poll.body);
+        if (poll.status === 400 && rfc !== null) {
+            switch (rfc) {
+                case "authorization_pending":
+                    continue;
+                case "slow_down":
+                    // RFC 8628 §3.5: add 5 seconds to the interval and keep going.
+                    intervalSeconds += 5;
+                    continue;
+                case "access_denied":
+                    throw new HomespunApiError(400, "device_flow_denied", "the approval request was denied in the browser");
+                case "expired_token":
+                    throw new HomespunApiError(400, "device_flow_expired", "the device code expired before it was approved - run 'homespun agent register' again");
+                default:
+                    throw new HomespunApiError(400, rfc, `relay rejected the poll (${rfc})`);
+            }
+        }
+        if (poll.status === 429) {
+            // Transient general rate limit - back off like a slow_down and retry.
+            intervalSeconds += 5;
+            continue;
+        }
+        // 426 cli_upgrade_required and anything else: surface the envelope.
+        const env = envelopeError(poll.body);
+        throw new HomespunApiError(poll.status, env?.code ?? "relay_error", env?.message ?? `relay returned ${poll.status} for /v1/device/token`, poll.body?.error?.details);
+    }
+    throw new HomespunApiError(400, "device_flow_expired", "the device code expired before it was approved - run 'homespun agent register' again");
+}

package/dist/index.js

@@ -110,6 +110,9 @@ const BOOLEAN_FLAGS = new Set([
     "plain",
     // `homespun deploy --force` / `homespun apps ... --force`: override a compat gate.
     "force",
+    // `homespun agent register --no-device`: skip the browser device-authorization
+    // flow and register directly (unowned agent), the pre-device-flow behavior.
+    "no-device",
 ]);
 async function main() {
     const rawArgv = process.argv.slice(2);

package/dist/version.js

@@ -1,11 +1,25 @@
 // Single source of truth for the CLI version string.
 //
 // - `homespun --version` prints this verbatim.
-// - Every HomespunClient construction passes it as `cliVersion`, which apps
-//   as the `x-homespun-cli-version` header on every relay request — drives the
+// - Every HomespunClient construction passes it as `cliVersion`, which rides
+//   as the `x-homespun-cli-version` header on every relay request, driving the
 //   relay's version-skew check (HTTP 426 `cli_upgrade_required`).
 //
-// Keep this in lockstep with packages/cli/package.json's `version` field;
-// they're consulted in different places (here for the runtime header,
-// package.json for npm publish + dependency resolution).
-export const VERSION = "0.0.29";
+// The value is read at runtime from THIS package's own `package.json`
+// `version` field rather than hardcoded, so it can never drift from what npm
+// published. Both the built `dist/version.js` and the source `src/version.ts`
+// sit exactly one directory below the package root, so `../package.json`
+// resolves the same in either location.
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function readVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = resolve(here, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+        throw new Error(`homespun CLI: missing version in ${pkgPath}`);
+    }
+    return pkg.version;
+}
+export const VERSION = readVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Command-line client for the Homespun relay: create apps, inspect state, send and watch events.",
   "license": "MIT",
   "type": "module",
@@ -11,14 +11,9 @@
     "relay",
     "human-in-the-loop"
   ],
-  "homepage": "https://github.com/aerolalit/homespun#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aerolalit/homespun.git",
-    "directory": "packages/cli"
-  },
+  "homepage": "https://homespun.dev",
   "bugs": {
-    "url": "https://github.com/aerolalit/homespun/issues"
+    "url": "mailto:support@homespun.dev"
   },
   "engines": {
     "node": ">=20"