@homespunapps/cli 1.0.0

package/dist/commands/config.js

@@ -0,0 +1,262 @@
+// `homespun config <verb>` — inspect and manage the multi-profile CLI config.
+//
+//   show              describe the resolved (url, api_key) the CLI would use
+//   list              list saved profiles (names + URLs + current marker)
+//   use <name>        switch the active profile
+//   add <name>        manually add a profile (for keys obtained out of band)
+//   rm <name>         delete a profile
+//
+// All four mutating verbs operate on the multi-profile store at
+// $XDG_CONFIG_HOME/homespun/config.json. See store.ts for the layout. They make
+// NO network calls — purely local config management.
+import { assertKnownFlags } from "../argv.js";
+import { describeConfig } from "../config.js";
+import { isValidProfileName, readStore, removeProfile, setCurrentProfile, storePath, upsertProfile, } from "../store.js";
+import { printJson, fail } from "../output.js";
+const SHOW_FLAGS = [];
+const SHOW_BOOLS = [];
+const LIST_FLAGS = [];
+const LIST_BOOLS = [];
+const USE_FLAGS = [];
+const USE_BOOLS = [];
+const ADD_FLAGS = ["api-key"];
+const ADD_BOOLS = [];
+const RM_FLAGS = [];
+const RM_BOOLS = [];
+export const configHelp = `homespun config — show and manage the CLI config (multi-profile)
+
+Usage:
+  homespun config show                      Show the resolved relay config
+  homespun config list                      List saved profiles
+  homespun config use <profile>             Switch the active profile
+  homespun config add <profile> --url <u> --api-key <k>
+                                        Add a profile manually
+  homespun config rm <profile>              Delete a profile
+
+A profile is one (url, api_key) pair under a short name (dev, staging, prod).
+Switch via 'homespun config use', '--profile <name>', or the HOMESPUN_PROFILE env var.
+The active profile's (url, api_key) is what every other command sees unless
+overridden by --url / --api-key or HOMESPUN_URL / HOMESPUN_API_KEY.
+
+Run \`homespun config <verb> --help\` for verb-specific help. The full API key is
+never printed; only a short masked prefix.
+
+The config file lives at \${XDG_CONFIG_HOME:-~/.config}/homespun/config.json
+(mode 0600).`;
+const showHelp = `homespun config show — show the resolved relay config
+
+Usage:
+  homespun config show [options]
+
+Reports the (url, api_key) the CLI would use right now, and where each value
+came from (flag / env / profile / none). Purely inspects flags + env + the
+saved config file; makes NO network call.
+
+The API key is never printed in full — only a short masked prefix.
+
+Options:
+  --url <url>         Relay base URL (overrides HOMESPUN_URL) — affects the report.
+  --api-key <key>     Agent API key (overrides HOMESPUN_API_KEY) — affects the report.
+  --profile <name>    Profile to resolve against — affects the report.
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  {
+    url, url_source,        flag | env | profile | none
+    key_prefix, key_source, flag | env | profile | none
+    profile, profile_source,  active profile name + how it was chosen
+    config_path
+  }`;
+const listHelp = `homespun config list — list saved profiles
+
+Usage:
+  homespun config list [options]
+
+Prints every profile in the local config file, with its URL and a masked
+key prefix. The active profile carries 'current: true'.
+
+Options:
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  {
+    current: <name|null>,
+    profiles: [ { name, url, key_prefix, current }, … ],
+    config_path
+  }`;
+const useHelp = `homespun config use <profile> — switch the active profile
+
+Usage:
+  homespun config use <profile>
+
+Sets 'current_profile' in the config file. The named profile must exist
+(create it first with 'homespun agent register --profile <name>' or
+'homespun config add <name>').
+
+Options:
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { profile, saved_to }`;
+const addHelp = `homespun config add <profile> — add a profile manually
+
+Usage:
+  homespun config add <profile> --url <url> --api-key <api-key>
+
+Saves a (url, api_key) pair under <profile> without contacting the relay.
+Use this when an operator handed you an API key out of band (e.g. a closed-
+registration relay) — for self-register and secret-mode relays, prefer
+'homespun agent register --profile <name>'.
+
+If <profile> already exists, the existing values are overwritten.
+
+Options:
+  --url <url>         Relay base URL.            REQUIRED.
+  --api-key <key>     Agent API key.             REQUIRED.
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { profile, saved_to }
+
+Does NOT change 'current_profile' unless this is the first profile being
+added. Use 'homespun config use' afterwards to switch.`;
+const rmHelp = `homespun config rm <profile> — delete a profile
+
+Usage:
+  homespun config rm <profile>
+
+Removes the named profile from the config file. If it was the active profile,
+'current_profile' is cleared (the next command falls back to env / default
+URL until another profile is selected via --profile or 'homespun config use').
+
+Options:
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { profile, was_current, path }`;
+async function runConfigShow(args) {
+    assertKnownFlags(args, SHOW_FLAGS, SHOW_BOOLS, "homespun config show");
+    printJson(describeConfig(args));
+}
+function maskKey(key) {
+    if (!key)
+        return null;
+    if (key.startsWith("hs_") && key.length >= 9)
+        return key.slice(0, 9) + "…";
+    return key.slice(0, 8) + "…";
+}
+async function runConfigList(args) {
+    assertKnownFlags(args, LIST_FLAGS, LIST_BOOLS, "homespun config list");
+    const store = readStore();
+    const profiles = Object.entries(store.profiles)
+        .map(([name, p]) => ({
+        name,
+        url: p.url ?? null,
+        key_prefix: maskKey(p.apiKey),
+        current: name === store.currentProfile,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    printJson({
+        current: store.currentProfile ?? null,
+        profiles,
+        config_path: storePath(),
+    });
+}
+async function runConfigUse(args) {
+    assertKnownFlags(args, USE_FLAGS, USE_BOOLS, "homespun config use");
+    const name = args.positionals[1];
+    if (!name) {
+        fail("missing profile name — usage: homespun config use <profile>", "invalid_args");
+    }
+    let savedTo;
+    try {
+        savedTo = setCurrentProfile(name);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
+    printJson({ profile: name, saved_to: savedTo });
+}
+async function runConfigAdd(args) {
+    assertKnownFlags(args, ADD_FLAGS, ADD_BOOLS, "homespun config add");
+    const name = args.positionals[1];
+    if (!name) {
+        fail("missing profile name — usage: homespun config add <profile> --url <url> --api-key <key>", "invalid_args");
+    }
+    if (!isValidProfileName(name)) {
+        fail(`invalid profile name '${name}' — letters, digits, _ and -, up to 32 chars`, "invalid_args");
+    }
+    const url = args.flags.get("url");
+    const apiKey = args.flags.get("api-key");
+    if (!url) {
+        fail("--url is required — usage: homespun config add <profile> --url <url> --api-key <key>", "invalid_args");
+    }
+    if (!apiKey) {
+        fail("--api-key is required — usage: homespun config add <profile> --url <url> --api-key <key>", "invalid_args");
+    }
+    // setCurrent=false: adding a profile shouldn't silently switch the user
+    // off whatever they were on. They use `homespun config use` after to flip.
+    // EXCEPT: if there's no current profile yet (first add), upsertProfile
+    // sets it automatically — that's the correct fresh-install behaviour.
+    const savedTo = upsertProfile(name, { url: url.replace(/\/$/, ""), apiKey }, false);
+    printJson({ profile: name, saved_to: savedTo });
+}
+async function runConfigRm(args) {
+    assertKnownFlags(args, RM_FLAGS, RM_BOOLS, "homespun config rm");
+    const name = args.positionals[1];
+    if (!name) {
+        fail("missing profile name — usage: homespun config rm <profile>", "invalid_args");
+    }
+    let result;
+    try {
+        result = removeProfile(name);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
+    printJson({
+        profile: name,
+        was_current: result.was_current,
+        path: result.path,
+    });
+}
+export async function runConfig(args) {
+    const verb = args.positionals[0];
+    // Per-verb --help: 'homespun config show --help' etc. Caught before dispatch
+    // so each runner doesn't need to repeat the check.
+    if (args.bools.has("help") && verb !== undefined) {
+        const helps = {
+            show: showHelp,
+            list: listHelp,
+            use: useHelp,
+            add: addHelp,
+            rm: rmHelp,
+        };
+        if (helps[verb] !== undefined) {
+            process.stdout.write(helps[verb] + "\n");
+            return;
+        }
+    }
+    switch (verb) {
+        case "show":
+            await runConfigShow(args);
+            break;
+        case "list":
+            await runConfigList(args);
+            break;
+        case "use":
+            await runConfigUse(args);
+            break;
+        case "add":
+            await runConfigAdd(args);
+            break;
+        case "rm":
+            await runConfigRm(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: homespun config <show|list|use|add|rm> (run 'homespun config --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown config verb '${verb}' — expected show|list|use|add|rm (run 'homespun config --help')`, "invalid_args");
+    }
+}

package/dist/commands/data.js

@@ -0,0 +1,168 @@
+// `homespun data` — collection row CRUD for a v2 app (spec-cli §3.3). Mirrors
+// `homespun records` (v1 app collections) but against `/v1/apps/:id/collections`
+// and with a dedicated per-row GET (no client-side scan — spec-cli §8 ruling
+// 3 confirms the relay route is real).
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+import { resolveJson } from "../input.js";
+import { resolveAppId } from "../resolve-app.js";
+export const dataHelp = `homespun data — collection row CRUD for a v2 app
+
+Usage:
+  homespun data <app> <collection> list   [--since <cursor>] [--limit <n>]
+  homespun data <app> <collection> get    <key>
+  homespun data <app> <collection> upsert --data <path|json> [--key <key>]
+  homespun data <app> <collection> update <key> --data <path|json> [--if-match <version>]
+  homespun data <app> <collection> delete <key> [--if-match <version>] [--yes]
+
+<app> accepts either the app_id or its slug. upsert is the ONLY create-shaped
+verb (spec-cli §8 ruling 4): omit --key to add a new row (server-generates
+the key); pass --key to ensure a row exists at that key (returns the
+existing row with deduped:true on a collision, never errors).
+
+Output (stdout, single JSON). Errors on stderr:
+{"error":{"code","message"}} with non-zero exit.`;
+export async function runData(args) {
+    const appArg = args.positionals[0];
+    const collection = args.positionals[1];
+    const verb = args.positionals[2];
+    if ((appArg === undefined || verb === undefined) && args.bools.has("help")) {
+        process.stdout.write(dataHelp + "\n");
+        return;
+    }
+    if (!appArg || !collection || !verb) {
+        fail("usage: homespun data <app> <collection> <list|get|upsert|update|delete>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(3),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "list":
+            return runList(appArg, collection, sub);
+        case "get":
+            return runGet(appArg, collection, sub);
+        case "upsert":
+            return runUpsert(appArg, collection, sub);
+        case "update":
+            return runUpdate(appArg, collection, sub);
+        case "delete":
+            return runDelete(appArg, collection, sub);
+        default:
+            fail(`unknown verb '${verb}' — homespun data <app> <collection> <list|get|upsert|update|delete>`, "invalid_args");
+    }
+}
+function parseIntFlag(args, name, defaultValue, bounds = {}) {
+    const raw = args.flags.get(name);
+    if (raw === undefined)
+        return defaultValue;
+    const n = Number(raw);
+    if (!Number.isInteger(n))
+        fail(`--${name} must be an integer`, "invalid_args");
+    if (bounds.min !== undefined && n < bounds.min) {
+        fail(`--${name} must be >= ${bounds.min}`, "invalid_args");
+    }
+    if (bounds.max !== undefined && n > bounds.max) {
+        fail(`--${name} must be <= ${bounds.max}`, "invalid_args");
+    }
+    return n;
+}
+async function runList(appArg, collection, args) {
+    assertKnownFlags(args, ["since", "limit", "url", "api-key"], ["help"], "homespun data list");
+    const since = args.flags.get("since");
+    const limit = parseIntFlag(args, "limit", undefined, { min: 1, max: 1000 });
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listAppRows(appId, collection, {
+            since,
+            ...(limit !== undefined ? { limit } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runGet(appArg, collection, args) {
+    assertKnownFlags(args, ["url", "api-key"], ["help"], "homespun data get");
+    const key = args.positionals[0];
+    if (!key) {
+        fail("usage: homespun data <app> <collection> get <key>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.getAppRow(appId, collection, key));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runUpsert(appArg, collection, args) {
+    assertKnownFlags(args, ["data", "key", "url", "api-key"], ["help"], "homespun data upsert");
+    const dataRaw = args.flags.get("data");
+    if (dataRaw === undefined) {
+        fail("--data is required (path to JSON file, or inline JSON)", "invalid_args");
+    }
+    const data = resolveJson(dataRaw, "--data");
+    const key = args.flags.get("key");
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        const body = { data };
+        if (key !== undefined)
+            body.key = key;
+        printJson(await client.upsertAppRow(appId, collection, body));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runUpdate(appArg, collection, args) {
+    assertKnownFlags(args, ["data", "if-match", "url", "api-key"], ["help"], "homespun data update");
+    const key = args.positionals[0];
+    if (!key) {
+        fail("usage: homespun data <app> <collection> update <key> --data <path|json>", "invalid_args");
+    }
+    const dataRaw = args.flags.get("data");
+    if (dataRaw === undefined) {
+        fail("--data is required (path to JSON file, or inline JSON)", "invalid_args");
+    }
+    const data = resolveJson(dataRaw, "--data");
+    const ifMatch = parseIntFlag(args, "if-match", undefined, { min: 0 });
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        const body = { data };
+        if (ifMatch !== undefined)
+            body.if_match = ifMatch;
+        printJson(await client.updateAppRow(appId, collection, key, body));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runDelete(appArg, collection, args) {
+    assertKnownFlags(args, ["if-match", "url", "api-key"], ["yes", "help"], "homespun data delete");
+    const key = args.positionals[0];
+    if (!key) {
+        fail("usage: homespun data <app> <collection> delete <key>", "invalid_args");
+    }
+    const ifMatch = parseIntFlag(args, "if-match", undefined, { min: 0 });
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        await client.deleteAppRow(appId, collection, key, {
+            ...(ifMatch !== undefined ? { ifMatch } : {}),
+        });
+        printJson({ deleted: true, key });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/deploy.js

@@ -0,0 +1,136 @@
+// `homespun deploy` — create or redeploy an App (spec-cli §3.1). This is the
+// create->redeploy loop the v2 vision names: no `--app` creates a new App;
+// `--app <id>` redeploys an existing one (compat-gated unless --force).
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { makeClient } from "../config.js";
+import { assertKnownFlags } from "../argv.js";
+import { fail, failFromError, printJson } from "../output.js";
+import { resolveJson } from "../input.js";
+import { resolveAppId } from "../resolve-app.js";
+const KNOWN_FLAGS = ["app", "manifest", "slug", "visibility"];
+const KNOWN_BOOLS = ["force"];
+export const deployHelp = `homespun deploy — create or redeploy an app
+
+Usage:
+  homespun deploy <dir|file> [--app <id>] [--manifest <path|json>]
+              [--slug <slug>] [--visibility private|link|public] [--force]
+
+Packaging (one canonical shape, one escape hatch):
+  Directory (canonical):  homespun deploy ./my-app
+    Reads ./my-app/index.html and ./my-app/manifest.json — fixed filenames,
+    no discovery heuristics. Both files are required.
+  Single file (escape hatch):  homespun deploy ./index.html --manifest ./manifest.json
+    --manifest accepts a file path OR inline JSON.
+
+Create vs. redeploy — decided by --app's presence, not two verbs:
+  (no --app)     Create (POST /v1/apps). New apps default to private
+                 (owner plus invited members, sign-in gated). --slug is
+                 accepted with private or public visibility, including the
+                 default; an explicit --visibility link always gets a
+                 server-generated slug and rejects --slug.
+  --app <id>     Redeploy (POST /v1/apps/:id/versions). --slug/--visibility
+                 are rejected here (slug is immutable; change visibility via
+                 'homespun apps update'). --force overrides the compat gate.
+
+Output: { app_id, slug, url, version, visibility, created, compat?, breaks? }
+Errors on stderr: {"error":{"code","message"}} with non-zero exit.`;
+function readBundle(source, manifestFlag) {
+    if (!existsSync(source)) {
+        fail(`no such file or directory: ${source}`, "invalid_args");
+    }
+    const st = statSync(source);
+    if (st.isDirectory()) {
+        if (manifestFlag !== undefined) {
+            fail("--manifest is only for the single-file escape hatch — a directory deploy reads <dir>/manifest.json", "invalid_args");
+        }
+        const htmlPath = join(source, "index.html");
+        const manifestPath = join(source, "manifest.json");
+        const missing = [];
+        if (!existsSync(htmlPath))
+            missing.push("index.html");
+        if (!existsSync(manifestPath))
+            missing.push("manifest.json");
+        if (missing.length > 0) {
+            fail(`directory deploy is missing required file(s): ${missing.join(", ")}`, "invalid_args");
+        }
+        return {
+            html: readFileSync(htmlPath, "utf8"),
+            manifest: JSON.parse(readFileSync(manifestPath, "utf8")),
+        };
+    }
+    // Single-file escape hatch.
+    if (manifestFlag === undefined) {
+        fail("single-file deploy requires --manifest <path|json>", "invalid_args");
+    }
+    return {
+        html: readFileSync(source, "utf8"),
+        manifest: resolveJson(manifestFlag, "--manifest"),
+    };
+}
+export async function runDeploy(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun deploy");
+    const source = args.positionals[0];
+    if (!source) {
+        fail("usage: homespun deploy <dir|file> [--app <id>] ...", "invalid_args");
+    }
+    const appId = args.flags.get("app");
+    const slug = args.flags.get("slug");
+    const visibility = args.flags.get("visibility");
+    if (visibility !== undefined &&
+        !["private", "link", "public"].includes(visibility)) {
+        fail("--visibility must be private|link|public", "invalid_args");
+    }
+    const force = args.bools.has("force");
+    const bundle = readBundle(source, args.flags.get("manifest"));
+    const client = makeClient(args);
+    if (appId === undefined) {
+        // Create. Client-side mirror of the relay's slug_not_allowed_for_link —
+        // fail fast rather than round-trip a request that will 400 (spec-cli §3.1).
+        if (slug !== undefined && visibility === "link") {
+            fail("a caller-supplied --slug is not allowed with visibility 'link' (link slugs are always server-generated); drop --visibility link, or omit --slug", "invalid_args");
+        }
+        try {
+            const out = await client.deployApp({
+                html: bundle.html,
+                manifest: bundle.manifest,
+                visibility,
+                slug,
+            });
+            printJson(out);
+        }
+        catch (e) {
+            failFromError(e);
+        }
+        return;
+    }
+    // Redeploy. slug/visibility are immutable here.
+    if (slug !== undefined) {
+        fail("--slug cannot be changed on redeploy (slug is immutable) — omit --app to create a new app instead", "invalid_args");
+    }
+    if (visibility !== undefined) {
+        fail("--visibility cannot be changed on redeploy — use 'homespun apps update --visibility' instead", "invalid_args");
+    }
+    const id = await resolveAppId(client, appId);
+    try {
+        const redeployed = await client.redeployApp(id, {
+            html: bundle.html,
+            manifest: bundle.manifest,
+            force,
+        });
+        const app = await client.getApp(id);
+        printJson({
+            app_id: redeployed.app_id,
+            slug: app.slug,
+            url: app.url,
+            version: redeployed.version,
+            visibility: app.visibility,
+            created: false,
+            compat: redeployed.compat,
+            ...(redeployed.breaks ? { breaks: redeployed.breaks } : {}),
+        });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}