@aiaiai-pt/martha-cli 0.63.2 → 0.64.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [0.64.0] — 2026-10-20
+
+### Added
+
+- `martha documents lifecycle <id>` explains ingestion, storage and presence states, search eligibility, event permissions, linked source freshness and transition history. `--json` returns the API payload unchanged. Requires a server with the document lifecycle endpoint (#1685).
+
+### Fixed
+
+- Store-only `skipped` ingestion finishes `--wait` and `--follow` successfully.
+- Failed ingestion returns a nonzero exit from JSON wait mode, matching text mode.
+
 ## [0.63.2] — 2026-10-15
 
 ### Changed

package/dist/index.js

@@ -11244,7 +11244,7 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.63.2";
+var CLI_VERSION = "0.64.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -17720,7 +17720,41 @@ var triggersConfig = {
 // src/commands/documents.ts
 import fs10 from "node:fs";
 init_errors();
-var TERMINAL_STATUSES2 = new Set(["ready", "error"]);
+
+// src/lib/document-lifecycle.ts
+function formatDocumentLifecycle(value) {
+  const lines = [
+    `Document: ${value.document_id}`,
+    `Searchable: ${value.searchable ? "yes" : "no"}`,
+    ...value.searchability_reasons.map((reason) => `  ${reason}`)
+  ];
+  for (const region of value.regions) {
+    lines.push(`
+${region.kind}: ${region.state ?? "Not recorded"} (${region.mode})`);
+    for (const event of region.events) {
+      lines.push(`  ${event.event} → ${event.to_state}: ${event.allowed ? "allowed" : `unavailable (${event.reason ?? "not authorized"})`}`);
+    }
+  }
+  lines.push(`
+Sync sources:`);
+  if (!value.sync_sources.length)
+    lines.push("  None");
+  for (const source of value.sync_sources) {
+    lines.push(`  ${source.id}: ${source.provider}, ${source.status}; last synced ${source.last_synced_at ?? "never"}`);
+  }
+  lines.push(`
+History:`);
+  if (!value.history.length)
+    lines.push("  No recorded transitions");
+  for (const row of value.history) {
+    lines.push(`  ${row.seq} ${row.created_at} ${row.kind}: ${row.from_state ?? "∅"} → ${row.to_state} (${row.event}, ${row.actor_kind}:${row.actor_id ?? "unknown"})`);
+  }
+  return lines.join(`
+`);
+}
+
+// src/commands/documents.ts
+var TERMINAL_STATUSES2 = new Set(["ready", "error", "skipped"]);
 var SPINNER_FRAMES2 = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 var spinnerIdx = 0;
 function nextSpinner() {
@@ -17850,6 +17884,8 @@ Detached. Check status with: martha documents status ${documentId}`));
         if (TERMINAL_STATUSES2.has(status.ingestion_status)) {
           if (status.ingestion_status === "ready") {
             lines.push(source_default.green("Ingestion complete"));
+          } else if (status.ingestion_status === "skipped") {
+            lines.push("Ingestion skipped (store-only document)");
           } else {
             lines.push(source_default.red(`Error: ${status.error ?? "unknown error"}`));
           }
@@ -17869,6 +17905,8 @@ Detached. Check status with: martha documents status ${documentId}`));
         if (!isJson && !isTTY) {
           if (status.ingestion_status === "ready") {
             console.log(`Ingestion complete. ${status.chunk_count ?? 0} chunks created.`);
+          } else if (status.ingestion_status === "skipped") {
+            console.log("Ingestion skipped (store-only document).");
           } else {
             console.error(`Ingestion failed: ${status.error ?? "unknown error"}`);
             process.exitCode = 1 /* Error */;
@@ -17898,6 +17936,10 @@ function registerDocumentCommands(program) {
   function isJson() {
     return !!program.opts().json;
   }
+  cmd.command("lifecycle <document-id>").description("Explain document states, search eligibility, event permissions and history").action(async (documentId) => {
+    const value = await getCtx().api.get(`/api/admin/documents/${encodeURIComponent(documentId)}/lifecycle`);
+    console.log(isJson() ? JSON.stringify(value, null, 2) : formatDocumentLifecycle(value));
+  });
   async function resolveCollection(ctx, ref) {
     const looksLikeUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref);
     if (looksLikeUuid) {
@@ -18124,11 +18166,15 @@ ${items.length} collections`));
         console.log(source_default.dim(`Uploaded ${result.filename}. Waiting for ingestion...`));
       }
       const final = await pollIngestionUntilDone(ctx, result.id);
+      if (final.ingestion_status === "error")
+        process.exitCode = 1 /* Error */;
       if (isJson()) {
         console.log(JSON.stringify(final));
       } else {
         if (final.ingestion_status === "ready") {
           console.log(`Ingestion complete. ${final.chunk_count ?? 0} chunks created.`);
+        } else if (final.ingestion_status === "skipped") {
+          console.log("Ingestion skipped (store-only document).");
         } else {
           console.error(`Ingestion failed: ${final.error ?? "unknown error"}`);
           process.exitCode = 1 /* Error */;
@@ -18307,11 +18353,15 @@ ${items.length} documents`));
         console.log(source_default.dim(`Re-ingestion triggered. Waiting for completion...`));
       }
       const final = await pollIngestionUntilDone(ctx, documentId);
+      if (final.ingestion_status === "error")
+        process.exitCode = 1 /* Error */;
       if (isJson()) {
         console.log(JSON.stringify(final));
       } else {
         if (final.ingestion_status === "ready") {
           console.log(`Ingestion complete. ${final.chunk_count ?? 0} chunks created.`);
+        } else if (final.ingestion_status === "skipped") {
+          console.log("Ingestion skipped (store-only document).");
         } else {
           console.error(`Ingestion failed: ${final.error ?? "unknown error"}`);
           process.exitCode = 1 /* Error */;
@@ -20507,13 +20557,10 @@ function registerMessagingCommands(program) {
   });
   cmd.command("send-sms").description("Send a test SMS").requiredOption("--to <number>", "Destination phone number (E.164)").requiredOption("--from <sender>", "Sender ID or number").requiredOption("--content <text>", "Message content").action(async (opts) => {
     const ctx = getCtx();
-    const data = await messagingFetch(ctx.profile.api_url, "/api/messaging/send/sms", {
-      method: "POST",
-      body: {
-        to: opts.to,
-        from_number: opts.from,
-        content: opts.content
-      }
+    const data = await ctx.api.post("/api/messaging/send/sms", {
+      to: opts.to,
+      from_number: opts.from,
+      content: opts.content
     });
     if (isJson()) {
       console.log(JSON.stringify(data, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.63.2",
+  "version": "0.64.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {

package/skills/martha-cli/SKILL.md

@@ -640,6 +640,7 @@ martha documents move-collection <id> --parent <slug-or-id> | --root  # Atomic m
 martha documents upload <collection-id> <file> [--wait] [--follow]   # --follow streams ingestion progress
 martha documents list <collection-id> [--inactive] [--limit 50]
 martha documents get <doc-id>                  # Full metadata + chunk count
+martha documents lifecycle <doc-id> [--json]    # States, search eligibility, event permissions, sources and history
 martha documents status <doc-id> [--follow]    # Ingestion progress: validate → parse → embed → finalize
 martha documents download <doc-id> [--expires 3600]   # Presigned URL (default 1h)
 martha documents delete <doc-id> [--yes]