@homespunapps/cli 1.6.48 → 1.6.49

package/dist/argv.js

@@ -63,6 +63,10 @@ export const BOOLEAN_FLAGS = new Set([
     // `homespun template publish --attest-example-only`: attest the captured template
     // and its seed rows carry no real personal data (marketplace PR 10).
     "attest-example-only",
+    // `homespun template upgrade --accept-permissions`: accept that the new version
+    // of a template asks for more than the installed one (#1502). Required when it
+    // does; it never clears an update that would strand rows.
+    "accept-permissions",
     // `homespun review respond --clear`: clear a publisher response (sends null).
     "clear",
     // `homespun credentials mint --no-expiry`: the explicit opt-in to NO EXPIRY

package/dist/commands/config.js

@@ -14,6 +14,7 @@ import { specFor } from "../help-catalog.js";
 import { describeConfig } from "../config.js";
 import { isValidProfileName, readStore, removeProfile, setCurrentProfile, storePath, upsertProfile, } from "../store.js";
 import { printJson, fail } from "../output.js";
+import { resolveSecretFlag } from "../input.js";
 const showHelp = `homespun config show — show the resolved relay config
 
 Usage:
@@ -83,7 +84,10 @@ If <profile> already exists, the existing values are overwritten.
 
 Options:
   --url <url>         Relay base URL.            REQUIRED.
-  --api-key <key>     Agent API key.             REQUIRED.
+  --api-key <key|->   Agent API key.              REQUIRED.
+                       Pass - to read it from stdin, or set
+                       HOMESPUN_CONFIG_API_KEY, instead of putting it on
+                       the command line where ps and shell history can see it.
   -h, --help          Show this help.
 
 Output (stdout, JSON):
@@ -158,7 +162,7 @@ async function runConfigAdd(args) {
         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");
+    const apiKey = await resolveSecretFlag(args.flags.get("api-key"), "HOMESPUN_CONFIG_API_KEY", "--api-key");
     if (!url) {
         fail("--url is required — usage: homespun config add <profile> --url <url> --api-key <key>", "invalid_args");
     }

package/dist/commands/connection.js

@@ -18,6 +18,7 @@ import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
 import { resolveAppId } from "../resolve-app.js";
+import { resolveSecretFlag } from "../input.js";
 export async function runConnection(args) {
     const verb = args.positionals[0];
     if ((verb === undefined || verb === "help") && args.bools.has("help")) {
@@ -88,7 +89,7 @@ async function runCreate(args) {
             const authorizeUrl = args.flags.get("authorize-url");
             const tokenEndpoint = args.flags.get("token-url");
             const clientId = args.flags.get("client-id");
-            const clientSecret = args.flags.get("client-secret");
+            const clientSecret = await resolveSecretFlag(args.flags.get("client-secret"), "HOMESPUN_CONNECTION_CLIENT_SECRET", "--client-secret");
             if (!authorizeUrl || !tokenEndpoint || !clientId || !clientSecret) {
                 fail("kind=oauth2 requires --authorize-url, --token-url, --client-id and --client-secret", "invalid_args");
             }
@@ -126,7 +127,7 @@ async function runCreate(args) {
             }));
             return;
         }
-        const headerValue = args.flags.get("header-value");
+        const headerValue = await resolveSecretFlag(args.flags.get("header-value"), "HOMESPUN_CONNECTION_HEADER_VALUE", "--header-value");
         if (!headerValue) {
             fail("--header-value is required for a static connection", "invalid_args");
         }

package/dist/commands/ingest.js

@@ -20,6 +20,7 @@ import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
 import { resolveAppId } from "../resolve-app.js";
+import { resolveSecretFlag } from "../input.js";
 export async function runIngest(args) {
     const verb = args.positionals[0];
     if ((verb === undefined || verb === "help") && args.bools.has("help")) {
@@ -125,7 +126,7 @@ async function runSigningSecretSet(args) {
     if (!appArg || !name) {
         fail("usage: homespun ingest signing-secret set --app <idOrSlug> --name <hookName> [--secret <value>] [--grace-seconds <n>]", "invalid_args");
     }
-    const secret = args.flags.get("secret");
+    const secret = await resolveSecretFlag(args.flags.get("secret"), "HOMESPUN_INGEST_SIGNING_SECRET", "--secret");
     const graceRaw = args.flags.get("grace-seconds");
     let graceSeconds;
     if (graceRaw !== undefined) {

package/dist/commands/template.js

@@ -19,7 +19,7 @@ export async function runTemplate(args) {
         return;
     }
     if (verb === undefined) {
-        fail("missing verb: homespun template <publish|unpublish|config-contract|install|list-pending|show|approve|reject>", "invalid_args");
+        fail("missing verb: homespun template <publish|unpublish|config-contract|install|upgrade-check|upgrade|revert|list-pending|show|approve|reject>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -38,6 +38,12 @@ export async function runTemplate(args) {
             return runConfigContract(sub);
         case "install":
             return runInstall(sub);
+        case "upgrade-check":
+            return runUpgradeCheck(sub);
+        case "upgrade":
+            return runUpgrade(sub);
+        case "revert":
+            return runRevert(sub);
         case "list-pending":
             return runListPending(sub);
         case "show":
@@ -47,7 +53,7 @@ export async function runTemplate(args) {
         case "reject":
             return runReject(sub);
         default:
-            fail(`unknown verb '${verb}' (homespun template <publish|unpublish|config-contract|install|list-pending|show|approve|reject>)`, "invalid_args");
+            fail(`unknown verb '${verb}' (homespun template <publish|unpublish|config-contract|install|upgrade-check|upgrade|revert|list-pending|show|approve|reject>)`, "invalid_args");
     }
 }
 function parseIntFlag(args, name, bounds = {}) {
@@ -244,3 +250,61 @@ async function runReject(args) {
         failFromError(e);
     }
 }
+// ---------------------------------------------------------------------------
+// upgrade-check / upgrade / revert (#1502)
+//
+// These take an APP, not a template ref. An installed template is a fork, so
+// the question is "is there a newer version of the template THIS app came
+// from", which only the app can answer.
+// ---------------------------------------------------------------------------
+async function runUpgradeCheck(args) {
+    assertKnownFlags(args, ...specFor("template", "upgrade-check"));
+    const appId = args.positionals[0];
+    if (!appId) {
+        fail("usage: homespun template upgrade-check <app>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.checkTemplateUpgrade(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runUpgrade(args) {
+    assertKnownFlags(args, ...specFor("template", "upgrade"));
+    const appId = args.positionals[0];
+    if (!appId) {
+        fail("usage: homespun template upgrade <app>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const expectVersion = args.flags.get("expect-version");
+    try {
+        printJson(await client.upgradeTemplate(appId, {
+            // Only ever true when the flag is present. An omitted flag must not
+            // satisfy the consent gate: the point of the gate is that somebody
+            // looked at what the new version is asking for.
+            ...(args.bools.has("accept-permissions")
+                ? { acceptPermissions: true }
+                : {}),
+            ...(expectVersion !== undefined ? { expectVersion } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runRevert(args) {
+    assertKnownFlags(args, ...specFor("template", "revert"));
+    const appId = args.positionals[0];
+    if (!appId) {
+        fail("usage: homespun template revert <app>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.revertTemplateUpgrade(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/help-catalog.js

@@ -477,8 +477,8 @@ const INGEST = {
                 },
                 {
                     name: "secret",
-                    value: "<value>",
-                    description: "set only: a provider-generated signing secret to store verbatim; omit to have the relay mint one (shown once)",
+                    value: "<value|->",
+                    description: "set only: a provider-generated signing secret to store verbatim; omit to have the relay mint one (shown once). Pass - to read it from stdin, or set HOMESPUN_INGEST_SIGNING_SECRET, instead of putting it on the command line where ps and shell history can see it",
                 },
                 {
                     name: "grace-seconds",
@@ -521,6 +521,7 @@ const INGEST = {
         "signing-secret manages a hook's OPT-IN signing secret, distinct from the URL secret above: it is what a provider (GitHub, Stripe, ...) HMACs the request body with. `set` without --secret mints one and returns { secret, fingerprint, setAt } with the value shown ONCE; `set --secret <value>` stores a provider-generated value verbatim and returns { fingerprint, setAt } without echoing it; `clear` removes it. A rotation keeps the previous secret valid for --grace-seconds so deliveries verify while you update the provider. A hook that declares `verify` in its manifest rule (GitHub scheme in v1) requires a valid signature over the raw body and stays fail-closed (401) until this secret is set; the fingerprint (a plaintext-derived id) lets you confirm which secret is set without the relay ever showing it.",
         "Hooks are declared in the app manifest (x-homespun-manifest.ingest) and materialized at deploy, so there is no create or delete verb here: add or remove a hook by editing the manifest and redeploying.",
         "backfill seeds a hook's collection with historical data: it POSTs an array of raw provider bodies to the OWNER endpoint (POST /v1/apps/:id/ingest-hooks/:name/backfill) and runs each through the SAME mapping the live public URL uses, so a backfilled row is byte-identical to a live delivery. It reads a JSON-array or NDJSON --file (each entry is a whole provider payload, any JSON value, not necessarily an object) and chunks it into --chunk bodies per call (default 500). It reuses the receive pipeline, so map/dedupeKey/upsertOn/row-schema validation and the collection quota all apply, but it SKIPS the public-URL brakes (the per-IP rate limit and the per-app hourly cap) and never verifies a signature (you are the authenticated owner). Wake is suppressed, so a large historical load never wakes a dormant app. Dedupe is ON: re-running the same file is idempotent for a body-path dedupeKey; a header:<name> dedupeKey cannot resolve here (no request headers), so it does not dedupe. Prints aggregate { total, accepted, dropped_duplicate, failed } counts.",
+        "--secret on signing-secret set takes the value straight from argv where it is visible in shell history and to other local users via ps for the life of the process. Prefer '--secret -' to read it from stdin, or set HOMESPUN_INGEST_SIGNING_SECRET, both of which never touch argv.",
     ],
 };
 const GRANTS = {
@@ -792,8 +793,8 @@ const CONNECTIONS = {
                 },
                 {
                     name: "header-value",
-                    value: "<value>",
-                    description: 'static only, required. The header value to send, e.g. "Bearer sk_live_..."',
+                    value: "<value|->",
+                    description: 'static only, required. The header value to send, e.g. "Bearer sk_live_...". Pass - to read it from stdin, or set HOMESPUN_CONNECTION_HEADER_VALUE, instead of putting it on the command line where ps and shell history can see it',
                 },
                 {
                     name: "authorize-url",
@@ -812,8 +813,8 @@ const CONNECTIONS = {
                 },
                 {
                     name: "client-secret",
-                    value: "<secret>",
-                    description: "oauth2 only, required. Your OAuth2 app's client secret",
+                    value: "<secret|->",
+                    description: "oauth2 only, required. Your OAuth2 app's client secret. Pass - to read it from stdin, or set HOMESPUN_CONNECTION_CLIENT_SECRET, instead of putting it on the command line where ps and shell history can see it",
                 },
                 {
                     name: "scopes",
@@ -891,6 +892,7 @@ const CONNECTIONS = {
         "A connection is the stored credential a manifest webhook rule authenticates its delivery target with, bound to a host so it can never be sent to another one. There is no update verb: change a connection by deleting and recreating it.",
         "Every stored secret (a static header value, or an oauth2 client secret and its tokens) is encrypted at rest and never returned by any call; list returns metadata plus a non-reversible fingerprint only.",
         "OAuth2 consent is inherently a human-in-a-browser step: the relay refuses an agent-key caller at the authorize endpoint. authorize-url never makes a network call, it builds the URL locally so you can hand it to the signed-in app owner to open. A newly created oauth2 connection starts in pending_auth until the owner completes it.",
+        "--header-value and --client-secret on create take the value straight from argv where it is visible in shell history and to other local users via ps for the life of the process. Prefer '--header-value -' / '--client-secret -' to read the value from stdin, or set HOMESPUN_CONNECTION_HEADER_VALUE / HOMESPUN_CONNECTION_CLIENT_SECRET, both of which never touch argv.",
     ],
 };
 const KEY = {
@@ -1035,8 +1037,8 @@ const CONFIG = {
             flags: [
                 {
                     name: "api-key",
-                    value: "<key>",
-                    description: "Agent API key to save in the profile, required",
+                    value: "<key|->",
+                    description: "Agent API key to save in the profile, required. Pass - to read it from stdin, or set HOMESPUN_CONFIG_API_KEY, instead of putting it on the command line where ps and shell history can see it",
                 },
             ],
         },
@@ -1050,6 +1052,7 @@ const CONFIG = {
         "A profile is one url and 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 is what every other command sees unless overridden by --url, --api-key, HOMESPUN_URL or HOMESPUN_API_KEY.",
         "Every verb is purely local: it inspects flags, env, and the saved config file and makes no network call. 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).",
         "add requires both --url and --api-key, and overwrites the existing values if the profile already exists. Use it when an operator handed you an API key out of band, for example a closed-registration relay; for self-register and secret-mode relays prefer 'homespun agent register --profile <name>'. It does not change current_profile unless it is the first profile added, so run 'homespun config use' afterwards to switch. rm clears current_profile when it removes the active profile, and the next command falls back to env or the default URL until another profile is selected.",
+        "--api-key on add takes the value straight from argv where it is visible in shell history and to other local users via ps for the life of the process. Prefer '--api-key -' to read it from stdin, or set HOMESPUN_CONFIG_API_KEY, both of which never touch argv.",
     ],
 };
 const SKILL = {
@@ -1367,7 +1370,7 @@ const TEMPLATE = {
     noun: "template",
     tagline: "community marketplace templates",
     group: "other",
-    rootSummary: "Community marketplace templates: publish an owned app, unpublish your own listing, read a template's config-contract, install one, and the operator review queue (list-pending, show, approve, reject).",
+    rootSummary: "Community marketplace templates: publish an owned app, unpublish your own listing, read a template's config-contract, install one, keep an installed app current (upgrade-check, upgrade, revert), and the operator review queue (list-pending, show, approve, reject).",
     verbs: [
         {
             verb: "publish",
@@ -1449,6 +1452,39 @@ const TEMPLATE = {
                 },
             ],
         },
+        {
+            verb: "upgrade-check",
+            positionals: "<app>",
+            summary: "Reports whether a newer version of the app's source template is available.",
+            flags: [],
+        },
+        {
+            verb: "upgrade",
+            positionals: "<app>",
+            summary: "Updates an app in place to its template's current version, keeping its data.",
+            flags: [
+                {
+                    name: "expect-version",
+                    value: "<semver>",
+                    description: "Refuse unless this is still the version on offer, so a republish mid-flight cannot slip through",
+                },
+            ],
+            // A value-less flag belongs in `bools`, not `flags`: the catalog is what
+            // assertKnownFlags reads, so declaring it as a value flag makes the real
+            // parser reject `--accept-permissions` as missing its value.
+            bools: [
+                {
+                    name: "accept-permissions",
+                    description: "Accept a version that asks for more than the installed one; required when it does",
+                },
+            ],
+        },
+        {
+            verb: "revert",
+            positionals: "<app>",
+            summary: "Puts an app back on the version it ran before its last template update.",
+            flags: [],
+        },
         {
             verb: "list-pending",
             summary: "Lists pending submissions in the review queue (operator only).",

package/dist/input.js

@@ -1,6 +1,8 @@
 // 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).
+// literal (JSON, or raw text for an HTML template body), plus a shared
+// resolver for flags that carry a caller-supplied secret.
 import { readFileSync, statSync } from "node:fs";
+import { fail, warn } from "./output.js";
 /**
  * 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
@@ -40,3 +42,56 @@ export function resolveJson(value, label) {
 export function resolveText(value) {
     return isFilePath(value) ? readFileSync(value, "utf8") : value;
 }
+/**
+ * Drain process.stdin to a utf8 string and trim exactly one trailing
+ * newline (or CRLF) — the byte an `echo` or heredoc appends and which is
+ * never part of the secret itself. The caller is responsible for gating on
+ * `process.stdin.isTTY` first; in a TTY this blocks waiting for ^D.
+ */
+async function readStdinSecret() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf8");
+    if (raw.endsWith("\r\n"))
+        return raw.slice(0, -2);
+    if (raw.endsWith("\n"))
+        return raw.slice(0, -1);
+    return raw;
+}
+/**
+ * Resolve a flag that carries a caller-supplied secret (a third-party
+ * client secret, a static connection's header value, a webhook signing
+ * secret, an agent API key) — anything an operator types in, as opposed to
+ * a token the relay generates and hands back. A value on argv sits in shell
+ * history and is readable by any other local user via `ps` or
+ * /proc/<pid>/cmdline for the life of the process, so this offers two ways
+ * around that, checked in order:
+ *
+ *   1. the flag given as exactly "-": read the value from stdin, refusing
+ *      when stdin is a TTY so the command fails fast instead of hanging on
+ *      ^D. Mirrors `feedback create --message -`.
+ *   2. `envVar`, read only when the flag was not given at all.
+ *
+ * The flag's literal value keeps working (scripts that already pass it
+ * verbatim must not break), but that path is the exposed one, so it prints
+ * a stderr warning naming the two alternatives above. Mirrors the
+ * `--secret` / `HOMESPUN_REGISTER_SECRET` fallback in `agent register`.
+ *
+ * `flagLabel` (e.g. "--client-secret") appears only in messages.
+ */
+export async function resolveSecretFlag(flagValue, envVar, flagLabel) {
+    if (flagValue === "-") {
+        if (process.stdin.isTTY) {
+            fail(`'${flagLabel} -' expects the secret on stdin, but stdin is a TTY`, "invalid_args");
+        }
+        return readStdinSecret();
+    }
+    if (flagValue !== undefined) {
+        warn(`${flagLabel} was passed on the command line: it is visible in your shell history and, while this command runs, to any other user on this machine via ps or /proc. Use '${flagLabel} -' to read it from stdin instead, or set ${envVar}.`);
+        return flagValue;
+    }
+    const env = process.env[envVar];
+    return env !== undefined && env !== "" ? env : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.48",
+  "version": "1.6.49",
   "description": "Command-line client for the Homespun relay: deploy a real multi-user web app from your agent, then keep reading and writing its data.",
   "license": "MIT",
   "type": "module",
@@ -31,12 +31,12 @@
   ],
   "scripts": {
     "build": "tsc",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "test": "vitest run",
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.6.48",
+    "@homespunapps/core": "^1.6.49",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {