@homespunapps/cli 1.0.0 → 1.4.2

package/dist/index.js

@@ -9,7 +9,8 @@
 // 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";
+import { parseArgs, ArgvError, BOOLEAN_FLAGS } from "./argv.js";
+import { nounSpec, renderNounHelp, renderRootHelp } from "./help-catalog.js";
 /**
  * Translate an ArgvError into the canonical `invalid_args` envelope and exit
  * non-zero. The parser throws ArgvError up-front; assertKnownFlags throws it
@@ -25,92 +26,25 @@ function failArgvError(e) {
     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 { runAgent } from "./commands/agent.js";
+import { runKey } from "./commands/key.js";
+import { runTaste } from "./commands/taste.js";
+import { runFeedback } from "./commands/feedback.js";
+import { runConfig } from "./commands/config.js";
+import { runBlob } from "./commands/attachment.js";
+import { runSkill } from "./commands/skill.js";
+import { runDeploy } from "./commands/deploy.js";
+import { runApps } from "./commands/apps.js";
+import { runData } from "./commands/data.js";
+import { runMembers } from "./commands/members.js";
+import { runGrant } from "./commands/grant.js";
+import { runIngest } from "./commands/ingest.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",
-]);
+// BOOLEAN_FLAGS (flags that never take a value) lives in argv.ts next to the
+// parser that consumes it, and is exported so tests parse with the real set
+// instead of a per-test copy that can drift (#827).
 async function main() {
     const rawArgv = process.argv.slice(2);
     // Version: handle before anything else.
@@ -124,7 +58,7 @@ async function main() {
         noun === "-h" ||
         noun === "--help" ||
         noun === "help") {
-        process.stdout.write(ROOT_HELP + "\n");
+        process.stdout.write(renderRootHelp() + "\n");
         return;
     }
     let args;
@@ -137,20 +71,8 @@ async function main() {
         }
         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)) {
+    const spec = nounSpec(noun);
+    if (!spec) {
         process.stderr.write(JSON.stringify({
             error: {
                 code: "unknown_command",
@@ -164,7 +86,7 @@ async function main() {
     // 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");
+        process.stdout.write(renderNounHelp(spec) + "\n");
         return;
     }
     switch (noun) {
@@ -201,6 +123,12 @@ async function main() {
         case "members":
             await runMembers(args);
             break;
+        case "grants":
+            await runGrant(args);
+            break;
+        case "ingest":
+            await runIngest(args);
+            break;
     }
 }
 main().catch((err) => {

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.4.2",
   "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://docs.homespun.dev",
   "bugs": {
-    "url": "https://github.com/aerolalit/homespun/issues"
+    "url": "https://github.com/homespunapps/homespun/issues"
   },
   "engines": {
     "node": ">=20"
@@ -41,13 +36,18 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.0.0",
+    "@homespunapps/core": "^1.4.2",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.1.1",
     "@types/qrcode-terminal": "^0.12.2",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/homespunapps/homespun.git",
+    "directory": "packages/cli"
   }
 }