@madewithremy/admin 0.1.31 → 0.1.33

package/dist/prod.js

@@ -1019,13 +1019,6 @@ async function dashboardLive(ctx) {
   );
   return dashboard.liveRelease;
 }
-function buildFailureReason(release) {
-  const log = Array.isArray(release.buildLog) ? release.buildLog : [];
-  const errors = log.filter(
-    (entry) => entry?.phase === "error" && typeof entry.message === "string"
-  );
-  return errors.length ? errors[errors.length - 1].message : null;
-}
 function summarizeRelease(release) {
   const summary2 = {
     releaseId: release.id,
@@ -1048,7 +1041,7 @@ function summarizeRelease(release) {
   }
   return {
     ...summary2,
-    error: release.failureReason ?? buildFailureReason(release) ?? "Build failed (no error entry in the build log)",
+    error: release.failureReason ?? "Build failed (no error entry in the build log)",
     ...release.failureKind ? { failureKind: release.failureKind } : {},
     ...release.failurePhase ? { failurePhase: release.failurePhase } : {}
   };
@@ -2946,7 +2939,7 @@ var filesSpecs = {
     usage: "Usage: remy-admin files list"
   },
   "files rm": {
-    usage: "Usage: remy-admin files rm --store <name> --key <key> [--private]",
+    usage: "Usage: remy-admin files rm --store <name> --key <key> [--public|--private]",
     flags: {
       ...ACCESS_FLAGS,
       store: { type: "string" },
@@ -2957,6 +2950,45 @@ var filesSpecs = {
 function resolveAccess(a) {
   return a.bool("private") ? "private" : "public";
 }
+async function readAccess(ctx, a, key) {
+  if (a.bool("private")) {
+    return "private";
+  }
+  if (a.bool("public")) {
+    return "public";
+  }
+  const store = storeOf(a);
+  const { stores } = await summary(ctx);
+  const held = stores.filter((s) => s.store === store && s.objectCount > 0);
+  if (held.length === 1) {
+    return held[0].access;
+  }
+  if (held.length === 0) {
+    if (key === void 0) {
+      return "public";
+    }
+    fatal(`Store "${store}" holds no objects, public or private.`);
+  }
+  if (key === void 0) {
+    const counts = held.map((s) => `${s.objectCount.toLocaleString()} ${s.access}`).join(", ");
+    fatal(
+      `Store "${store}" holds objects in both halves (${counts}): pass --public or --private.`
+    );
+  }
+  for (const access of ["private", "public"]) {
+    try {
+      await stat(ctx, { store, access, key });
+      return access;
+    } catch (err) {
+      if (!(err instanceof AdminApiError) || err.status !== 404) {
+        throw err;
+      }
+    }
+  }
+  fatal(
+    `No object "${key}" in store "${store}" (looked in its private and public halves).`
+  );
+}
 function storeOf(a) {
   return a.str("store") || DEFAULT_STORE;
 }
@@ -2967,8 +2999,8 @@ function requireKeyFlag(a) {
   }
   return key;
 }
-function refOf(a, key) {
-  return { store: storeOf(a), access: resolveAccess(a), key };
+async function refOf(ctx, a, key) {
+  return { store: storeOf(a), access: await readAccess(ctx, a, key), key };
 }
 async function filesPut(ctx, a) {
   const file = a.req("file");
@@ -2994,7 +3026,7 @@ async function filesPut(ctx, a) {
 }
 async function filesGet(ctx, a) {
   const key = a.req("key");
-  const ref = refOf(a, key);
+  const ref = await refOf(ctx, a, key);
   const { url } = await sign(
     ctx,
     ref,
@@ -3004,7 +3036,9 @@ async function filesGet(ctx, a) {
   const abs = path2.isAbsolute(outPath) ? outPath : path2.join(WORKSPACE_DIR, outPath);
   const res = await fetch(url);
   if (!res.ok || !res.body) {
-    fatal(`Download failed: ${res.status} ${res.statusText}`);
+    fatal(
+      res.status === 403 || res.status === 404 ? `No object "${key}" in the ${ref.access} half of store "${ref.store}" (download answered ${res.status}).` : `Download failed: ${res.status} ${res.statusText}`
+    );
   }
   await pipeline(
     Readable.fromWeb(res.body),
@@ -3013,16 +3047,18 @@ async function filesGet(ctx, a) {
   out({ path: abs, size: fs2.statSync(abs).size });
 }
 async function filesSign(ctx, a) {
-  out(await sign(ctx, refOf(a, requireKeyFlag(a)), a.num("ttl")));
+  out(
+    await sign(ctx, await refOf(ctx, a, requireKeyFlag(a)), a.num("ttl"))
+  );
 }
 async function filesStat(ctx, a) {
-  out(await stat(ctx, refOf(a, requireKeyFlag(a))));
+  out(await stat(ctx, await refOf(ctx, a, requireKeyFlag(a))));
 }
 async function filesLs(ctx, a) {
   out(
     await ls(ctx, {
       store: storeOf(a),
-      access: resolveAccess(a),
+      access: await readAccess(ctx, a),
       prefix: a.str("prefix"),
       q: a.str("q"),
       cursor: a.str("cursor"),
@@ -3042,7 +3078,13 @@ async function filesRm(ctx, a) {
   if (!key) {
     fatal("--key is required.");
   }
-  out(await remove(ctx, { store, access: resolveAccess(a), key }));
+  out(
+    await remove(ctx, {
+      store,
+      access: await readAccess(ctx, a, key),
+      key
+    })
+  );
 }
 var filesHandlers = {
   "files put": filesPut,
@@ -3066,12 +3108,12 @@ Subcommands:
 
 Usage:
   remy-admin files put [--public|--private] [--store <name>] [--key <key>] [--cache-control <value>] <file>
-  remy-admin files get [--private] [--store <name>] [--out <path>] <key>
-  remy-admin files sign [--private] [--store <name>] [--ttl <seconds>] --key <key>
-  remy-admin files stat [--private] [--store <name>] --key <key>
-  remy-admin files ls [--private] [--store <name>] [--prefix <prefix>] [--q <substring>] [--limit <n>]
+  remy-admin files get [--public|--private] [--store <name>] [--out <path>] <key>
+  remy-admin files sign [--public|--private] [--store <name>] [--ttl <seconds>] --key <key>
+  remy-admin files stat [--public|--private] [--store <name>] --key <key>
+  remy-admin files ls [--public|--private] [--store <name>] [--prefix <prefix>] [--q <substring>] [--limit <n>]
   remy-admin files list
-  remy-admin files rm --store <name> --key <key> [--private]
+  remy-admin files rm --store <name> --key <key> [--public|--private]
 
 Examples:
   remy-admin files put --public ./hero.jpg
@@ -3081,7 +3123,10 @@ Examples:
   remy-admin files rm --store handoff --key <key> --private
 
 Notes:
-  - Defaults to a public store named 'assets'; pass --private / --store to change.
+  - Defaults to the store named 'assets'. put writes public unless --private.
+    Reads (get, sign, stat, ls, rm) without --public or --private use the half
+    of the store that holds objects; in a store holding both, a key is found
+    wherever it is, and ls asks which.
   - Handing someone a large or sensitive file? Use a PRIVATE store + \`sign\`:
     the link is unguessable, expires (--ttl seconds, max 7 days), and the object
     stays deletable with \`rm\`. Never use the account media CDN
@@ -3119,6 +3164,7 @@ var summarize = (d) => ({
 });
 async function addDocument(ctx, params) {
   const { slug, filename, content, metadata, entities: entities2, onProgress } = params;
+  const { budgetDollars } = params;
   const contentHash = createHash2("sha256").update(content).digest("hex");
   const token = await call(
     ctx,
@@ -3134,11 +3180,13 @@ async function addDocument(ctx, params) {
   );
   if (token.alreadyCurrent) {
     onProgress?.(`${filename}: unchanged, skipped`);
+    const documents3 = token.documents ?? [token.document];
     return {
       filename,
       skipped: true,
       document: token.document,
-      documents: token.documents ?? [token.document]
+      documents: documents3,
+      documentCount: token.documentCount ?? documents3.length
     };
   }
   onProgress?.(
@@ -3156,16 +3204,21 @@ async function addDocument(ctx, params) {
       contentType: token.contentType,
       size: content.length,
       ...metadata ? { metadata } : {},
-      ...entities2 ? { entities: entities2 } : {}
+      ...entities2 ? { entities: entities2 } : {},
+      ...budgetDollars !== void 0 ? { budgetDollars } : {}
     }
   );
+  const documents2 = confirmed.documents ?? (confirmed.document ? [confirmed.document] : []);
   return {
     filename,
     skipped: false,
     queued: confirmed.queued,
     document: confirmed.document,
-    documents: confirmed.documents ?? (confirmed.document ? [confirmed.document] : []),
-    outcome: confirmed.outcome
+    documents: documents2,
+    documentCount: confirmed.documentCount ?? documents2.length,
+    outcome: confirmed.outcome,
+    invalid: confirmed.invalid ?? null,
+    job: confirmed.job ?? null
   };
 }
 async function waitForIngest(ctx, params) {
@@ -3347,6 +3400,21 @@ function entities(ctx, params) {
     }
   );
 }
+function passages(ctx, params) {
+  const { slug, filter, cursor, limit, candidate } = params;
+  return call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/passages`,
+    {
+      slug,
+      ...filter ? { filter } : {},
+      ...cursor ? { cursor } : {},
+      ...limit !== void 0 ? { limit } : {},
+      ...candidate ? { candidate: true } : {}
+    }
+  );
+}
 function configGet(ctx, slug) {
   return call(
     ctx,
@@ -4870,12 +4938,14 @@ Dictionary:
   background (a relink; \`dictionary status\` shows it), with nothing
   re-embedded. An unchanged dictionary commits nothing.
 
-  Matching ignores case and a tag's separators (P-101A, P101A, p 101a), takes
+  Matching ignores case and a tag's separators (P-101A, P101A, p 101a) and
+  an inch or foot mark after a size (8"-P-1057-A1A is 8-P-1057-A1A), takes
   whole words only (P-101AB is not P-101A), and prefers the longest name; a
   name two ids claim tags both. A name needs three letters or digits (two in
   Chinese, Japanese or Korean). The push reports ambiguous names, the most
-  claimed, and names that can't match their own text as written
-  (\`unmatchable\`). Up to 250,000 entries, 16 names each, a million names.
+  claimed (each with one name as pushed), and names that can't match their
+  own text as written (\`unmatchable\`). Up to 250,000 entries, 16 names
+  each, a million names.
 
   \`link\` shows what the current dictionary finds in any text: check one
   there before relying on it. --linker-version moves a dictionary to a newer
@@ -5179,7 +5249,8 @@ function mapTest(ctx, params) {
       ...selectionBody(params.selection),
       ...params.keys ? { keys: params.keys } : {},
       ...params.limit !== void 0 ? { limit: params.limit } : {},
-      ...params.dev ? { dev: true } : {}
+      ...params.dev ? { dev: true } : {},
+      ...params.releaseId ? { releaseId: params.releaseId } : {}
     }
   );
 }
@@ -5245,12 +5316,13 @@ var dataSourceMappersSpecs = {
     }
   },
   "datasources map test": {
-    usage: "Usage: remy-admin datasources map test [--source <slug>] (--store <name> [--access <private|public>] [--prefix <p>] | --connector) [--keys k1,k2,...] [--limit <n>] [--dev] [--full]",
+    usage: "Usage: remy-admin datasources map test [--source <slug>] (--store <name> [--access <private|public>] [--prefix <p>] | --connector) [--keys k1,k2,...] [--limit <n>] [--dev [--release <dev-release-id>]] [--full]",
     flags: {
       source: { type: "string" },
       ...SELECTION_FLAGS,
       limit: { type: "number", min: 1 },
       dev: { type: "boolean" },
+      release: { type: "string" },
       full: { type: "boolean" }
     },
     requireAnyOf: {
@@ -5362,7 +5434,8 @@ async function mapTest2(ctx, a) {
     selection: selectionOf(a),
     ...keysOf(a) ? { keys: keysOf(a) } : {},
     ...limit !== void 0 ? { limit } : {},
-    ...a.bool("dev") ? { dev: true } : {}
+    ...a.bool("dev") ? { dev: true } : {},
+    ...a.str("release") ? { releaseId: a.str("release") } : {}
   });
   const results = a.bool("full") ? result.results : result.results.map(
     (r) => r.outcome.kind === "documents" ? {
@@ -5496,7 +5569,7 @@ var dataSourceMappersHandlers = {
 var dataSourceMappersHelp = `
 Mapping raw objects into documents (mappers):
   remy-admin datasources inspect [--source <slug>] (--store <name> [--prefix <p>] | --connector) [--keys k1,k2] [--limit <n>]
-  remy-admin datasources map test [--source <slug>] (--store <name> [--prefix <p>] | --connector) [--keys k1,k2] [--limit <n>] [--dev] [--full]
+  remy-admin datasources map test [--source <slug>] (--store <name> [--prefix <p>] | --connector) [--keys k1,k2] [--limit <n>] [--dev [--release <id>]] [--full]
   remy-admin datasources map deploy [--source <slug>] [--release <id>]
   remy-admin datasources remap [--source <slug>] [--budget <dollars>] [--limit <n>] [--wait] [--timeout <sec>]
   remy-admin datasources jobs quarantine <id> [--kind skip|error] [--stage map|read] [--reason <text>] [--cursor <id>] [--limit <n>]
@@ -5511,14 +5584,21 @@ Mapping raw objects into documents (mappers):
   map(object) reads the raw object (object.key, .bytes(), .text(), .json())
   and answers documents([{ externalId, title, markdown, metadata?, replaces? }]),
   passthrough() (ingest the raw object as-is), skip(reason) or
-  deletes([externalId, ...]); throwing is the object's error. It may call
-  models or fetch \u2014 every call is spend per object. Everything entering a
-  mapped source is mapped: jobs, syncs and Source.add() alike.
+  deletes([externalId, ...]); throwing is the object's error. documents()
+  takes an array or any iterable, with no cap: the platform stores what it
+  produces as it goes, so a generator yielding a document per row streams an
+  export of any size. It may call models or fetch \u2014 every call is spend per
+  object. Everything entering
+  a mapped source is mapped: jobs, syncs and Source.add() alike; an add() of
+  an object mapping to more than a thousand documents registers the first
+  thousand and hands the rest to a job (\`datasources add --budget\` caps it).
 
   The loop: \`inspect\` profiles the objects (key shapes, extensions, sizes,
   JSON key signatures of ten sampled heads) before a line is written;
   \`map test --dev\` runs the LOCAL mapper through the running dev session
-  over real objects and prints every outcome without ingesting anything;
+  over real objects and prints every outcome without ingesting anything
+  (each object's count, its first documents, and every document that fails
+  validation, by its place in the mapper's output);
   push a branch and wait for its build (\`releases wait\`) \u2014 a mapper runs on
   the platform, so the platform has to compile it, and a private branch
   build is all it needs; \`map deploy\` makes that build's mapper the
@@ -5537,7 +5617,11 @@ Mapping raw objects into documents (mappers):
   ids this document supersedes (a writethru's original); deletes([...])
   removes by id. A plan on a mapped source records the mapper's outcome mix
   on its sample; a run whose skip share climbs past twice that (floor 5%)
-  pauses with pauseReason 'skips' for a look at the quarantine.
+  pauses with pauseReason 'skips' for a look at the quarantine. Documents
+  that fail validation are left out and their object gets one quarantine row
+  naming them; the rest register. A mapper built with an older
+  @mindstudio-ai/agent, which returns documents inline, errors every
+  documents outcome until it is upgraded, pushed and map deployed.
 `;
 
 // src/ops/dataSourceReaders.ts
@@ -5552,7 +5636,8 @@ function readerTest(ctx, params) {
     {
       slug: params.slug,
       ...params.documents ? { documents: params.documents } : {},
-      ...params.limit !== void 0 ? { limit: params.limit } : {}
+      ...params.limit !== void 0 ? { limit: params.limit } : {},
+      ...params.releaseId ? { releaseId: params.releaseId } : {}
     }
   );
 }
@@ -5593,12 +5678,13 @@ function reread(ctx, params) {
 // src/commands/dataSourceReaders.ts
 var dataSourceReadersSpecs = {
   "datasources reader test": {
-    usage: "Usage: remy-admin datasources reader test --dev [--source <slug>] [--documents id1,id2,...] [--limit <n>]",
+    usage: "Usage: remy-admin datasources reader test --dev [--source <slug>] [--documents id1,id2,...] [--limit <n>] [--release <dev-release-id>]",
     flags: {
       source: { type: "string" },
       dev: { type: "boolean" },
       documents: { type: "string" },
-      limit: { type: "number", min: 1 }
+      limit: { type: "number", min: 1 },
+      release: { type: "string" }
     }
   },
   "datasources reader status": {
@@ -5643,7 +5729,8 @@ async function readerTest2(ctx, a) {
   const result = await readerTest(ctx, {
     slug,
     ...documents2 ? { documents: documents2 } : {},
-    ...limit !== void 0 ? { limit } : {}
+    ...limit !== void 0 ? { limit } : {},
+    ...a.str("release") ? { releaseId: a.str("release") } : {}
   });
   out({
     dataSource: slug,
@@ -5714,7 +5801,7 @@ var dataSourceReadersHandlers = {
 };
 var dataSourceReadersHelp = `
 Reading documents into the app (readers):
-  remy-admin datasources reader test --dev [--source <slug>] [--documents id1,id2] [--limit <n>]
+  remy-admin datasources reader test --dev [--source <slug>] [--documents id1,id2] [--limit <n>] [--release <id>]
   remy-admin datasources reader status [--source <slug>]
   remy-admin datasources reader retry [--source <slug>] [--job <id>]
   remy-admin datasources reread [--source <slug>] [--unread] [--filter <k=v|json>] [--budget <dollars>] [--limit <n>] [--wait] [--timeout <sec>]
@@ -5725,12 +5812,15 @@ Reading documents into the app (readers):
   platform's batching, retries, budgets and pauses. Declare it in
   mindstudio.json:
     "dataSources": [{ "slug": "archive", "reader": { "path": "dist/datasources/archive.reader.ts" } }]
-  The file exports defineReader(Archive, { read, removed, cleared? }) from
-  @mindstudio-ai/agent. read(document) gets the document (id, sourceId,
-  filename, metadata, entities) and document.chunks(), its passages as
-  indexed with each one's entities; removed(documentId) is called when a
-  document leaves the source; cleared(sourceId) once when the source is
-  deleted. Throwing fails that document, which is retried. A document can be
+  The file exports defineReader(Archive, { read, removed, cleared?,
+  relinked? }) from @mindstudio-ai/agent. read(document) gets the document
+  (id, sourceId, filename, metadata, entities, url), document.chunks(), its
+  passages as indexed with each one's entities, and document.bytes(), the
+  file it came from; removed(documentId) is called when a document leaves
+  the source; cleared(sourceId) once when the source is deleted; relinked(
+  document) when a new dictionary re-tagged a document already read, for
+  rows derived from its tags. Throwing fails that document, which is
+  retried. A document can be
   read more than once, so read() replaces the document's rows as a set,
   keyed by its id, and removed() deletes them. Options on the declaration:
   timeoutMs (per document, default 60000, max 300000) and concurrency
@@ -5792,12 +5882,13 @@ var CONFIG_FLAGS = {
 };
 var dataSourcesSpecs = {
   "datasources add": {
-    usage: "Usage: remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--entities <id,...>] [--wait] [--timeout <sec>] <file...>",
+    usage: "Usage: remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--entities <id,...>] [--budget <dollars>] [--wait] [--timeout <sec>] <file...>",
     positionals: [{ name: "file", required: true, variadic: true }],
     flags: {
       source: { type: "string" },
       metadata: { type: "string" },
       entities: { type: "string" },
+      budget: { type: "number", min: 0.01 },
       wait: { type: "boolean" },
       timeout: { type: "string" }
     }
@@ -5885,6 +5976,19 @@ var dataSourcesSpecs = {
       candidate: { type: "boolean" }
     }
   },
+  "datasources passages": {
+    usage: "Usage: remy-admin datasources passages [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--cursor <cursor>] [--limit <n>] [--candidate]",
+    flags: {
+      source: { type: "string" },
+      filter: { type: "string" },
+      entities: { type: "string" },
+      contains: { type: "string" },
+      phrase: { type: "string" },
+      cursor: { type: "string" },
+      limit: { type: "number", min: 1 },
+      candidate: { type: "boolean" }
+    }
+  },
   "datasources move": {
     usage: "Usage: remy-admin datasources move [--source <slug>] --to <resource-id|shared> [--chains <n>] [--restart] [--wait] [--timeout <sec>] | --stop",
     flags: {
@@ -5928,6 +6032,7 @@ async function dataSourcesAdd(ctx, a) {
   const slug = sourceOf(a);
   const metadata = parseKeyValuePairs(a.str("metadata"), "metadata");
   const entities2 = parseIdList(a.str("entities"));
+  const budgetDollars = a.num("budget");
   const results = [];
   for (const file of files) {
     const abs = path6.isAbsolute(file) ? file : path6.join(WORKSPACE_DIR, file);
@@ -5945,10 +6050,22 @@ async function dataSourcesAdd(ctx, a) {
         content: bytes,
         ...metadata ? { metadata } : {},
         ...entities2 ? { entities: entities2 } : {},
+        ...budgetDollars !== void 0 ? { budgetDollars } : {},
         onProgress: progress
       })
     );
   }
+  const jobs = results.flatMap(
+    (r) => r.job ? [
+      {
+        file: r.filename,
+        documents: r.documentCount,
+        job: r.job.id,
+        state: r.job.state,
+        follow: `remy-admin datasources jobs status ${r.job.id}`
+      }
+    ] : []
+  );
   if (a.bool("wait")) {
     const timeoutSec = a.num("timeout");
     const timeoutMs = timeoutSec ? timeoutSec * 1e3 : DEFAULT_WAIT_TIMEOUT_MS;
@@ -5964,7 +6081,8 @@ async function dataSourcesAdd(ctx, a) {
       dataSource: slug,
       status: result.status,
       ...result.error ? { error: result.error } : {},
-      documents: result.documents
+      documents: result.documents,
+      ...jobs.length > 0 ? { jobs } : {}
     });
     if (result.status === "timeout") {
       throw new CliError(result.error ?? "Timed out.", EXIT.timeout);
@@ -5974,7 +6092,11 @@ async function dataSourcesAdd(ctx, a) {
     }
     return;
   }
-  out({ dataSource: slug, documents: results });
+  out({
+    dataSource: slug,
+    documents: results.map(({ job, ...r }) => r),
+    ...jobs.length > 0 ? { jobs } : {}
+  });
 }
 async function dataSourcesList(ctx) {
   out(await list8(ctx));
@@ -6098,6 +6220,22 @@ async function dataSourcesEntities(ctx, a) {
     })
   );
 }
+async function dataSourcesPassages(ctx, a) {
+  const filter = filterFromFlags(a);
+  const limit = a.num("limit");
+  const cursor = a.str("cursor");
+  const result = await passages(ctx, {
+    slug: sourceOf(a),
+    ...filter ? { filter } : {},
+    ...cursor ? { cursor } : {},
+    ...limit !== void 0 ? { limit } : {},
+    ...a.bool("candidate") ? { candidate: true } : {}
+  });
+  out({
+    ...result,
+    ...result.nextCursor ? { note: `More: pass --cursor ${result.nextCursor} for the next page.` } : {}
+  });
+}
 function parseIdList(raw) {
   if (raw === void 0) {
     return void 0;
@@ -6362,6 +6500,7 @@ var dataSourcesHandlers = {
   "datasources config": dataSourcesConfig,
   "datasources count": dataSourcesCount,
   "datasources entities": dataSourcesEntities,
+  "datasources passages": dataSourcesPassages,
   "datasources move": dataSourcesMove,
   "datasources revectorize": dataSourcesRevectorize,
   "datasources promote": dataSourcesPromote,
@@ -6379,6 +6518,11 @@ Subcommands:
   status       Show a source's counts and its failed documents (--all walks every document)
   rm           Remove a document, or every document matching a filter
   search       Query a corpus \u2014 useful to sanity-check one you just built
+  count        How many passages match a filter (words, a phrase, entities, metadata)
+  passages     Every passage matching a filter, unranked, a page at a time
+  entities     Which entities the matching passages are about, most first
+  dictionary   push|status: send a source its dictionary of names, or show the current one
+  link         What the source's dictionary finds in a piece of text
   create       Create an empty source, optionally on dedicated capacity
   config       Show or change how a corpus is processed and searched
   move         Move a corpus between shared and dedicated capacity, data intact
@@ -6391,6 +6535,8 @@ Subcommands:
   map test     Run a source's mapper over real objects and show the outcomes; nothing ingested
   map deploy   Make a build's compiled mapper the source's active one (a branch build will do)
   remap        Re-apply the active mapper to every raw copy the source holds
+  reader       test|status|retry: run the dev session's reader, see its deliveries, resend failed ones
+  reread       Read a source's documents again with its live reader, priced first
   hydrate      Reload an evicted index ahead of the first search
   reindex      Recreate a dedicated source's collection with the current shape, refilled from stored vectors
   sample       Draw a sample of a source into a new one with the same config
@@ -6401,13 +6547,14 @@ Subcommands:
   delete       Delete a whole data source \u2014 documents, vectors and versions
 
 Usage:
-  remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--entities <id,...>] [--wait] [--timeout <sec>] <file...>
+  remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--entities <id,...>] [--budget <dollars>] [--wait] [--timeout <sec>] <file...>
   remy-admin datasources list
   remy-admin datasources status [--source <slug>] [--status error] [--all]
   remy-admin datasources rm [--source <slug>] (--document <id> | --filter <k=v,...|json>)
   remy-admin datasources search [--source <slug>] [search options] <query>
   remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--candidate]
   remy-admin datasources entities [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--limit <n>] [--candidate]
+  remy-admin datasources passages [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--cursor <c>] [--limit <n>] [--candidate]
   remy-admin datasources create --source <slug> [--name <name>] [--placement <resource-id|shared>] [rebuild settings...]
   remy-admin datasources config [--source <slug>] [--placement <resource-id|shared>] [settings...]
   remy-admin datasources move [--source <slug>] --to <resource-id|shared> [--chains <n>] [--restart] [--wait] [--timeout <sec>]
@@ -6541,6 +6688,10 @@ Notes:
   --metadata tags documents for search-time filtering (scalars, \u226416 keys).
   --entities names what a document is about, as your own ids (\u2264256, no spaces
     or commas); an empty --entities clears them. Also free on a re-add.
+  On a mapped source, a file that maps to more than a thousand documents adds
+    the first thousand and starts a job for the rest, listed under \`jobs\` in
+    the output; --budget caps that job. --wait waits for the first thousand;
+    follow the job with \`jobs status <id> --wait\`.
   rm --filter removes every matching document in pages of a thousand: k=v
     pairs match metadata; a JSON object takes the full selector \u2014 metadata,
     filename, documentIds, externalIdPrefix (the key a job or connector
@@ -9264,32 +9415,60 @@ function resolveRoute(argv) {
   if (sub && KEYS.has(two)) {
     return { key: two, argv: argv.slice(2) };
   }
-  if (group === "domains" && sub === "custom") {
-    return {
-      error: `Unknown subcommand: domains custom ${action ?? ""}. Run 'remy-admin domains --help'`
-    };
+  if (group === "db" && sub) {
+    return { key: "db query", argv: argv.slice(1) };
   }
-  if (group === "settings" && ["allowlist", "test-accounts", "frame-ancestors"].includes(sub ?? "")) {
-    return {
-      error: `Unknown subcommand: settings ${sub} ${action ?? ""}. Run 'remy-admin settings --help'`
-    };
+  return { error: unknownSubcommand(group, sub, action) };
+}
+function keysUnder(words) {
+  const prefix = `${words.join(" ")} `;
+  return [...KEYS].filter((key) => key.startsWith(prefix)).sort();
+}
+function unknownSubcommand(group, sub, action) {
+  const asked = [group, sub, action].filter(Boolean).join(" ");
+  const nested = sub ? keysUnder([group, sub]) : [];
+  if (nested.length > 0) {
+    const actions = nested.map((key) => key.split(" ")[2]);
+    return `Unknown subcommand: ${asked}. '${group} ${sub}' takes: ${actions.join(", ")}. Run 'remy-admin ${group} ${sub} --help' for their usage.`;
   }
-  if (group === "datasources" && (sub === "jobs" || sub === "eval" || sub === "map")) {
-    return {
-      error: `Unknown subcommand: datasources ${sub} ${action ?? ""}. Run 'remy-admin datasources --help'`
-    };
+  const subs = [...new Set(keysUnder([group]).map((key) => key.split(" ")[1]))];
+  return `Unknown subcommand: ${asked}. '${group}' takes: ${subs.join(", ")}. Run 'remy-admin ${group} --help'.`;
+}
+function leadingWords(argv) {
+  const words = [];
+  for (const token of argv) {
+    if (token.startsWith("-")) {
+      break;
+    }
+    words.push(token);
   }
-  if (group === "email" && ["domains", "inbound-domains"].includes(sub ?? "")) {
-    return {
-      error: `Unknown subcommand: email ${sub} ${action ?? ""}. Run 'remy-admin email --help'`
-    };
+  return words;
+}
+function commandHelp(argv) {
+  const words = leadingWords(argv);
+  const group = words[0];
+  const guide = `Run 'remy-admin ${group} --help' for the ${group} guide.`;
+  for (let n = Math.min(words.length, 3); n >= 2; n--) {
+    const key = words.slice(0, n).join(" ");
+    if (KEYS.has(key)) {
+      return `${SPECS[key].usage}
+
+${guide}`;
+    }
   }
-  if (group === "db" && sub) {
-    return { key: "db query", argv: argv.slice(1) };
+  if (words.length >= 2) {
+    const under = keysUnder(words.slice(0, 2));
+    if (under.length > 0) {
+      const usages = under.map(
+        (key) => `  ${SPECS[key].usage.replace(/^Usage:\s*/, "")}`
+      );
+      return `Usage:
+${usages.join("\n")}
+
+${guide}`;
+    }
   }
-  return {
-    error: `Unknown subcommand: ${group} ${sub ?? ""}. Run 'remy-admin ${group} --help'`
-  };
+  return void 0;
 }
 function resolveHelp(argv) {
   const group = argv[0];
@@ -9304,7 +9483,10 @@ function resolveHelp(argv) {
     return groupHelp;
   }
   const scan = group === "db" ? argv.slice(1, argv[1] === "query" ? 3 : 2) : argv.slice(1);
-  return scan.some((t) => t === "--help" || t === "-h") ? groupHelp : void 0;
+  if (!scan.some((t) => t === "--help" || t === "-h")) {
+    return void 0;
+  }
+  return commandHelp(argv) ?? groupHelp;
 }
 
 // src/prod.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madewithremy/admin",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Admin SDK + CLI for managing production Remy apps",
   "type": "module",
   "main": "./dist/index.js",