@homespunapps/cli 1.6.37 → 1.6.39

package/README.md

@@ -16,18 +16,22 @@ npx @homespunapps/cli <command>
 
 The binary is `homespun`.
 
-## Try it
+## Quickstart
 
-Register once, then `homespun demo` spins up a short-lived sample app on the hosted
-relay, opens it in your browser, and prints the structured event back in your
-terminal the moment you interact (the demo app is cleaned up on exit):
+Register once, then deploy:
 
 ```sh
 npx @homespunapps/cli agent register --name "my-agent"   # one-time, hosted relay
-npx @homespunapps/cli demo                               # Node 20+ — round-trip in ~60s
+npx @homespunapps/cli deploy ./my-app   # Node 20+, reads ./my-app/index.html + manifest.json
 ```
 
-Add `--no-open` on a headless / SSH box and it just prints the URL.
+`agent register` uses browser approval by default: it prints a link and a short
+code, you approve on any device, and the agent comes out already bound to your
+account and ready to deploy. See [Setup](#setup) for the direct-registration
+path and the one-time `agent claim` it needs.
+
+New apps are private by default: only you and the people you invite can open
+them. Pass `--visibility link` or `--visibility public` to share wider.
 
 ## Setup
 
@@ -53,41 +57,69 @@ Override per-invocation with `--url <url>` and `--api-key <key>`.
 
 ## Commands
 
-Uniform `homespun <noun> <verb> [options]`:
+Uniform `homespun <noun> <verb> [options]` (`data` takes its collection
+before the verb: `homespun data <app> <collection> <verb>`).
+
+App commands, each operating on a deployed app:
+
+```
+homespun deploy [dir|file]  Create or redeploy an app (POST /v1/apps, or
+                            /v1/apps/:id/versions with --app)
+homespun apps <verb>        App lifecycle: list, show, update, share-link,
+                            delete, wake, domain, watch (the change feed as
+                            JSON-lines)
+homespun data <app> <collection> <verb>
+                            Collection row CRUD: list, get, upsert, update,
+                            delete, purge, import, retention
+homespun members <verb>     App membership: add, list, set-role, remove, roles
+homespun grants <verb>      Grant-link management: mint, list, revoke
+homespun ingest <verb>      Inbound catch-hook management: list, rotate,
+                            signing-secret, backfill
+```
+
+Other command groups:
 
 ```
-homespun demo                      Zero-setup guided tour — see the round-trip live
-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
-homespun send <id>         Emit an agent event into an app
-homespun watch <id>        Stream an app's events as JSON-lines on stdout
-homespun delete <id>       Close / delete an app
-homespun template <verb>           Manage reusable, versioned templates
-homespun key list | revoke         Inspect or revoke your agent's API key
-homespun taste get | set | clear   Read / write / clear UI-taste notes
-homespun feedback create | list    Submit / list one-shot feedback to the operator
-homespun config show               Show the resolved relay config (no network call)
-homespun skill show | version      Fetch the relay's SKILL.md (or its version)
+homespun publisher <verb>  Your community publisher identity: claim, show,
+                           update, set-trust
+homespun template <verb>   Community marketplace templates: publish,
+                           unpublish, config-contract, install, list-pending,
+                           show, approve, reject
+homespun review <verb>     Community template reviews: create, respond,
+                           report, remove, unhold
+homespun key <verb>        Your agent's own API key: list, mint, revoke
+homespun taste <verb>      Your agent's UI taste notes: get, set, clear
+homespun feedback <verb>   One-shot feedback to the relay operator: create, list
+homespun attachment <verb> Binary attachments: upload, download, show, list,
+                           delete, token mint | revoke | list
+homespun agent <verb>      This agent's identity on the relay: register,
+                           claim, set-key, logout
+homespun config <verb>     CLI config and profile management: show, list,
+                           use, add, rm
+homespun skill <verb>      The relay's SKILL.md: show, version
 ```
 
 Run `homespun <noun> --help` for that noun's verbs, and
-`homespun <noun> <verb> --help` for verb-specific options.
+`homespun <noun> <verb> --help` for verb-specific options. The same table
+also drives the generated [CLI reference](https://docs.homespun.dev/agents/cli-reference/).
 
 ## Output
 
-stdout is machine-readable JSON. Errors go to stderr as
-`{"error":{"code","message"}}` with a non-zero exit.
+stdout is JSON. Errors go to stderr as `{"error":{"code","message"}}` with a
+non-zero exit. A deploy, then a read of the data it wrote back:
 
 ```sh
-SESSION=$(homespun create --template ./form.html --name "Quick poll" --event-schema ./q.json | jq -r .app_id)
-homespun watch "$SESSION" | jq 'select(.type == "human_response")'
+homespun deploy ./grocery-list
+# -> { app_id, slug, url, version, visibility: "private", created: true }
+
+homespun data grocery-list items upsert --data '{"name":"Milk","checked":false}'
+# -> { row: { key, data: { name: "Milk", checked: false }, version: 1, author, created_at, updated_at } }
+
+homespun data grocery-list items list
+# -> { rows: [...], next_cursor, has_more }
 ```
 
 ## Links
 
 - Docs: <https://docs.homespun.dev>
-- License: MIT
+- License: [MIT](LICENSE)

package/dist/commands/data.js

@@ -18,7 +18,7 @@ export async function runData(args) {
         return;
     }
     if (!appArg || !collection || !verb) {
-        fail("usage: homespun data <app> <collection> <list|get|upsert|update|delete|purge|import|retention>", "invalid_args");
+        fail("usage: homespun data <app> <collection> <list|get|upsert|update|delete|restore|deleted|purge|import|retention>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(3),
@@ -39,6 +39,10 @@ export async function runData(args) {
             return runUpdate(appArg, collection, sub);
         case "delete":
             return runDelete(appArg, collection, sub);
+        case "restore":
+            return runRestore(appArg, collection, sub);
+        case "deleted":
+            return runListDeleted(appArg, collection, sub);
         case "purge":
             return runPurge(appArg, collection, sub);
         case "import":
@@ -46,7 +50,7 @@ export async function runData(args) {
         case "retention":
             return runRetention(appArg, collection, sub);
         default:
-            fail(`unknown verb '${verb}': homespun data <app> <collection> <list|get|upsert|update|delete|purge|import|retention>`, "invalid_args");
+            fail(`unknown verb '${verb}': homespun data <app> <collection> <list|get|upsert|update|delete|restore|deleted|purge|import|retention>`, "invalid_args");
     }
 }
 function parseIntFlag(args, name, defaultValue, bounds = {}) {
@@ -191,6 +195,50 @@ async function runDelete(appArg, collection, args) {
         failFromError(e);
     }
 }
+// `homespun data <app> <coll> restore --key <key>`: undo a delete. Owner/agent
+// only, and --key rather than a positional for the same reason purge uses one:
+// the verb reads deliberately at the call site.
+async function runRestore(appArg, collection, args) {
+    assertKnownFlags(args, ...specFor("data", "restore"));
+    const key = args.flags.get("key");
+    if (!key) {
+        fail("usage: homespun data <app> <collection> restore --key <key>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.restoreAppRow(appId, collection, key));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// `homespun data <app> <coll> deleted`: the recovery bin, newest deletion
+// first. Owner/agent only. Paged with --before, which takes the previous
+// page's `next_before`.
+async function runListDeleted(appArg, collection, args) {
+    assertKnownFlags(args, ...specFor("data", "deleted"));
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    const limitRaw = args.flags.get("limit");
+    const before = args.flags.get("before");
+    const opts = {};
+    if (limitRaw !== undefined) {
+        const n = Number(limitRaw);
+        if (!Number.isInteger(n) || n < 1) {
+            fail("--limit must be a positive integer", "invalid_args");
+        }
+        opts.limit = n;
+    }
+    if (before !== undefined)
+        opts.before = before;
+    try {
+        printJson(await client.listDeletedAppRows(appId, collection, opts));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
 // `homespun data <app> <coll> purge --key <key>`, owner/agent-only removal that
 // bypasses an append-only collection (Wave C1). The row key comes from --key
 // (not a positional) so a purge reads deliberately, harder to fire by accident.

package/dist/commands/template.js

@@ -1,10 +1,11 @@
 // `homespun template` (issue #890) community marketplace templates: publish an
-// owned app as a pending template, read a template's install-time config
-// contract, install a template for the caller, and (operator) list/show/approve/
-// reject pending submissions. Publish/config-contract/install act AS the calling
-// agent's owning human; list-pending/show/approve/reject are operator-gated
-// server-side. A template <ref> is a namespaced <handle>/<slug> or a snapshot id,
-// passed straight to the SDK.
+// owned app as a pending template, unpublish your own live listing (#1299),
+// read a template's install-time config contract, install a template for the
+// caller, and (operator) list/show/approve/reject pending submissions.
+// Publish/unpublish/config-contract/install act AS the calling agent's owning
+// human; list-pending/show/approve/reject are operator-gated server-side. A
+// template <ref> is a namespaced <handle>/<slug> or a snapshot id, passed
+// straight to the SDK.
 import { assertKnownFlags } from "../argv.js";
 import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
@@ -18,7 +19,7 @@ export async function runTemplate(args) {
         return;
     }
     if (verb === undefined) {
-        fail("missing verb: homespun template <publish|config-contract|install|list-pending|show|approve|reject>", "invalid_args");
+        fail("missing verb: homespun template <publish|unpublish|config-contract|install|list-pending|show|approve|reject>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -31,6 +32,8 @@ export async function runTemplate(args) {
     switch (verb) {
         case "publish":
             return runPublish(sub);
+        case "unpublish":
+            return runUnpublish(sub);
         case "config-contract":
             return runConfigContract(sub);
         case "install":
@@ -44,7 +47,7 @@ export async function runTemplate(args) {
         case "reject":
             return runReject(sub);
         default:
-            fail(`unknown verb '${verb}' (homespun template <publish|config-contract|install|list-pending|show|approve|reject>)`, "invalid_args");
+            fail(`unknown verb '${verb}' (homespun template <publish|unpublish|config-contract|install|list-pending|show|approve|reject>)`, "invalid_args");
     }
 }
 function parseIntFlag(args, name, bounds = {}) {
@@ -109,6 +112,23 @@ async function runPublish(args) {
     }
 }
 // ---------------------------------------------------------------------------
+// unpublish
+// ---------------------------------------------------------------------------
+async function runUnpublish(args) {
+    assertKnownFlags(args, ...specFor("template", "unpublish"));
+    const snapshotId = args.positionals[0];
+    if (!snapshotId) {
+        fail("usage: homespun template unpublish <snapshot-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.unpublishCommunityTemplate(snapshotId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
 // config-contract
 // ---------------------------------------------------------------------------
 async function runConfigContract(args) {

package/dist/help-catalog.js

@@ -133,7 +133,7 @@ const DATA = {
     noun: "data",
     tagline: "collection row CRUD for an app",
     group: "app",
-    rootSummary: "Collection row CRUD for an app: list, get, upsert, update, delete, purge, import, plus retention (owner override).",
+    rootSummary: "Collection row CRUD for an app: list, get, upsert, update, delete, restore, deleted, purge, import, plus retention (owner override).",
     // The data parser is verb-LAST: `homespun data <app> <collection> <verb>`
     // (see commands/data.ts, which reads the verb from positionals[2]). Every
     // other noun is verb-first. Each verb below carries only the positionals that
@@ -219,6 +219,29 @@ const DATA = {
             ],
             bools: [{ name: "yes", description: "Skip the confirmation prompt" }],
         },
+        {
+            verb: "restore",
+            summary: "Restores a soft-deleted row. Owner and agent only.",
+            flags: [
+                {
+                    name: "key",
+                    value: "<key>",
+                    description: "Key of the deleted row to restore (required)",
+                },
+            ],
+        },
+        {
+            verb: "deleted",
+            summary: "Lists recoverable deleted rows. Owner and agent only.",
+            flags: [
+                { name: "limit", value: "<n>", description: "Max rows (default 100)" },
+                {
+                    name: "before",
+                    value: "<iso>",
+                    description: "Page cursor: the previous page's next_before",
+                },
+            ],
+        },
         {
             verb: "purge",
             summary: "Removes one row even from an append-only collection.",
@@ -297,7 +320,7 @@ const DATA = {
     notes: [
         "<app> accepts either the app_id or its slug. upsert is the ONLY create-shaped verb: omit --key to add a new row (the server generates the key); pass --key to ensure a row exists at that key (returns the existing row with deduped:true on a collision). A collision on a row the collection's read list does not reach for you is row_not_found (404) instead of the row, the same answer a get on that key gives, so upsert cannot read past read. Pass --on <field> to upsert on a manifest-declared UNIQUE field instead of the key: the row whose <field> value matches is updated in place (idempotent re-import), else created.",
         "list --where takes a JSON array of {field, op, value} conditions (ANDed), op one of eq, neq, in, notIn, gt, lt, gte, lte (in and notIn take an array value). --sort takes a JSON array of {field, dir} (dir asc or desc). Filtering is applied AFTER the read permission and author scoping, so a filtered list is always a subset of what you could already read. Comparisons are same-type only (no coercion); dates compare as ISO-8601 strings. A custom --sort cannot be combined with --since.",
-        "purge removes ONE row by --key even in an append-only collection. Owner and agent only (never members or anyone); it bypasses append-only and the collection delete list on purpose, and writes an audited delete feed entry.",
+        "delete is RECOVERABLE: it tombstones the row, `deleted` lists what can still be brought back, and `restore` brings one back for 30 days. purge is the permanent one: it removes ONE row by --key even in an append-only collection, scrubs its contents immediately, and cannot be restored. Both are owner and agent only (never members or anyone); purge bypasses append-only and the collection delete list on purpose, and both write an audited delete feed entry.",
         "import reads NDJSON (one JSON object per line) OR a JSON array from --file and bulk-writes it in chunks via the batch API, in ONE process. Each object is a row's data. Pass --key-field to derive the row key from a field: an existing row at that key is LEFT UNCHANGED, so this is create-or-skip-by-id, not overwrite, and re-importing changed data for a known key does not update it. A skipped row is reported as a per-row row_not_found rather than an ok when the collection's read list does not reach that row for you (the row is still left unchanged); list 'agent' in read if you want the skip reported as a success. Import DEFAULTS TO SILENT (it suppresses notify and webhooks, since a bulk import is a migration); pass --emit-effects to fire them. A per-row failure is listed in the summary WITHOUT aborting the import.",
         "retention is an OWNER control: the author declares default retention in the manifest, and this tightens or loosens it per collection at runtime WITHOUT a redeploy. Effective retention is per-axis override-or-author-default: --max-rows/--max-age-days set an axis override, --clear-rows/--clear-age revert an axis to the author default, and with no flag (or --show) it just reads. The response reports the effective bounds, the author default, the override, and wouldPrune (how many live rows the effective bound would prune on the next sweep). The override survives redeploys and effective maxRows is capped at MAX_ROWS_PER_APP.",
     ],
@@ -1045,7 +1068,7 @@ const TEMPLATE = {
     noun: "template",
     tagline: "community marketplace templates",
     group: "other",
-    rootSummary: "Community marketplace templates: publish an owned app, 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, and the operator review queue (list-pending, show, approve, reject).",
     verbs: [
         {
             verb: "publish",
@@ -1105,6 +1128,11 @@ const TEMPLATE = {
                 },
             ],
         },
+        {
+            verb: "unpublish",
+            positionals: "<snapshot-id>",
+            summary: "Takes your own live listing out of the public gallery.",
+        },
         {
             verb: "config-contract",
             positionals: "<ref>",
@@ -1156,6 +1184,7 @@ const TEMPLATE = {
     notes: [
         "A template <ref> is a namespaced <handle>/<slug> or a community snapshot id, passed straight to the relay. publish resolves <app> by id or slug, the same way apps and data do.",
         "publish, config-contract, and install act as the calling agent's owning human. Install always creates a new owned app and returns its id, slug, and url; use config-contract first to discover what config an install needs.",
+        "unpublish takes one of YOUR OWN live listings down: it leaves the public gallery, search, and the direct snapshot install link. Existing installs keep working, because an install is a fresh private copy and not a live reference. It is idempotent, and it reports not_found for a snapshot that is not yours. Republish a new version to put a listing back.",
         "list-pending, show, approve, and reject drive the operator review queue and are operator-gated server-side. reject requires --note, which is delivered to the publisher's app feed.",
     ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.37",
+  "version": "1.6.39",
   "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",
@@ -36,14 +36,14 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.6.37",
+    "@homespunapps/core": "^1.6.39",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.1.2",
     "@types/qrcode-terminal": "^0.12.2",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.10"
   },
   "repository": {
     "type": "git",