@sprid/cli 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 0.1.4 - 2026-09-23
+
+- `sprid whoami` warns when the credentials file is readable by other users
+  on the machine, with the `chmod 600` that fixes it, and reports
+  `credentialsFileSecure` in `--json`.
+- `sprid docs` carries the tightened connect guides and the new distribution,
+  first-seconds and store-listing guides.
+- `sprid post create --file` saves an idea when the file says `"status":
+  "idea"`: notes, a `sourceUrl` and any gathered assets, with no assets
+  required. The same `requestId` makes a retry safe, so a repo's hook bank
+  can be pushed in and pushed again.
+- `sprid family` is removed with market editions, which the server no longer
+  has. `sprid apps`, `sprid insights` and `sprid account` are unchanged.
+
+## 0.1.3 - 2026-09-23
+
+- Posts and reviews have refs: `BND-78` is post 78 of the account keyed BND,
+  `BND-R4` is review 4 of the app keyed BND. Every command that takes a post id
+  takes its ref, and `sprid reviews draft|reply` take a review ref. `sprid
+  status` and the review mail print refs, which older versions refuse.
+- `sprid reviews reply` reads the one review it replies to, so a review
+  older than the latest hundred can be answered from its draft.
+- `sprid account avatar <account> [file|url]` sets an account's avatar; with
+  no source it uses the app's own icon. `sprid init` reports the avatar it set.
+
 ## 0.1.2 - 2026-09-22
 
 - Published as `@sprid/cli`. The command is still `sprid`.

package/README-post.md

@@ -269,7 +269,6 @@ the *copy* here anyway:
 carousels: {
   kind: "composed",
   spec: "social/specs/<slug>.json",
-  // format: <format id>,        // choose from this account’s formats
   // template: <template id>,    // choose from this account’s templates
   expect: { slides: [5, 9], words: [0, 30] },
   neverSay: ["the phrase this account decided it does not say"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprid/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The Sprid command line: connect your app, review results, prepare posts and store screenshots, and release mobile apps.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/cli.mjs

@@ -29,7 +29,7 @@ import * as mcp from "./commands/mcp.mjs";
 import * as reviews from "./commands/reviews.mjs";
 import { marketingReview } from "./commands/marketing-review.mjs";
 import { plan, research } from './commands/plan.mjs';
-import { apps, family, insights, account } from "./commands/family.mjs";
+import { apps, insights, account } from "./commands/family.mjs";
 import * as post from "./commands/post.mjs";
 import { docs } from "./commands/docs.mjs";
 import { screenshots, release } from './commands/local-tools.mjs';
@@ -55,7 +55,7 @@ export const COMMANDS = {
   plan, research,
   media, capabilities, completion,
   screenshots, release, doctor, update,
-  apps, family, insights, account,
+  apps, insights, account,
   docs,
   login: auth.login,
   logout: auth.logout,

package/src/commands/auth.mjs

@@ -2,7 +2,7 @@
 // a long secret, the person types a short code into a signed-in browser, and
 // the server hands over a personal access token exactly once.
 
-import { DEFAULT_API_URL, deleteCredentials, credentialsPath, readCredentials, stripSlash, writeCredentials } from "../creds.mjs";
+import { DEFAULT_API_URL, deleteCredentials, credentialsModeOk, credentialsPath, readCredentials, stripSlash, writeCredentials } from "../creds.mjs";
 import { ApiError } from "../http.mjs";
 import { C, OK } from "../format.mjs";
 import { pickWorkspace } from "../cli.mjs";
@@ -124,6 +124,8 @@ export async function whoami(ctx) {
   // The current one, if it can be known without asking; never exit 2 from whoami.
   const current = await ctx.workspace().catch(() => null);
   const source = a.source === "env" ? "SPRID_PAT" : credentialsPath(ctx.env);
+  // Written 0600, but a later copy, restore or chmod can loosen it silently.
+  const fileSecure = a.source === "env" ? null : credentialsModeOk(ctx.env);
   if (ctx.json) {
     ctx.out({
       email: user.email ?? a.email ?? null,
@@ -133,6 +135,7 @@ export async function whoami(ctx) {
       apiUrl: a.apiUrl,
       tokenSource: source,
       tokenId: a.tokenId,
+      credentialsFileSecure: fileSecure,
     });
     return 0;
   }
@@ -143,6 +146,9 @@ export async function whoami(ctx) {
       : "no workspace";
   ctx.print(`  ${user.email ?? a.email ?? "(unknown)"} · workspace ${wsLine}`);
   ctx.print(C.dim(`  ${a.apiUrl} · token from ${source}`));
+  if (fileSecure === false) {
+    ctx.print(`  Warning: ${source} is readable by other users on this machine. Fix: chmod 600 "${source}"`);
+  }
   if (workspaces.length > 1) {
     ctx.print(workspaceList(workspaces, current));
     if (!current) ctx.print(C.dim("  Pick one: sprid use <slug>"));

package/src/commands/family.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { extname, resolve } from "node:path";
 import { UsageError } from "../args.mjs";
 import { resolveProfile } from "../profiles.mjs";
 
@@ -18,53 +18,13 @@ function objectFile(ctx) {
 function positiveId(raw) {
   const id = Number(raw);
   if (!Number.isInteger(id) || id <= 0)
-    throw new UsageError("Pass a positive family or edition ID.");
+    throw new UsageError("Pass a positive account ID.");
   return id;
 }
 export async function apps(ctx) {
   ctx.out(await ctx.api().get("/api/app-profiles/hierarchy"));
   return 0;
 }
-export async function family(ctx) {
-  const [verb = "list", raw] = ctx.positionals;
-  let result;
-  if (verb === "list" || verb === "compare") {
-    const workspaceId = await ctx.workspaceId();
-    const app = await resolveProfile(ctx, workspaceId);
-    result = await ctx
-      .api()
-      .get(
-        `/api/content-families${verb === "compare" ? "/performance" : ""}?workspaceId=${workspaceId}&app=${app.id}&ageDays=${encodeURIComponent(ctx.flags.days ?? 7)}`,
-      );
-  } else if (verb === "create")
-    result = await ctx.api().post("/api/content-families", objectFile(ctx));
-  else {
-    const id = positiveId(raw);
-    const edition = ["get", "preview", "review", "localize"].includes(verb);
-    const path = edition
-      ? `/api/content-families/editions/${id}`
-      : `/api/content-families/${id}`;
-    if (verb === "get") result = await ctx.api().get(path);
-    else if (verb === "preview")
-      result = await ctx.api().post(`${path}/preview`, {});
-    else if (
-      ["edition", "review", "localize", "plan", "schedule"].includes(verb)
-    )
-      result = await ctx
-        .api()
-        .post(
-          `${path}/${verb === "edition" ? "editions" : verb}`,
-          objectFile(ctx),
-        );
-    else
-      throw new UsageError(
-        "sprid family list|create|edition|get|localize|preview|review|plan|schedule|compare [id] [--file payload.json]",
-      );
-  }
-  // Always print exact IDs, preview URLs, blockers and revision fingerprints.
-  ctx.out(result);
-  return 0;
-}
 export async function insights(ctx) {
   const workspaceId = await ctx.workspaceId();
   const app = await resolveProfile(ctx, workspaceId);
@@ -88,9 +48,39 @@ export async function account(ctx) {
         .api()
         .patch(`/api/accounts/${positiveId(raw)}`, objectFile(ctx)),
     );
+  else if (verb === "avatar") return accountAvatar(ctx, raw, ctx.positionals[2]);
   else
     throw new UsageError(
-      "sprid account create|update [id] --file payload.json",
+      "sprid account create|update [id] --file payload.json | sprid account avatar <account> [file|url]",
     );
   return 0;
 }
+
+const AVATAR_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp" };
+
+// The account's avatar: what Sprid's mails and the account.avatarUrl template
+// binding draw. No source = the app's own icon, looked up by the server.
+async function accountAvatar(ctx, ref, source) {
+  if (!ref) throw new UsageError("sprid account avatar <account> [file|url]");
+  const account = encodeURIComponent(String(ref));
+  if (!source || /^https?:\/\//i.test(source)) {
+    const result = await ctx.api().post(`/api/accounts/${account}/avatar/from-url`, source ? { url: source } : {});
+    if (ctx.flags.json) ctx.out(result);
+    else ctx.print(`Avatar set from ${result.source} (${result.size}): ${result.avatarUrl}`);
+    return 0;
+  }
+  const path = resolve(ctx.cwd, source);
+  const ext = extname(path).toLowerCase();
+  const contentType = AVATAR_TYPES[ext];
+  if (!contentType) throw new UsageError("The avatar must be a PNG, JPEG or WebP file. SVG and ICO do not render in mail clients.");
+  const bytes = readFileSync(path);
+  if (bytes.length > 5 * 1024 * 1024) throw new UsageError("The avatar file is over 5 MB. Export the icon at 512 or 1024 px.");
+  const api = ctx.api();
+  const { uploadUrl, key } = await api.post(`/api/accounts/${account}/avatar/upload-url`, { contentType });
+  const put = await (ctx.fetch ?? fetch)(uploadUrl, { method: "PUT", headers: { "content-type": contentType }, body: bytes, redirect: "error", signal: AbortSignal.timeout(60000) });
+  if (!put.ok) throw new Error(`Uploading the avatar failed (${put.status}).`);
+  const result = await api.post(`/api/accounts/${account}/avatar/confirm`, { key });
+  if (ctx.flags.json) ctx.out(result);
+  else ctx.print(`Avatar set from ${source}: ${result.avatarUrl}`);
+  return 0;
+}

package/src/commands/init.mjs

@@ -128,6 +128,7 @@ export async function init(ctx) {
   ctx.print(`  ${C.ok(OK)} ${existing ? "Updated" : "Created"} App Profile ${C.bold(profile.slug)} (${profile.name}) from ${source}`);
   const set = PROFILE_FIELDS.filter((k) => k !== "slug" && k !== "name" && profile[k]).map((k) => [k, profile[k]]);
   if (set.length) ctx.print(table(set, { indent: "    " }));
+  if (profile.avatar) ctx.print(`  ${C.ok(OK)} Avatar for ${profile.avatar.accounts.join(", ")} from the ${profile.avatar.source} icon (${profile.avatar.size})`);
   if (missing.length) {
     ctx.print("  Still missing:");
     ctx.print(table(missing.map((m) => [`${NONE} ${m.label.split(" · ")[0]}`, C.dim("→"), m.cli]), { indent: "    " }));

package/src/commands/reviews.mjs

@@ -70,18 +70,24 @@ export function renderReview(r) {
   return lines.join("\n");
 }
 
+// A review is named by its row id (41) or its ref (BND-R41); the server
+// resolves either, so the CLI only checks the shape.
 function needId(arg, usage) {
-  const id = Number(arg);
-  if (!Number.isInteger(id) || id <= 0) throw new UsageError(usage);
-  return id;
+  const id = String(arg ?? "").trim();
+  if (/^[1-9]\d*$/.test(id)) return Number(id); // --json keeps printing a number
+  if (/^[A-Za-z][A-Za-z0-9]{1,4}-[Rr]\d+$/.test(id)) return id.toUpperCase();
+  throw new UsageError(usage);
 }
 
+/** `BND-R41` as is; a bare row id as `#41`. */
+const label = (id) => (/^\d+$/.test(String(id)) ? `#${id}` : String(id));
+
 async function draft(ctx, arg) {
-  const id = needId(arg, "sprid reviews draft <id>");
-  const res = await ctx.api().post(`/api/store-reviews/${id}/draft`);
+  const id = needId(arg, "sprid reviews draft <id|ref>");
+  const res = await ctx.api().post(`/api/store-reviews/${encodeURIComponent(id)}/draft`);
   if (ctx.json) ctx.out(res);
   else {
-    ctx.print(`  Draft for review #${id}:`);
+    ctx.print(`  Draft for review ${label(id)}:`);
     ctx.print(`  ${res.draftReply ?? ""}`);
     ctx.print(C.dim(`  Send it: sprid reviews reply ${id}   (edit first: --text "…")`));
   }
@@ -89,15 +95,18 @@ async function draft(ctx, arg) {
 }
 
 async function reply(ctx, arg) {
-  const id = needId(arg, "sprid reviews reply <id> [--text …] [--yes]");
-  // No GET /api/store-reviews/:id exists; the list (max 100, newest first) is
-  // the lookup. Good enough for a reply, which is about a recent review.
-  const rows = await fetchReviews(ctx, { limit: 100 });
-  const row = rows.find((r) => r.id === id);
+  const id = needId(arg, "sprid reviews reply <id|ref> [--text …] [--yes]");
+  // The one review, by id or ref. Any age, not only the latest hundred.
+  let row = null;
+  try {
+    row = (await ctx.api().get(`/api/store-reviews/${encodeURIComponent(id)}`)).review ?? null;
+  } catch (err) {
+    if (!(err instanceof ApiError) || err.status !== 404) throw err;
+  }
   let text = ctx.flags.text && ctx.flags.text !== true ? String(ctx.flags.text) : null;
   if (!text) {
-    if (!row) throw new ApiError(404, `Review #${id} is not among the latest 100${ctx.flags.app ? ` for ${ctx.flags.app}` : ""}; pass --text to reply anyway.`);
-    if (!row.draftReply) throw new UsageError(`Review #${id} has no draft. Run \`sprid reviews draft ${id}\` or pass --text.`);
+    if (!row) throw new ApiError(404, `Review ${label(id)} was not found; pass --text to reply anyway.`);
+    if (!row.draftReply) throw new UsageError(`Review ${label(id)} has no draft. Run \`sprid reviews draft ${id}\` or pass --text.`);
     text = row.draftReply;
   }
   const source = row?.source ?? null;
@@ -113,13 +122,13 @@ async function reply(ctx, arg) {
       if (ctx.json) {
         ctx.out({ ok: false, error: msg, id, text, store: source, limit });
       } else {
-        ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review #${id}:`);
+        ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review ${label(row?.ref ?? id)}:`);
         ctx.print(`  ${text}`);
         ctx.warn(`  ✗ ${msg}`);
       }
       return 2;
     }
-    ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review #${id}:`);
+    ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review ${label(row?.ref ?? id)}:`);
     if (row) ctx.print(C.dim(`  re: ${stars(row.rating)} ${truncate([row.title, row.body].filter(Boolean).join(" · "), 120)}`));
     ctx.print("");
     ctx.print(`  ${text}`);
@@ -131,9 +140,9 @@ async function reply(ctx, arg) {
     }
   }
 
-  const res = await ctx.api().post(`/api/store-reviews/${id}/reply`, { text });
+  const res = await ctx.api().post(`/api/store-reviews/${encodeURIComponent(id)}/reply`, { text });
   if (ctx.json) ctx.out({ ok: true, id, text, review: res.review ?? null });
-  else ctx.print(`  ${C.ok(OK)} Reply sent for review #${id}${source ? ` on ${STORE_LABEL[source]}` : ""}.`);
+  else ctx.print(`  ${C.ok(OK)} Reply sent for review ${label(row?.ref ?? id)}${source ? ` on ${STORE_LABEL[source]}` : ""}.`);
   return 0;
 }
 

package/src/commands/studio.mjs

@@ -11,10 +11,12 @@ async function payload(ctx) {
 }
 export async function remotePost(ctx) {
   const [verb, ref] = ctx.positionals;
-  const id = ctx.flags.id ?? ref;
+  let id = ctx.flags.id ?? ref;
   if (!['create', 'get', 'update', 'deliveries', 'handoff'].includes(verb) && !(verb === 'preview' && ctx.flags.id)) return false;
-  if (verb !== 'create' && !/^[1-9]\d*$/.test(String(id))) throw new UsageError('Supply the positive server post ID. Local preview slugs remain unchanged.');
+  // The server post id (271) or its ref (BND-78); the server resolves either.
+  if (verb !== 'create' && !/^([1-9]\d*|[A-Za-z][A-Za-z0-9]{1,4}-\d+)$/.test(String(id))) throw new UsageError('Supply the server post ID or its ref, such as 271 or BND-78. Local preview slugs remain unchanged.');
   const api = ctx.api();
+  if (verb !== 'create') id = encodeURIComponent(String(id).toUpperCase());
   const result = verb === 'create' ? await api.post('/api/studio/posts', await payload(ctx))
     : verb === 'update' ? await api.patch(`/api/posts/${id}`, await payload(ctx))
     : verb === 'preview' ? await api.get(`/api/studio/posts/${id}/preview`)

package/src/docs/commands.mjs

@@ -28,8 +28,8 @@ export const COMMAND_GROUPS = [
     ['media', 'sprid media reel --file <recipe.json>', 'Create a metered hosted photos/text reel after explicit user authorization. Returns a durable job ID.'],
     ['media', 'sprid media job <UUID>', 'Read saved upload results or creation progress without repeating the operation.'],
     ['media', 'sprid media init|build|register|check|push|preview …', 'Run the existing local media pipeline. Historical sprid post invocations remain supported.'],
-    ['post', 'sprid post create --file <draft.json>', 'Create a shared draft from ordered asset references and a stable requestId. Never publishes.'],
-    ['post', 'sprid post get <postId>', 'Read the shared post and its slides.'],
+    ['post', 'sprid post create --file <draft.json>', 'Create a shared draft from ordered asset references and a stable requestId. With "status": "idea" it saves an idea instead: notes, a sourceUrl and any gathered assets, before layout. Never publishes.'],
+    ['post', 'sprid post get <postId>', 'Read the shared post and its slides. Every <postId> here takes the number or the post\'s ref, such as BND-142.'],
     ['post', 'sprid post update <postId> --file <changes.json>', 'Apply the existing post-update contract to a shared draft.'],
     ['post', 'sprid post preview --id <postId>', 'Preview a shared post. Without --id, historical local preview arguments are unchanged.'],
     ['post', 'sprid post deliveries <postId>', 'Read scheduled, failed and delivered publications with platform receipts.'],
@@ -45,18 +45,11 @@ export const COMMAND_GROUPS = [
     ['release', 'sprid release metadata|screenshots|graphics [--config release.config.ts] [--execute]', 'Preview store listing changes locally; --execute sends the reviewed changes. Requires Bun.'],
     ['release', 'sprid release ship [--execute] [--ios-only|--android-only]', 'Build and submit your app using its release configuration. Dry run by default; use --help for all options.'],
   ] },
-  { title: 'Apps and market editions', entries: [
+  { title: 'Apps and accounts', entries: [
     ['account', 'sprid account create|update [id] --file payload.json', 'Create an app content account or update its identity. Creation requires workspaceId, appProfileId, name and slug; market, locale, persona and timezone are explicit.'],
+    ['account', 'sprid account avatar <account> [file|url]', 'Set the avatar Sprid’s mails and templates draw. No source uses the app’s icon: App Store artwork, else the website’s manifest or touch icon. A file must be PNG, JPEG or WebP; a 1024 px app icon from the repo is the best source.'],
     ['apps', 'sprid apps', 'List apps with their content accounts and workspace IDs.'],
     ['insights', 'sprid insights --app <slug> [--account <slug>] [--days N]', 'Read app results once, with social content optionally narrowed to one account.'],
-    ['family', 'sprid family compare --app <slug> [--days N]', 'Compare themes at matched post age with sample counts and channel baselines.'],
-    ['family', 'sprid family list --app <slug>', 'List content families, themes and market editions.'],
-    ['family', 'sprid family create --file payload.json', 'Create a family: sourcePostId, title, theme and sourceReference.'],
-    ['family', 'sprid family edition <familyId> --file payload.json', 'Copy an independent draft: accountId, locale and market. Translate it in the editor or through the API.'],
-    ['family', 'sprid family localize <postId> --file payload.json', 'Save translated captions and slide text or reel beats atomically, clearing old approval.'],
-    ['family', 'sprid family get|preview <postId>', 'Read the edition or render its current content for review.'],
-    ['family', 'sprid family review <postId> --file payload.json', 'Approve a rendered revision with fingerprint, sourceReference and confirmed: true.'],
-    ['family', 'sprid family plan|schedule <familyId> --file payload.json', 'Plan exact postId/channelId/scheduledFor destinations. Scheduling also requires the returned planFingerprint.'],
   ] },
   { title: 'Sign in', entries: [
     ['setup', 'sprid setup begin --file <artifact> --task publish|review|repo [--source <source>] [--entry website|installed-skill|browser|paid]', 'Save the first useful result locally before signup. Repeating begin preserves the same task and retry key.'],