@homespunapps/cli 1.0.0

package/dist/index.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// app — command-line client for the Homespun relay.
+//
+// Shape: uniform `homespun <noun> <verb> [options]`. Every command lives under a
+// noun; nothing is a bare top-level verb. See issue #163 for the rationale
+// behind the shape and the rename from the older flat layout.
+//
+// Config: HOMESPUN_URL and HOMESPUN_API_KEY (env), overridable with --url / --api-key.
+// Multiple environments live as named profiles in
+// $XDG_CONFIG_HOME/homespun/config.json; pick one with --profile or HOMESPUN_PROFILE.
+// Output is JSON by default. Every noun self-documents via --help.
+import { parseArgs, ArgvError } from "./argv.js";
+/**
+ * Translate an ArgvError into the canonical `invalid_args` envelope and exit
+ * non-zero. The parser throws ArgvError up-front; assertKnownFlags throws it
+ * from inside a runner. Both paths funnel here so the on-wire shape is one.
+ */
+function failArgvError(e) {
+    const error = {
+        code: "invalid_args",
+        message: e.message,
+    };
+    if (e.hint !== undefined)
+        error["hint"] = e.hint;
+    process.stderr.write(JSON.stringify({ error }) + "\n");
+    process.exit(1);
+}
+import { runAgent, agentHelp } from "./commands/agent.js";
+import { runKey, keyHelp } from "./commands/key.js";
+import { runTaste, tasteHelp } from "./commands/taste.js";
+import { runFeedback, feedbackHelp } from "./commands/feedback.js";
+import { runConfig, configHelp } from "./commands/config.js";
+import { runBlob, blobHelp } from "./commands/attachment.js";
+import { runSkill, skillHelp } from "./commands/skill.js";
+import { runDeploy, deployHelp } from "./commands/deploy.js";
+import { runApps, appsHelp } from "./commands/apps.js";
+import { runData, dataHelp } from "./commands/data.js";
+import { runMembers, membersHelp } from "./commands/members.js";
+import { VERSION } from "./version.js";
+import { HomespunApiError } from "@homespunapps/core";
+import { failUpgradeRequired } from "./output.js";
+const ROOT_HELP = `homespun: apps your AI builds and hosts for you and people you invite
+
+Usage:
+  homespun <command> [options]
+
+v2 app commands (operate on an App — a persistent, deployed web app):
+  deploy            Create or redeploy an app (POST /v1/apps or
+                    /v1/apps/:id/versions) — the create->redeploy loop.
+  apps              App lifecycle: list | show | update | delete | wake |
+                    watch (stream the app's change feed as JSON-lines).
+  data              Collection row CRUD for an app: list | get | upsert |
+                    update | delete.
+  members           App membership management: add | list | remove
+                    (invite/attach a member by email, list, or remove).
+
+Other noun groups:
+  key               YOUR agent's API key (list | revoke).
+  taste             YOUR agent's freeform UI taste notes
+                    (get | set | clear) — presentation preferences the agent
+                    has learned from human feedback and reads before
+                    generating an app.
+  feedback          One-shot feedback to the relay operator
+                    (create | list) — bug reports, feature requests, notes.
+  attachment        Binary attachments (upload | download | show | list |
+                    delete | token <mint|revoke|list>). Attachments are
+                    scoped to an agent or an App, and can be
+                    referenced from input_data via \`format: homespun-attachment-id\`.
+  agent             Agent identity on this machine (register | logout).
+  config            CLI config inspection (show).
+  skill             The relay's SKILL.md (show | version) — auto-updating;
+                    no API key required.
+
+Run \`homespun <command> --help\` for command-specific options.
+
+Config:
+  HOMESPUN_URL          Relay base URL.        Override: --url <url>
+  HOMESPUN_API_KEY      Agent API key.         Override: --api-key <key>
+  HOMESPUN_PROFILE      Active profile name.   Override: --profile <name>
+  'homespun agent register' provisions the API key and saves it (with the URL) to
+  \${XDG_CONFIG_HOME:-~/.config}/homespun/config.json under a named profile —
+  afterwards commands need no env vars. Manage multiple environments
+  (dev/staging/prod) with 'homespun config list / use / add / rm'.
+
+Global flags:
+  -h, --help        Show help.
+  -v, --version     Print version.
+  --profile <name>  Pick a saved profile for this invocation (overrides
+                    HOMESPUN_PROFILE and the saved 'current_profile').
+  --url <url>       Relay base URL — bypasses profile selection entirely.
+  --api-key <key>   Agent API key — bypasses profile selection entirely.
+
+Output: stdout is machine-readable JSON; errors go to stderr as
+{"error":{"code","message"}} with a non-zero exit.`;
+// Flags that never take a value. `json` is kept here purely for forward-compat
+// (JSON is currently the only output mode): accepting `--json` as a no-op bool
+// means a future `--text`/`--json` toggle won't break existing invocations. It
+// is intentionally undocumented in --help.
+//
+// `version` is deliberately NOT here: the top-level `-v` / `--version` is
+// handled from rawArgv[0] before parseArgs runs, so it never needs to be a
+// boolean flag — and keeping it out leaves room for a future noun-level
+// `--version <n>` value flag without a collision.
+const BOOLEAN_FLAGS = new Set([
+    "json",
+    "once",
+    "help",
+    "print-key",
+    "yes",
+    "plain",
+    // `homespun deploy --force` / `homespun apps ... --force`: override a compat gate.
+    "force",
+]);
+async function main() {
+    const rawArgv = process.argv.slice(2);
+    // Version: handle before anything else.
+    if (rawArgv[0] === "-v" || rawArgv[0] === "--version") {
+        process.stdout.write(VERSION + "\n");
+        return;
+    }
+    const noun = rawArgv[0];
+    const rest = rawArgv.slice(1);
+    if (noun === undefined ||
+        noun === "-h" ||
+        noun === "--help" ||
+        noun === "help") {
+        process.stdout.write(ROOT_HELP + "\n");
+        return;
+    }
+    let args;
+    try {
+        args = parseArgs(rest, BOOLEAN_FLAGS);
+    }
+    catch (e) {
+        if (e instanceof ArgvError) {
+            failArgvError(e);
+        }
+        throw e;
+    }
+    const helps = {
+        key: keyHelp,
+        taste: tasteHelp,
+        feedback: feedbackHelp,
+        attachment: blobHelp,
+        agent: agentHelp,
+        config: configHelp,
+        skill: skillHelp,
+        deploy: deployHelp,
+        apps: appsHelp,
+        data: dataHelp,
+        members: membersHelp,
+    };
+    if (!(noun in helps)) {
+        process.stderr.write(JSON.stringify({
+            error: {
+                code: "unknown_command",
+                message: `unknown command '${noun}' — run 'homespun --help'`,
+            },
+        }) + "\n");
+        process.exit(1);
+    }
+    // `homespun <noun> --help` with no verb prints the noun-level help. A verb-level
+    // --help is the responsibility of each runner (e.g. runApp dispatches to
+    // the verb runner which reads its own xxxHelp). This pre-empt only fires
+    // when --help is the FIRST positional-equivalent — i.e. no verb given.
+    if (args.bools.has("help") && args.positionals.length === 0) {
+        process.stdout.write(helps[noun] + "\n");
+        return;
+    }
+    switch (noun) {
+        case "key":
+            await runKey(args);
+            break;
+        case "taste":
+            await runTaste(args);
+            break;
+        case "feedback":
+            await runFeedback(args);
+            break;
+        case "attachment":
+            await runBlob(args);
+            break;
+        case "agent":
+            await runAgent(args);
+            break;
+        case "config":
+            await runConfig(args);
+            break;
+        case "skill":
+            await runSkill(args);
+            break;
+        case "deploy":
+            await runDeploy(args);
+            break;
+        case "apps":
+            await runApps(args);
+            break;
+        case "data":
+            await runData(args);
+            break;
+        case "members":
+            await runMembers(args);
+            break;
+    }
+}
+main().catch((err) => {
+    // ArgvError thrown from a runner (e.g. assertKnownFlags) reaches here —
+    // funnel it through the same invalid_args envelope as the parse-time path
+    // so unknown-flag rejection looks identical no matter which layer caught
+    // the user error.
+    if (err instanceof ArgvError) {
+        failArgvError(err);
+    }
+    // Funnel 426 cli_upgrade_required through the dedicated upgrade-message
+    // path so a command that throws raw (instead of going through
+    // failFromError) still produces the exact stderr block + exit 75 the
+    // SKILL.md tells the agent's harness to expect.
+    if (err instanceof HomespunApiError &&
+        err.code === "cli_upgrade_required" &&
+        err.status === 426) {
+        failUpgradeRequired(err);
+    }
+    process.stderr.write(JSON.stringify({
+        error: {
+            code: "internal",
+            message: err instanceof Error ? err.message : String(err),
+        },
+    }) + "\n");
+    process.exit(1);
+});

package/dist/input.js

@@ -0,0 +1,42 @@
+// Helpers for reading CLI inputs that may be either a file path or an inline
+// literal (JSON, or raw text for an HTML template body).
+import { readFileSync, statSync } from "node:fs";
+/**
+ * True if `value` names an existing file. Only a missing path (ENOENT) is
+ * treated as "not a file" — any other fs error (EACCES, ELOOP, …) propagates
+ * with a labeled message rather than being misreported as inline content.
+ */
+function isFilePath(value) {
+    try {
+        return statSync(value).isFile();
+    }
+    catch (e) {
+        if (e &&
+            typeof e === "object" &&
+            e.code === "ENOENT") {
+            return false;
+        }
+        const code = e && typeof e === "object" ? e.code : undefined;
+        throw new Error(`cannot stat '${value}'${code ? ` (${code})` : ""}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+}
+/**
+ * Resolve a value that is either a file path or an inline JSON literal.
+ * Returns the parsed JSON. Throws on parse failure.
+ */
+export function resolveJson(value, label) {
+    const raw = isFilePath(value) ? readFileSync(value, "utf8") : value;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${label}: not valid JSON (${e instanceof Error ? e.message : String(e)})`, { cause: e });
+    }
+}
+/**
+ * Resolve raw text that is either a file path or an inline literal — no JSON
+ * parsing. Used for an inline HTML template body.
+ */
+export function resolveText(value) {
+    return isFilePath(value) ? readFileSync(value, "utf8") : value;
+}

package/dist/output.js

@@ -0,0 +1,77 @@
+// stdout/stderr helpers. The CLI is JSON-by-default: machine-readable on
+// stdout, human errors on stderr.
+import { HomespunApiError } 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 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
+ * immediately, one event per line.
+ */
+export function printJsonLine(value) {
+    process.stdout.write(JSON.stringify(value) + "\n");
+}
+/** Print an error envelope to stderr and exit non-zero. */
+export function fail(message, code = "error", details, extra) {
+    const error = { code, message };
+    if (extra?.hint !== undefined)
+        error["hint"] = extra.hint;
+    if (extra?.retryable !== undefined)
+        error["retryable"] = extra.retryable;
+    if (extra?.docs_url !== undefined)
+        error["docs_url"] = extra.docs_url;
+    if (details !== undefined)
+        error["details"] = details;
+    process.stderr.write(JSON.stringify({ error }) + "\n");
+    process.exit(1);
+}
+/** Translate a thrown error (incl. HomespunApiError) into a fail() exit. */
+export function failFromError(err) {
+    // 426 cli_upgrade_required gets its own dedicated exit path: a
+    // human-readable upgrade message on stderr and a stable exit code
+    // (sysexits EX_TEMPFAIL = 75) that the SKILL.md instructs the agent's
+    // harness to branch on. Everything else falls through to the generic
+    // JSON envelope below.
+    if (err instanceof HomespunApiError &&
+        err.code === "cli_upgrade_required" &&
+        err.status === 426) {
+        failUpgradeRequired(err);
+    }
+    if (err instanceof HomespunApiError) {
+        fail(err.message, err.code, err.details, {
+            hint: err.hint,
+            retryable: err.retryable,
+            docs_url: err.docsUrl,
+        });
+    }
+    fail(err instanceof Error ? err.message : String(err), "internal");
+}
+/**
+ * Print the upgrade message to stderr and exit 75. Pulled out of
+ * failFromError so the top-level main().catch can also funnel through it
+ * — the two entry points must produce identical output for the SKILL.md's
+ * "if you see exit 75…" instructions to be reliable.
+ *
+ * The install-method detection reads `import.meta.url` of the CLI entry,
+ * resolved from the call site that imports this module. Inlining the
+ * resolution here keeps each command's own error-handling free of the
+ * detail.
+ */
+export function failUpgradeRequired(err) {
+    // The CLI entry is packages/cli/dist/index.js (after build) or
+    // packages/cli/src/index.ts (when running from source via tsx). Either
+    // way, the detector only looks at the path's shape, so resolving from
+    // *this* file works — output.ts sits alongside index.ts/index.js in
+    // both layouts.
+    const entryPath = fileURLToPath(import.meta.url);
+    const method = detectInstallMethod(entryPath);
+    const details = (err.details ?? {});
+    const minVersion = typeof details.min_version === "string" ? details.min_version : "0.0.0";
+    const command = upgradeCommandFor(method, minVersion);
+    process.stderr.write(formatUpgradeMessage(err, method, command) + "\n");
+    process.exit(EXIT_CLI_UPGRADE_REQUIRED);
+}

package/dist/resolve-app.js

@@ -0,0 +1,51 @@
+// Shared `<app>` resolution for every v2 CLI noun (`apps`, `data`, `deploy
+// --app`): accepts either the App.id (cuid) or its slug, resolving a slug to
+// an id via `GET /v1/apps?slug=` — spec-cli §3.2's "the single ergonomic
+// concession beyond the raw /v1 shape."
+import { HomespunApiError } from "@homespunapps/core";
+import { fail } from "./output.js";
+// cuid2 ids (Prisma's `@default(cuid())`) are lowercase alphanumeric,
+// starting with a letter, 24+ chars. A slug is DNS-label-shaped (spec-schema
+// §6 ruling 8) and always contains at least one hyphen in practice
+// (`<adjective>-<noun>-<suffix>` for generated ones, or a short owner-chosen
+// word) — but the deciding heuristic here is simply "looks like a cuid";
+// anything else is treated as a slug and resolved via a lookup.
+//
+// This is a heuristic, NOT a proof: `public`/`private` apps allow any
+// DNS-label-shaped owner-chosen slug (app-slug.ts's SLUG_RX), hyphens
+// optional, so a 21+-char hyphen-free slug also matches CUID_RX. Rather than
+// trust the shape alone, `resolveAppId` below verifies an id-shaped value
+// against `GET /v1/apps/:id` and falls back to the slug lookup on a 404 —
+// so a legit slug always resolves regardless of how it happens to be shaped.
+const CUID_RX = /^[a-z][a-z0-9]{20,}$/;
+function looksLikeId(value) {
+    return CUID_RX.test(value);
+}
+/**
+ * Resolve a CLI-supplied `<app>` positional to an App.id. Values that look
+ * like a cuid are tried as-is via `GET /v1/apps/:id` first (the fast, common
+ * path); if that 404s — e.g. an owner-chosen slug that happens to be
+ * hyphen-free and 21+ chars, matching the cuid heuristic — falls back to
+ * `GET /v1/apps?slug=`. Values that don't look like a cuid skip straight to
+ * the slug lookup. Fails with `app_not_found` if no app matches either way.
+ */
+export async function resolveAppId(client, value) {
+    if (looksLikeId(value)) {
+        try {
+            await client.getApp(value);
+            return value;
+        }
+        catch (e) {
+            if (!(e instanceof HomespunApiError && e.code === "app_not_found")) {
+                throw e;
+            }
+            // Fall through: treat it as a slug instead.
+        }
+    }
+    const page = await client.listApps({ status: "all", slug: value, limit: 1 });
+    const match = page.items[0];
+    if (!match) {
+        fail(`no app found with slug '${value}'`, "app_not_found");
+    }
+    return match.id;
+}

package/dist/store.js

@@ -0,0 +1,205 @@
+// Persisted CLI config: ${XDG_CONFIG_HOME or ~/.config}/homespun/config.json.
+//
+// Holds one or more named profiles. Each profile is one agent identity on
+// one relay — (url, api_key). Switching profiles is the multi-environment
+// story: dev / staging / prod, or personal / work agents on the same relay,
+// without re-running `homespun agent register` between them.
+//
+// On-disk shape:
+//
+//   {
+//     "current_profile": "prod",
+//     "profiles": {
+//       "prod": { "url": "https://…", "api_key": "hs_…" },
+//       "dev":  { "url": "http://localhost:3000", "api_key": "hs_…" }
+//     }
+//   }
+//
+// Tiny and synchronous; no deps. Holds secrets — files written mode 0600.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+/**
+ * Default profile name when the user runs `homespun agent register` without
+ * `--profile` on a fresh install. Stable, predictable, and short enough to
+ * type in `homespun --profile default …` if needed.
+ */
+export const DEFAULT_PROFILE_NAME = "default";
+/** Profile-name validation (a-z, A-Z, 0-9, _ and -, 1..32 chars). */
+const PROFILE_NAME_RX = /^[A-Za-z0-9_-]{1,32}$/;
+export function isValidProfileName(name) {
+    return PROFILE_NAME_RX.test(name);
+}
+/** Absolute path to the config file (honours XDG_CONFIG_HOME). */
+export function storePath() {
+    const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim() !== ""
+        ? process.env.XDG_CONFIG_HOME
+        : join(homedir(), ".config");
+    return join(base, "homespun", "config.json");
+}
+/**
+ * Read the persisted config. Returns an empty store if the file is missing,
+ * unparseable, or doesn't carry a `profiles` object.
+ */
+export function readStore() {
+    let text;
+    try {
+        text = readFileSync(storePath(), "utf8");
+    }
+    catch {
+        return { profiles: {} };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { profiles: {} };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { profiles: {} };
+    }
+    const obj = parsed;
+    if (!obj["profiles"] || typeof obj["profiles"] !== "object") {
+        return { profiles: {} };
+    }
+    const rawProfiles = obj["profiles"];
+    const profiles = {};
+    for (const [name, raw] of Object.entries(rawProfiles)) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const p = raw;
+        const profile = {};
+        if (typeof p["url"] === "string")
+            profile.url = p["url"];
+        if (typeof p["api_key"] === "string")
+            profile.apiKey = p["api_key"];
+        profiles[name] = profile;
+    }
+    const currentProfile = typeof obj["current_profile"] === "string"
+        ? obj["current_profile"]
+        : undefined;
+    // If the named current profile was deleted out-of-band, drop it back to
+    // undefined so the resolver can fall through to env / default URL.
+    return {
+        currentProfile: currentProfile && profiles[currentProfile] !== undefined
+            ? currentProfile
+            : undefined,
+        profiles,
+    };
+}
+/** Serialise a Store to the on-disk JSON shape (snake_case fields). */
+function serialize(store) {
+    const profilesOut = {};
+    for (const [name, p] of Object.entries(store.profiles)) {
+        const o = {};
+        if (p.url !== undefined)
+            o["url"] = p.url;
+        if (p.apiKey !== undefined)
+            o["api_key"] = p.apiKey;
+        profilesOut[name] = o;
+    }
+    const body = { profiles: profilesOut };
+    if (store.currentProfile !== undefined) {
+        body["current_profile"] = store.currentProfile;
+    }
+    return JSON.stringify(body, null, 2) + "\n";
+}
+/**
+ * Atomically write the whole Store to disk. The file is created with mode
+ * 0600 and the parent directory is created as needed.
+ */
+export function writeStoreFull(store) {
+    const path = storePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serialize(store), { mode: 0o600 });
+    // Ensure mode even when the file pre-existed with looser permissions.
+    chmodSync(path, 0o600);
+    return path;
+}
+/**
+ * Upsert a single profile and write back. If `setCurrent` is true, the
+ * profile becomes the active one. If the store had no current profile yet
+ * (empty store), the newly-written profile becomes current regardless —
+ * there's no other choice that makes sense.
+ */
+export function upsertProfile(name, patch, setCurrent = false) {
+    if (!isValidProfileName(name)) {
+        throw new Error(`invalid profile name '${name}' — must match ${PROFILE_NAME_RX} (letters, digits, underscore, dash; 1..32 chars)`);
+    }
+    const store = readStore();
+    const merged = { ...(store.profiles[name] ?? {}), ...patch };
+    store.profiles[name] = merged;
+    if (setCurrent || store.currentProfile === undefined) {
+        store.currentProfile = name;
+    }
+    return writeStoreFull(store);
+}
+/**
+ * Set the active profile by name. Throws if `name` is not in the store.
+ * Use `upsertProfile` if you also want to create it.
+ */
+export function setCurrentProfile(name) {
+    const store = readStore();
+    if (store.profiles[name] === undefined) {
+        throw new Error(`profile '${name}' does not exist — run 'homespun config list' to see available profiles`);
+    }
+    store.currentProfile = name;
+    return writeStoreFull(store);
+}
+/**
+ * Remove a profile. If it was current, drop `current_profile` (the resolver
+ * falls through to env / default URL). If the resulting store is empty,
+ * delete the file entirely so a `readStore` looks identical to "fresh".
+ * Returns `{ path, was_current }`. Throws if the profile doesn't exist.
+ */
+export function removeProfile(name) {
+    const store = readStore();
+    if (store.profiles[name] === undefined) {
+        throw new Error(`profile '${name}' does not exist`);
+    }
+    const wasCurrent = store.currentProfile === name;
+    delete store.profiles[name];
+    if (wasCurrent) {
+        store.currentProfile = undefined;
+    }
+    if (Object.keys(store.profiles).length === 0) {
+        // Empty store → delete the file so a subsequent register starts fresh.
+        return { path: clearStore(), was_current: wasCurrent };
+    }
+    return { path: writeStoreFull(store), was_current: wasCurrent };
+}
+/**
+ * Delete the persisted config file entirely. Idempotent — no error if the
+ * file never existed. Returns the path it targeted. Used by
+ * `homespun agent logout --all` and `removeProfile` when it drains the last
+ * profile.
+ */
+export function clearStore() {
+    const path = storePath();
+    rmSync(path, { force: true });
+    return path;
+}
+/**
+ * Resolve which profile to load from the store, given the optional selector
+ * (`--profile` flag or `HOMESPUN_PROFILE` env). Returns `null` if no profile
+ * matches — i.e. the caller should fall through to env / default-URL
+ * resolution. Throws if `selector` was explicit (truthy) and not found, so
+ * a typo in `--profile dev` doesn't silently fall back to the wrong relay.
+ */
+export function resolveProfile(store, selector) {
+    if (selector !== undefined && selector !== "") {
+        const p = store.profiles[selector];
+        if (p === undefined) {
+            const known = Object.keys(store.profiles).sort().join(", ") || "(none)";
+            throw new Error(`profile '${selector}' does not exist (known: ${known}) — run 'homespun config list'`);
+        }
+        return { name: selector, profile: p };
+    }
+    if (store.currentProfile !== undefined) {
+        const p = store.profiles[store.currentProfile];
+        if (p !== undefined)
+            return { name: store.currentProfile, profile: p };
+    }
+    return null;
+}