@homespunapps/cli 1.6.0 → 1.6.2

package/dist/argv.js

@@ -54,6 +54,11 @@ export const BOOLEAN_FLAGS = new Set([
     "all",
     // `homespun members set-role --clear-role`: drop a custom role back to plain member.
     "clear-role",
+    // `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 review respond --clear`: clear a publisher response (sends null).
+    "clear",
 ]);
 /**
  * Parse argv tokens. `booleanFlags` lists flags that never consume a value

package/dist/commands/ingest.js

@@ -1,7 +1,9 @@
 // `homespun ingest`: inbound catch-hook read surface for an app (inbound-webhooks
-// PR 3). List the app's declared hooks with their full secret URL, and rotate a
-// hook's secret. Every verb targets an app via a required `--app <idOrSlug>`,
-// resolved the same way `homespun members`/`homespun data` do (resolveAppId).
+// PR 3). List the app's declared hooks with their full secret URL, rotate a
+// hook's secret, manage its opt-in signing secret, and backfill historical
+// payloads through a hook's mapping (issue #966). Every verb targets an app via a
+// required `--app <idOrSlug>`, resolved the same way `homespun members`/`homespun
+// data` do (resolveAppId).
 //
 // This is the smallest surface an agent needs during app setup: after deploying
 // a manifest that declares an `ingest` hook, the agent runs `homespun ingest list`
@@ -12,6 +14,7 @@
 // Auth on the relay side is owner-or-agent (the owning agent's API key OR the
 // owner human's login cookie); this CLI always authenticates as the agent, so
 // both verbs work for an app the calling agent's owning human owns.
+import { readFileSync } from "node:fs";
 import { assertKnownFlags } from "../argv.js";
 import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
@@ -24,7 +27,7 @@ export async function runIngest(args) {
         return;
     }
     if (verb === undefined) {
-        fail("missing verb (homespun ingest <list|rotate|signing-secret>)", "invalid_args");
+        fail("missing verb (homespun ingest <list|rotate|signing-secret|backfill>)", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -41,8 +44,10 @@ export async function runIngest(args) {
             return runRotate(sub);
         case "signing-secret":
             return runSigningSecret(sub);
+        case "backfill":
+            return runBackfill(sub);
         default:
-            fail(`unknown verb '${verb}' (homespun ingest <list|rotate|signing-secret>)`, "invalid_args");
+            fail(`unknown verb '${verb}' (homespun ingest <list|rotate|signing-secret|backfill>)`, "invalid_args");
     }
 }
 // ---------------------------------------------------------------------------
@@ -161,3 +166,118 @@ async function runSigningSecretClear(args) {
         failFromError(e);
     }
 }
+// ---------------------------------------------------------------------------
+// backfill
+// ---------------------------------------------------------------------------
+//
+// Bulk-load historical raw provider bodies through a hook's mapping (issue
+// #966), so a seeded app's rows are byte-identical to live deliveries. Reads a
+// JSON-array OR NDJSON file of raw payloads (each a whole provider body, any JSON
+// value, not necessarily an object), chunks it into <= --chunk bodies per call,
+// and prints aggregate { accepted, dropped_duplicate, failed } counts. Re-running
+// the same file is idempotent for a body-path dedupeKey (the relay dedupes).
+// The relay's INGEST_BACKFILL_MAX_BODIES default; a larger --chunk is rejected
+// server-side (400), so the CLI keeps the conservative default and lets the
+// chunker split the whole file across as many calls as needed.
+const DEFAULT_BACKFILL_CHUNK = 500;
+/**
+ * Parse a backfill file into an ordered list of raw provider bodies. Accepts
+ * either a single JSON array (the whole file parses as an array) or NDJSON (one
+ * JSON value per non-blank line). Unlike a row import, an entry may be ANY JSON
+ * value (object, array, string, number): it is a raw provider payload, mapped
+ * server-side. A malformed line reports its 1-based line number.
+ */
+function parseBackfillBodies(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return [];
+    // JSON array form: the entire file is one array literal.
+    if (trimmed.startsWith("[")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (e) {
+            fail(`--file is not valid JSON (${e instanceof Error ? e.message : String(e)})`, "invalid_args");
+        }
+        if (!Array.isArray(parsed)) {
+            fail("--file top-level JSON must be an array of payloads", "invalid_args");
+        }
+        return parsed;
+    }
+    // NDJSON form: one JSON value per non-blank line.
+    const out = [];
+    const lines = raw.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.length === 0)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch (e) {
+            fail(`--file line ${i + 1} is not valid JSON (${e instanceof Error ? e.message : String(e)})`, "invalid_args");
+        }
+    }
+    return out;
+}
+async function runBackfill(args) {
+    assertKnownFlags(args, ...specFor("ingest", "backfill"));
+    const appArg = args.flags.get("app");
+    const name = args.flags.get("name");
+    const file = args.flags.get("file");
+    if (!appArg || !name || !file) {
+        fail("usage: homespun ingest backfill --app <idOrSlug> --name <hookName> --file <path> [--chunk <n>]", "invalid_args");
+    }
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (e) {
+        fail(`cannot read --file '${file}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+    }
+    const bodies = parseBackfillBodies(raw);
+    if (bodies.length === 0) {
+        fail("--file contained no payloads to backfill", "invalid_args");
+    }
+    let chunkSize = DEFAULT_BACKFILL_CHUNK;
+    const chunkRaw = args.flags.get("chunk");
+    if (chunkRaw !== undefined) {
+        chunkSize = Number(chunkRaw);
+        if (!Number.isInteger(chunkSize) || chunkSize < 1) {
+            fail("--chunk must be a positive integer", "invalid_args");
+        }
+    }
+    const client = makeClient(args);
+    // resolveAppId ONCE for the whole backfill (not per chunk): the app id is
+    // stable for the process, so one lookup drives every call.
+    const appId = await resolveAppId(client, appArg);
+    const total = bodies.length;
+    const chunkCount = Math.ceil(total / chunkSize);
+    let accepted = 0;
+    let droppedDuplicate = 0;
+    let failed = 0;
+    try {
+        for (let start = 0, chunkNo = 1; start < total; start += chunkSize, chunkNo++) {
+            const chunk = bodies.slice(start, start + chunkSize);
+            const res = await client.backfillIngestHook(appId, name, chunk);
+            accepted += res.accepted;
+            droppedDuplicate += res.dropped_duplicate;
+            failed += res.failed;
+            // Human-readable progress on stderr so stdout stays a single JSON summary.
+            process.stderr.write(`backfilled ${accepted + droppedDuplicate + failed}/${total} (chunk ${chunkNo}/${chunkCount}, ${accepted} accepted, ${droppedDuplicate} dropped_duplicate, ${failed} failed)\n`);
+        }
+    }
+    catch (e) {
+        failFromError(e);
+    }
+    printJson({
+        app: appId,
+        hook: name,
+        total,
+        accepted,
+        dropped_duplicate: droppedDuplicate,
+        failed,
+        chunks: chunkCount,
+    });
+}

package/dist/commands/publisher.js

@@ -0,0 +1,115 @@
+// `homespun publisher` (issue #890) community publisher identity: claim the
+// one permanent handle, show the caller's own profile, update the mutable
+// profile fields, and (operator) set another publisher's trust level. Every
+// verb acts AS the calling agent's owning human via the relay /v1/publisher
+// routes; set-trust is operator-gated server-side.
+import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+export async function runPublisher(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("publisher")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb: homespun publisher <claim|show|update|set-trust>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "claim":
+            return runClaim(sub);
+        case "show":
+            return runShow(sub);
+        case "update":
+            return runUpdate(sub);
+        case "set-trust":
+            return runSetTrust(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun publisher <claim|show|update|set-trust>)`, "invalid_args");
+    }
+}
+// ---------------------------------------------------------------------------
+// claim
+// ---------------------------------------------------------------------------
+async function runClaim(args) {
+    assertKnownFlags(args, ...specFor("publisher", "claim"));
+    const handle = args.positionals[0];
+    if (!handle) {
+        fail("usage: homespun publisher claim <handle>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.claimPublisherHandle(handle));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// show
+// ---------------------------------------------------------------------------
+async function runShow(args) {
+    assertKnownFlags(args, ...specFor("publisher", "show"));
+    const client = makeClient(args);
+    try {
+        printJson(await client.getPublisher());
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// update
+// ---------------------------------------------------------------------------
+async function runUpdate(args) {
+    assertKnownFlags(args, ...specFor("publisher", "update"));
+    const displayName = args.flags.get("display-name");
+    const bio = args.flags.get("bio");
+    // The SDK field is `url`, but the CLI flag is --website: --url is the global
+    // relay-target override, so the publisher's profile url gets its own name.
+    const website = args.flags.get("website");
+    if (displayName === undefined && bio === undefined && website === undefined) {
+        fail("at least one of --display-name, --bio, or --website is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.updatePublisher({
+            ...(displayName !== undefined ? { displayName } : {}),
+            ...(bio !== undefined ? { bio } : {}),
+            ...(website !== undefined ? { url: website } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// set-trust
+// ---------------------------------------------------------------------------
+async function runSetTrust(args) {
+    assertKnownFlags(args, ...specFor("publisher", "set-trust"));
+    const handle = args.positionals[0];
+    const level = args.positionals[1];
+    if (!handle || !level) {
+        fail("usage: homespun publisher set-trust <handle> <new|established>", "invalid_args");
+    }
+    if (level !== "new" && level !== "established") {
+        fail('trust level must be "new" or "established"', "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.setPublisherTrustLevel(handle, level));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/review.js

@@ -0,0 +1,155 @@
+// `homespun review` (issue #890) community marketplace reviews: create a star
+// review for a template the caller installed, respond to a review as the
+// publisher, report a review for operator attention, and (operator) remove or
+// unhold a review. create/respond/report act AS the calling agent's owning
+// human; remove/unhold are operator-gated server-side. A template <ref> is a
+// namespaced <handle>/<slug>, passed straight to the SDK.
+import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+export async function runReview(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("review")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb: homespun review <create|respond|report|remove|unhold>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "create":
+            return runCreate(sub);
+        case "respond":
+            return runRespond(sub);
+        case "report":
+            return runReport(sub);
+        case "remove":
+            return runRemove(sub);
+        case "unhold":
+            return runUnhold(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun review <create|respond|report|remove|unhold>)`, "invalid_args");
+    }
+}
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+async function runCreate(args) {
+    assertKnownFlags(args, ...specFor("review", "create"));
+    const ref = args.positionals[0];
+    if (!ref) {
+        fail("usage: homespun review create <ref> --stars <1-5> [--body <text>]", "invalid_args");
+    }
+    const starsRaw = args.flags.get("stars");
+    if (starsRaw === undefined) {
+        fail("--stars is required", "invalid_args");
+    }
+    const stars = Number(starsRaw);
+    if (!Number.isInteger(stars) || stars < 1 || stars > 5) {
+        fail("--stars must be an integer from 1 to 5", "invalid_args");
+    }
+    const body = args.flags.get("body");
+    const client = makeClient(args);
+    try {
+        printJson(await client.createReview({
+            template: ref,
+            stars,
+            ...(body !== undefined ? { body } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// respond
+// ---------------------------------------------------------------------------
+async function runRespond(args) {
+    assertKnownFlags(args, ...specFor("review", "respond"));
+    const reviewId = args.positionals[0];
+    if (!reviewId) {
+        fail("usage: homespun review respond <review-id> (--response <text> | --clear)", "invalid_args");
+    }
+    // Clearing a response is a real instruction, so it gets its own explicit flag
+    // rather than being spelled as an omitted or empty --response: an omitted
+    // value must never silently wipe a published response.
+    const response = args.flags.get("response");
+    const clear = args.bools.has("clear");
+    if (clear && response !== undefined) {
+        fail("--response and --clear are mutually exclusive", "invalid_args");
+    }
+    if (!clear && response === undefined) {
+        fail("one of --response <text> or --clear is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.respondToReview(reviewId, clear ? null : response));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// report
+// ---------------------------------------------------------------------------
+async function runReport(args) {
+    assertKnownFlags(args, ...specFor("review", "report"));
+    const reviewId = args.positionals[0];
+    if (!reviewId) {
+        fail("usage: homespun review report <review-id> --reason <reason>", "invalid_args");
+    }
+    const reason = args.flags.get("reason");
+    if (!reason) {
+        fail("--reason is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.reportReview(reviewId, reason));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// remove
+// ---------------------------------------------------------------------------
+async function runRemove(args) {
+    assertKnownFlags(args, ...specFor("review", "remove"));
+    const reviewId = args.positionals[0];
+    if (!reviewId) {
+        fail("usage: homespun review remove <review-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.removeReview(reviewId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// unhold
+// ---------------------------------------------------------------------------
+async function runUnhold(args) {
+    assertKnownFlags(args, ...specFor("review", "unhold"));
+    const reviewId = args.positionals[0];
+    if (!reviewId) {
+        fail("usage: homespun review unhold <review-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.unholdReview(reviewId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/template.js

@@ -0,0 +1,226 @@
+// `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.
+import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.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 async function runTemplate(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("template")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb: homespun template <publish|config-contract|install|list-pending|show|approve|reject>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "publish":
+            return runPublish(sub);
+        case "config-contract":
+            return runConfigContract(sub);
+        case "install":
+            return runInstall(sub);
+        case "list-pending":
+            return runListPending(sub);
+        case "show":
+            return runShow(sub);
+        case "approve":
+            return runApprove(sub);
+        case "reject":
+            return runReject(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun template <publish|config-contract|install|list-pending|show|approve|reject>)`, "invalid_args");
+    }
+}
+function parseIntFlag(args, name, bounds = {}) {
+    const raw = args.flags.get(name);
+    if (raw === undefined)
+        return undefined;
+    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;
+}
+// ---------------------------------------------------------------------------
+// publish
+// ---------------------------------------------------------------------------
+async function runPublish(args) {
+    assertKnownFlags(args, ...specFor("template", "publish"));
+    const appArg = args.positionals[0];
+    if (!appArg) {
+        fail("usage: homespun template publish <app>", "invalid_args");
+    }
+    const title = args.flags.get("title");
+    const description = args.flags.get("description");
+    const longDescription = args.flags.get("long-description");
+    const category = args.flags.get("category");
+    const slug = args.flags.get("slug");
+    const version = args.flags.get("version");
+    const changelogNote = args.flags.get("changelog-note");
+    const attestExampleOnly = args.bools.has("attest-example-only");
+    const tagsRaw = args.flags.get("tags");
+    const tags = tagsRaw !== undefined
+        ? resolveJson(tagsRaw, "--tags")
+        : undefined;
+    const setupStepsRaw = args.flags.get("setup-steps");
+    const setupSteps = setupStepsRaw !== undefined
+        ? resolveJson(setupStepsRaw, "--setup-steps")
+        : undefined;
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.publishCommunityTemplate({
+            appId,
+            ...(title !== undefined ? { title } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(longDescription !== undefined ? { longDescription } : {}),
+            ...(category !== undefined ? { category } : {}),
+            ...(tags !== undefined ? { tags } : {}),
+            ...(slug !== undefined ? { slug } : {}),
+            ...(version !== undefined ? { version } : {}),
+            ...(changelogNote !== undefined ? { changelogNote } : {}),
+            ...(setupSteps !== undefined ? { setupSteps } : {}),
+            ...(attestExampleOnly ? { attestExampleOnly: true } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// config-contract
+// ---------------------------------------------------------------------------
+async function runConfigContract(args) {
+    assertKnownFlags(args, ...specFor("template", "config-contract"));
+    const ref = args.positionals[0];
+    if (!ref) {
+        fail("usage: homespun template config-contract <ref>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.getCommunityConfigContract(ref));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// install
+// ---------------------------------------------------------------------------
+async function runInstall(args) {
+    assertKnownFlags(args, ...specFor("template", "install"));
+    const ref = args.positionals[0];
+    if (!ref) {
+        fail("usage: homespun template install <ref>", "invalid_args");
+    }
+    const configRaw = args.flags.get("config");
+    const config = configRaw !== undefined
+        ? resolveJson(configRaw, "--config")
+        : undefined;
+    const client = makeClient(args);
+    try {
+        printJson(await client.installCommunityTemplate(ref, config));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// list-pending
+// ---------------------------------------------------------------------------
+async function runListPending(args) {
+    assertKnownFlags(args, ...specFor("template", "list-pending"));
+    const limit = parseIntFlag(args, "limit", { min: 1 });
+    const cursor = args.flags.get("cursor");
+    const client = makeClient(args);
+    try {
+        printJson(await client.listCommunitySubmissions({
+            ...(limit !== undefined ? { limit } : {}),
+            ...(cursor !== undefined ? { cursor } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// show
+// ---------------------------------------------------------------------------
+async function runShow(args) {
+    assertKnownFlags(args, ...specFor("template", "show"));
+    const snapshotId = args.positionals[0];
+    if (!snapshotId) {
+        fail("usage: homespun template show <snapshot-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.getCommunitySubmission(snapshotId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// approve
+// ---------------------------------------------------------------------------
+async function runApprove(args) {
+    assertKnownFlags(args, ...specFor("template", "approve"));
+    const snapshotId = args.positionals[0];
+    if (!snapshotId) {
+        fail("usage: homespun template approve <snapshot-id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.reviewCommunitySubmission(snapshotId, {
+            decision: "approve",
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// reject
+// ---------------------------------------------------------------------------
+async function runReject(args) {
+    assertKnownFlags(args, ...specFor("template", "reject"));
+    const snapshotId = args.positionals[0];
+    if (!snapshotId) {
+        fail("usage: homespun template reject <snapshot-id> --note <note>", "invalid_args");
+    }
+    const note = args.flags.get("note");
+    if (!note) {
+        fail("--note is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        printJson(await client.reviewCommunitySubmission(snapshotId, {
+            decision: "reject",
+            note: note,
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/help-catalog.js

@@ -403,7 +403,7 @@ const INGEST = {
     noun: "ingest",
     tagline: "inbound catch-hook read surface",
     group: "app",
-    rootSummary: "Inbound catch-hook management: list, rotate, signing-secret. Read back an app's declared inbound hooks with their full secret URL so you can tell the owner where an external system posts, rotate a leaked URL secret, or manage a hook's opt-in signing secret. Hooks themselves are declared in the app manifest (x-homespun-manifest.ingest).",
+    rootSummary: "Inbound catch-hook management: list, rotate, signing-secret, backfill. Read back an app's declared inbound hooks with their full secret URL so you can tell the owner where an external system posts, rotate a leaked URL secret, manage a hook's opt-in signing secret, or bulk-load historical payloads through a hook's mapping. Hooks themselves are declared in the app manifest (x-homespun-manifest.ingest).",
     verbs: [
         {
             verb: "list",
@@ -459,6 +459,32 @@ const INGEST = {
                 },
             ],
         },
+        {
+            verb: "backfill",
+            summary: "Bulk-loads historical raw provider bodies through a hook's mapping, writing rows identical to live deliveries.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the hook belongs to (required)",
+                },
+                {
+                    name: "name",
+                    value: "<hookName>",
+                    description: "Name of the manifest ingest hook to backfill into (required)",
+                },
+                {
+                    name: "file",
+                    value: "<path>",
+                    description: "Path to a JSON-array or NDJSON file of raw provider payloads, one whole body per entry (required)",
+                },
+                {
+                    name: "chunk",
+                    value: "<n>",
+                    description: "Bodies per relay call (default 500); the file is split across as many calls as needed",
+                },
+            ],
+        },
     ],
     notes: [
         "--app accepts either the app_id or its slug (resolved via GET /v1/apps?slug= when it does not look like a cuid).",
@@ -466,6 +492,7 @@ const INGEST = {
         "rotate mints a fresh secret for the named hook and returns { hook: { name, url } } with the NEW url once. The old url stops working immediately; no redeploy is needed. Use it when a url leaks.",
         "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.",
     ],
 };
 const GRANTS = {
@@ -955,6 +982,238 @@ const AGENT = {
         "logout clears the active profile only, leaving the other profiles on disk and unsetting current_profile, while --all deletes the whole config file. It is idempotent, and it touches only LOCAL config: it does NOT revoke the key on the relay, which keeps working until 'homespun key revoke' retires it.",
     ],
 };
+const PUBLISHER = {
+    noun: "publisher",
+    tagline: "community publisher identity",
+    group: "other",
+    rootSummary: "Your community publisher identity: claim (set the permanent handle), show, update (display name, bio, website), and set-trust (operator only).",
+    verbs: [
+        {
+            verb: "claim",
+            positionals: "<handle>",
+            summary: "Claims your one permanent publisher handle.",
+        },
+        {
+            verb: "show",
+            summary: "Shows your own publisher profile.",
+        },
+        {
+            verb: "update",
+            summary: "Updates your publisher display name, bio, or website.",
+            flags: [
+                {
+                    name: "display-name",
+                    value: "<name>",
+                    description: "Public display name",
+                },
+                { name: "bio", value: "<text>", description: "Short publisher bio" },
+                {
+                    name: "website",
+                    value: "<url>",
+                    description: "Public website or profile link",
+                },
+            ],
+        },
+        {
+            verb: "set-trust",
+            positionals: "<handle> <new|established>",
+            summary: "Sets a publisher's trust level (operator only).",
+        },
+    ],
+    notes: [
+        "All verbs act as the calling agent's owning human. The handle is set ONCE by claim and is permanent afterward; claim and update additionally need a verified email server-side.",
+        "update requires at least one of --display-name, --bio, or --website. The website field maps to the profile url; it is spelled --website here because --url is the global relay-target override.",
+        "set-trust promotes a publisher to established (the review fast-track) or back to new. It is operator-gated server-side and rejects a caller who is not the relay operator.",
+    ],
+};
+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).",
+    verbs: [
+        {
+            verb: "publish",
+            positionals: "<app>",
+            summary: "Publishes an owned app as a pending community template.",
+            flags: [
+                {
+                    name: "title",
+                    value: "<text>",
+                    description: "Listing title, defaults to the manifest name",
+                },
+                {
+                    name: "description",
+                    value: "<text>",
+                    description: "Short listing blurb, defaults to the manifest one",
+                },
+                {
+                    name: "long-description",
+                    value: "<text>",
+                    description: "Long-form description shown on the detail page",
+                },
+                {
+                    name: "category",
+                    value: "<name>",
+                    description: "Listing category, validated server-side",
+                },
+                {
+                    name: "tags",
+                    value: "<path|json>",
+                    description: "Curation tags as inline JSON or a path to a JSON file",
+                },
+                {
+                    name: "slug",
+                    value: "<slug>",
+                    description: "Per-publisher slug for a namespaced, versioned line",
+                },
+                {
+                    name: "version",
+                    value: "<semver>",
+                    description: "Semver version, defaults to 1.0.0",
+                },
+                {
+                    name: "changelog-note",
+                    value: "<text>",
+                    description: "Note recorded in this version's changelog",
+                },
+                {
+                    name: "setup-steps",
+                    value: "<path|json>",
+                    description: "Typed setup steps as inline JSON or a JSON file path",
+                },
+            ],
+            bools: [
+                {
+                    name: "attest-example-only",
+                    description: "Attest the template and seed rows carry no real data",
+                },
+            ],
+        },
+        {
+            verb: "config-contract",
+            positionals: "<ref>",
+            summary: "Shows a template's install-time config contract.",
+        },
+        {
+            verb: "install",
+            positionals: "<ref>",
+            summary: "Installs a community template for your owning human.",
+            flags: [
+                {
+                    name: "config",
+                    value: "<path|json>",
+                    description: "Install config as inline JSON or a path to a JSON file",
+                },
+            ],
+        },
+        {
+            verb: "list-pending",
+            summary: "Lists pending submissions in the review queue (operator only).",
+            flags: [
+                { name: "limit", value: "<n>", description: "Page size" },
+                { name: "cursor", value: "<cursor>", description: "Page cursor" },
+            ],
+        },
+        {
+            verb: "show",
+            positionals: "<snapshot-id>",
+            summary: "Shows one submission's full content (operator only).",
+        },
+        {
+            verb: "approve",
+            positionals: "<snapshot-id>",
+            summary: "Approves a pending submission (operator only).",
+        },
+        {
+            verb: "reject",
+            positionals: "<snapshot-id>",
+            summary: "Rejects a pending submission with a note (operator only).",
+            flags: [
+                {
+                    name: "note",
+                    value: "<note>",
+                    description: "Reason sent to the publisher's app feed (required)",
+                },
+            ],
+        },
+    ],
+    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.",
+        "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.",
+    ],
+};
+const REVIEW = {
+    noun: "review",
+    tagline: "community template reviews",
+    group: "other",
+    rootSummary: "Community template reviews: create a star review for a template you installed, respond as the publisher, report a review, and remove or unhold one (operator only).",
+    verbs: [
+        {
+            verb: "create",
+            positionals: "<ref>",
+            summary: "Creates a star review for a template you installed.",
+            flags: [
+                {
+                    name: "stars",
+                    value: "<1-5>",
+                    description: "Star rating, an integer from 1 to 5 (required)",
+                },
+                {
+                    name: "body",
+                    value: "<text>",
+                    description: "Optional written review body",
+                },
+            ],
+        },
+        {
+            verb: "respond",
+            positionals: "<review-id>",
+            summary: "Responds to a review as the publisher.",
+            flags: [
+                {
+                    name: "response",
+                    value: "<text>",
+                    description: "Publisher response text",
+                },
+            ],
+            bools: [
+                {
+                    name: "clear",
+                    description: "Clear the existing publisher response",
+                },
+            ],
+        },
+        {
+            verb: "report",
+            positionals: "<review-id>",
+            summary: "Reports a review for operator attention.",
+            flags: [
+                {
+                    name: "reason",
+                    value: "<reason>",
+                    description: "Why the review is being reported (required)",
+                },
+            ],
+        },
+        {
+            verb: "remove",
+            positionals: "<review-id>",
+            summary: "Removes a review (operator only).",
+        },
+        {
+            verb: "unhold",
+            positionals: "<review-id>",
+            summary: "Publishes a held review (operator only).",
+        },
+    ],
+    notes: [
+        "create identifies the template by its namespaced <handle>/<slug> ref, and you must have installed it. --stars is an integer 1 to 5; --body is optional. A body containing a link or email may land held for moderation.",
+        "respond acts as the publisher on your own template's review: exactly one of --response <text> or --clear is required, where --clear removes the existing response by sending null.",
+        "report flags a review for the operator with a --reason. remove and unhold are operator-gated moderation actions: remove takes a review down, unhold publishes a held review.",
+    ],
+};
 // Order here is the order in `homespun --help` and in the generated reference
 // page: app commands first, then the rest.
 const NOUNS = [
@@ -964,6 +1223,9 @@ const NOUNS = [
     MEMBERS,
     GRANTS,
     INGEST,
+    PUBLISHER,
+    TEMPLATE,
+    REVIEW,
     KEY,
     TASTE,
     FEEDBACK,

package/dist/index.js

@@ -39,6 +39,9 @@ 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 { runPublisher } from "./commands/publisher.js";
+import { runTemplate } from "./commands/template.js";
+import { runReview } from "./commands/review.js";
 import { VERSION } from "./version.js";
 import { HomespunApiError } from "@homespunapps/core";
 import { failUpgradeRequired } from "./output.js";
@@ -129,6 +132,15 @@ async function main() {
         case "ingest":
             await runIngest(args);
             break;
+        case "publisher":
+            await runPublisher(args);
+            break;
+        case "template":
+            await runTemplate(args);
+            break;
+        case "review":
+            await runReview(args);
+            break;
     }
 }
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "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.6.0",
+    "@homespunapps/core": "^1.6.2",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {