@homespunapps/cli 1.5.1 → 1.6.1

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>", "invalid_args");
+        fail("usage: homespun data <app> <collection> <list|get|upsert|update|delete|purge|import|retention>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(3),
@@ -43,8 +43,10 @@ export async function runData(args) {
             return runPurge(appArg, collection, sub);
         case "import":
             return runImport(appArg, collection, sub);
+        case "retention":
+            return runRetention(appArg, collection, sub);
         default:
-            fail(`unknown verb '${verb}': homespun data <app> <collection> <list|get|upsert|update|delete|purge|import>`, "invalid_args");
+            fail(`unknown verb '${verb}': homespun data <app> <collection> <list|get|upsert|update|delete|purge|import|retention>`, "invalid_args");
     }
 }
 function parseIntFlag(args, name, defaultValue, bounds = {}) {
@@ -353,3 +355,45 @@ async function runImport(appArg, collection, args) {
         failures,
     });
 }
+// `homespun data <app> <collection> retention` (issue #956): show or change the
+// OWNER retention override on a collection. With no set/clear flag (or --show) it
+// reads the current effective retention; otherwise it sets an axis
+// (--max-rows/--max-age-days) or clears one (--clear-rows/--clear-age, reverting
+// that axis to the author default). Effective retention is per-axis
+// `override ?? authorDefault`. Prints the effective bounds and the would-prune
+// count either way.
+async function runRetention(appArg, collection, args) {
+    assertKnownFlags(args, ...specFor("data", "retention"));
+    const clearRows = args.bools.has("clear-rows");
+    const clearAge = args.bools.has("clear-age");
+    const maxRows = parseIntFlag(args, "max-rows", undefined, { min: 1 });
+    const maxAgeDays = parseIntFlag(args, "max-age-days", undefined, { min: 1 });
+    if (clearRows && maxRows !== undefined) {
+        fail("--clear-rows cannot be combined with --max-rows", "invalid_args");
+    }
+    if (clearAge && maxAgeDays !== undefined) {
+        fail("--clear-age cannot be combined with --max-age-days", "invalid_args");
+    }
+    // Build the per-axis patch: a number sets the axis, null clears it, an omitted
+    // axis is left unchanged. `--show` (or no set/clear flag) reads without writing.
+    const patch = {};
+    if (clearRows)
+        patch.maxRows = null;
+    else if (maxRows !== undefined)
+        patch.maxRows = maxRows;
+    if (clearAge)
+        patch.maxAgeDays = null;
+    else if (maxAgeDays !== undefined)
+        patch.maxAgeDays = maxAgeDays;
+    const willWrite = patch.maxRows !== undefined || patch.maxAgeDays !== undefined;
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(willWrite
+            ? await client.setCollectionRetention(appId, collection, patch)
+            : await client.getCollectionRetention(appId, collection));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/help-catalog.js

@@ -128,7 +128,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.",
+    rootSummary: "Collection row CRUD for an app: list, get, upsert, update, delete, 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
@@ -258,12 +258,43 @@ const DATA = {
                 },
             ],
         },
+        {
+            verb: "retention",
+            summary: "Shows or overrides the owner retention on a collection (owner control).",
+            flags: [
+                {
+                    name: "max-rows",
+                    value: "<n>",
+                    description: "Override the max live rows kept (per-axis, positive)",
+                },
+                {
+                    name: "max-age-days",
+                    value: "<n>",
+                    description: "Override the max row age in days (per-axis, positive)",
+                },
+            ],
+            bools: [
+                {
+                    name: "clear-rows",
+                    description: "Clear the rows override, reverting to the author default",
+                },
+                {
+                    name: "clear-age",
+                    description: "Clear the age override, reverting to the author default",
+                },
+                {
+                    name: "show",
+                    description: "Only read the current effective retention, change nothing",
+                },
+            ],
+        },
     ],
     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, never errors). 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.",
         "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. 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.",
     ],
     outputNote: 'Output is a single JSON object on stdout, and import additionally writes per-chunk progress lines to stderr. Errors go to stderr as {"error":{"code","message"}} with a non-zero exit.',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "Command-line client for the Homespun relay: create apps, inspect state, send and watch events.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.5.1",
+    "@homespunapps/core": "^1.6.1",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {