stow-cli 2.2.3 → 2.3.0

package/dist/chunk-JXITFFWI.js

@@ -0,0 +1,318 @@
+// src/lib/cli-docs.ts
+var CLI_DOCS = {
+  root: {
+    description: "CLI for Stow file storage",
+    usage: "stow [command] [options]",
+    examples: [
+      "stow whoami",
+      "stow upload ./photo.jpg --bucket photos",
+      "stow drop ./screenshot.png",
+      "stow buckets",
+      "stow files photos --limit 50",
+      "stow search text 'sunset beach'",
+      "stow admin health"
+    ],
+    notes: [
+      "Set STOW_API_KEY before running commands that call the API.",
+      "Set STOW_API_URL to target a non-default environment.",
+      "Set STOW_ADMIN_SECRET for admin commands."
+    ]
+  },
+  drop: {
+    description: "Upload a file and get a short URL (quick share)",
+    usage: "stow drop <file> [options]",
+    examples: ["stow drop ./video.mp4", "stow drop ./notes.txt --quiet"]
+  },
+  upload: {
+    description: "Upload a file to a bucket",
+    usage: "stow upload <file> [options]",
+    examples: ["stow upload ./logo.png --bucket brand-assets", "stow upload ./clip.mov --quiet"]
+  },
+  buckets: {
+    description: "List your buckets",
+    usage: "stow buckets",
+    examples: ["stow buckets"]
+  },
+  bucketsCreate: {
+    description: "Create a new bucket",
+    usage: "stow buckets create <name> [options]",
+    examples: [
+      "stow buckets create photos",
+      'stow buckets create docs --description "Product docs"',
+      "stow buckets create public-media --public"
+    ]
+  },
+  bucketsRename: {
+    description: "Rename a bucket",
+    usage: "stow buckets rename <name> <new-name> [options]",
+    examples: ["stow buckets rename old-name new-name --yes"],
+    notes: ["Renaming a bucket can break existing public URLs."]
+  },
+  bucketsDelete: {
+    description: "Delete a bucket by ID",
+    usage: "stow buckets delete <id>",
+    examples: ["stow buckets delete 8f3d1ab4-..."]
+  },
+  files: {
+    description: "List files in a bucket",
+    usage: "stow files <bucket> [options]",
+    examples: [
+      "stow files photos",
+      "stow files photos --search avatars/ --limit 100",
+      "stow files photos --json"
+    ]
+  },
+  filesGet: {
+    description: "Get details for a single file",
+    usage: "stow files get <bucket> <key>",
+    examples: ["stow files get photos hero.png", "stow files get photos hero.png --json"]
+  },
+  filesUpdate: {
+    description: "Update file metadata",
+    usage: "stow files update <bucket> <key> -m key=value",
+    examples: [
+      "stow files update photos hero.png -m alt='Hero image'",
+      "stow files update photos hero.png -m category=banner -m priority=high"
+    ]
+  },
+  filesMissing: {
+    description: "List files missing processing data",
+    usage: "stow files missing <bucket> <type>",
+    examples: [
+      "stow files missing brera dimensions",
+      "stow files missing brera embeddings --limit 200",
+      "stow files missing brera colors --json"
+    ],
+    notes: ["Valid types: dimensions, embeddings, colors"]
+  },
+  filesEnrich: {
+    description: "Generate title, description, and alt text for an image",
+    usage: "stow files enrich <bucket> <key>",
+    examples: ["stow files enrich photos hero.jpg", "stow files enrich next l5igro4iutep3"],
+    notes: [
+      "Triggers title, description, and alt text generation in parallel.",
+      "Requires a searchable bucket with image files."
+    ]
+  },
+  drops: {
+    description: "List your drops with usage info",
+    usage: "stow drops",
+    examples: ["stow drops"]
+  },
+  dropsDelete: {
+    description: "Delete a drop by ID",
+    usage: "stow drops delete <id>",
+    examples: ["stow drops delete drop_abc123"]
+  },
+  delete: {
+    description: "Delete a file from a bucket",
+    usage: "stow delete <bucket> <key>",
+    examples: ["stow delete photos hero/banner.png"]
+  },
+  whoami: {
+    description: "Show account info, usage stats, and API key details",
+    usage: "stow whoami",
+    examples: ["stow whoami"]
+  },
+  open: {
+    description: "Open a bucket in the browser",
+    usage: "stow open <bucket>",
+    examples: ["stow open photos"]
+  },
+  interactive: {
+    description: "Launch interactive TUI mode",
+    usage: "stow --interactive",
+    examples: ["stow", "stow --interactive"]
+  },
+  search: {
+    description: "Search files across buckets",
+    usage: "stow search <subcommand>",
+    examples: [
+      "stow search text 'sunset beach' -b photos",
+      "stow search similar --file hero.png -b photos",
+      'stow search color --hex "#ff0000" -b photos',
+      "stow search diverse -b photos"
+    ]
+  },
+  searchText: {
+    description: "Semantic text search",
+    usage: "stow search text <query> [options]",
+    examples: ["stow search text 'sunset beach' -b photos --limit 10 --json"]
+  },
+  searchSimilar: {
+    description: "Find files similar to a given file",
+    usage: "stow search similar --file <key> [options]",
+    examples: ["stow search similar --file hero.png -b photos"]
+  },
+  searchColor: {
+    description: "Search by color (hex, name, palette, or mood)",
+    usage: "stow search color [--hex|--name|--palette|--mood-temp + --mood-light] [options]",
+    examples: [
+      'stow search color --hex "#ff6b35" -b photos',
+      "stow search color --name terracotta --limit 20",
+      'stow search color --palette "#d94e1f" "#264066" -b products',
+      "stow search color --mood-temp 0.8 --mood-light 0.4",
+      'stow search color --hex "#336633" --dominant-only --min-proportion 0.2'
+    ]
+  },
+  searchDiverse: {
+    description: "Diversity-aware search",
+    usage: "stow search diverse [options]",
+    examples: ["stow search diverse -b photos --limit 20"]
+  },
+  tags: {
+    description: "Manage tags",
+    usage: "stow tags",
+    examples: ["stow tags", "stow tags create 'Hero Images'", "stow tags delete <id>"]
+  },
+  tagsCreate: {
+    description: "Create a new tag",
+    usage: "stow tags create <name> [options]",
+    examples: ['stow tags create "Hero Images"', 'stow tags create "Featured" --color "#ff6600"']
+  },
+  tagsDelete: {
+    description: "Delete a tag by ID",
+    usage: "stow tags delete <id>",
+    examples: ["stow tags delete tag_abc123"]
+  },
+  profiles: {
+    description: "Manage taste profiles",
+    usage: "stow profiles <subcommand>",
+    examples: [
+      'stow profiles create --name "My Profile"',
+      "stow profiles get <id>",
+      "stow profiles delete <id>"
+    ]
+  },
+  profilesCreate: {
+    description: "Create a taste profile",
+    usage: 'stow profiles create --name "My Profile" [options]',
+    examples: ['stow profiles create --name "My Profile" -b photos']
+  },
+  profilesGet: {
+    description: "Get a taste profile with clusters",
+    usage: "stow profiles get <id>",
+    examples: ["stow profiles get profile_abc123 --json"]
+  },
+  profilesDelete: {
+    description: "Delete a taste profile",
+    usage: "stow profiles delete <id>",
+    examples: ["stow profiles delete profile_abc123"]
+  },
+  jobs: {
+    description: "List processing jobs for a bucket",
+    usage: "stow jobs --bucket <id> [options]",
+    examples: [
+      "stow jobs --bucket <id>",
+      "stow jobs --bucket <id> --status failed",
+      "stow jobs --bucket <id> --queue extract-colors --json"
+    ]
+  },
+  jobsRetry: {
+    description: "Retry a failed job",
+    usage: "stow jobs retry <id> --queue <name> --bucket <id>",
+    examples: ["stow jobs retry job123 --queue generate-title --bucket <id>"]
+  },
+  jobsDelete: {
+    description: "Remove a job",
+    usage: "stow jobs delete <id> --queue <name> --bucket <id>",
+    examples: ["stow jobs delete job123 --queue extract-colors --bucket <id>"]
+  },
+  admin: {
+    description: "Admin commands (requires STOW_ADMIN_SECRET)",
+    usage: "stow admin <subcommand>",
+    examples: [
+      "stow admin health",
+      "stow admin backfill dimensions --bucket <id> --dry-run",
+      "stow admin cleanup-drops --dry-run"
+    ],
+    notes: ["Requires STOW_ADMIN_SECRET environment variable."]
+  },
+  adminHealth: {
+    description: "Check system health and queue depths",
+    usage: "stow admin health",
+    examples: ["stow admin health", "stow admin health --json"]
+  },
+  adminBackfill: {
+    description: "Backfill processing data for files",
+    usage: "stow admin backfill <type> [options]",
+    examples: [
+      "stow admin backfill dimensions --bucket <id> --dry-run",
+      "stow admin backfill colors --bucket <id> --limit 200",
+      "stow admin backfill embeddings --bucket <id> --limit 100 --json"
+    ],
+    notes: ["Valid types: dimensions, colors, embeddings"]
+  },
+  adminCleanupDrops: {
+    description: "Remove expired drops",
+    usage: "stow admin cleanup-drops [options]",
+    examples: ["stow admin cleanup-drops --max-age-hours 24 --dry-run"]
+  },
+  adminPurgeEvents: {
+    description: "Purge old webhook events",
+    usage: "stow admin purge-events [options]",
+    examples: ["stow admin purge-events --dry-run"]
+  },
+  adminReconcileFiles: {
+    description: "Reconcile files between R2 and database",
+    usage: "stow admin reconcile-files --bucket <id>",
+    examples: ["stow admin reconcile-files --bucket <id> --dry-run"]
+  },
+  adminRetrySyncFailures: {
+    description: "Retry failed S3 sync operations",
+    usage: "stow admin retry-sync-failures",
+    examples: ["stow admin retry-sync-failures"]
+  },
+  adminJobs: {
+    description: "List and manage processing jobs",
+    usage: "stow admin jobs [options]",
+    examples: [
+      "stow admin jobs",
+      "stow admin jobs --status failed",
+      "stow admin jobs --org <id> --queue generate-title",
+      "stow admin jobs --json"
+    ]
+  },
+  adminJobsRetry: {
+    description: "Retry a failed job",
+    usage: "stow admin jobs retry <id> --queue <name>",
+    examples: ["stow admin jobs retry job123 --queue generate-title"]
+  },
+  adminJobsDelete: {
+    description: "Remove a job",
+    usage: "stow admin jobs delete <id> --queue <name>",
+    examples: ["stow admin jobs delete job123 --queue extract-colors"]
+  },
+  adminQueues: {
+    description: "Show queue depths and counts",
+    usage: "stow admin queues",
+    examples: ["stow admin queues", "stow admin queues --json"]
+  },
+  adminQueuesClean: {
+    description: "Clean jobs from a queue",
+    usage: "stow admin queues clean <name> --failed|--completed",
+    examples: [
+      "stow admin queues clean generate-title --failed",
+      "stow admin queues clean extract-colors --completed --grace 3600"
+    ]
+  }
+};
+function renderCommandHelp(key) {
+  const doc = CLI_DOCS[key];
+  const lines = [
+    "",
+    `Usage: ${doc.usage}`,
+    "",
+    "Examples:",
+    ...doc.examples.map((example) => `  ${example}`)
+  ];
+  if (doc.notes?.length) {
+    lines.push("", "Notes:", ...doc.notes.map((note) => `  ${note}`));
+  }
+  return lines.join("\n");
+}
+
+export {
+  CLI_DOCS,
+  renderCommandHelp
+};

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   CLI_DOCS,
   renderCommandHelp
-} from "./chunk-MYFLRBWC.js";
+} from "./chunk-JXITFFWI.js";
 import {
   InputValidationError
 } from "./chunk-NBHBVKP5.js";
@@ -163,7 +163,7 @@ dropsCmd.command("delete").description(CLI_DOCS.dropsDelete.description).argumen
 var searchCmd = program.command("search").description(CLI_DOCS.search.description).addHelpText("after", renderCommandHelp("search"));
 searchCmd.command("text").description(CLI_DOCS.searchText.description).argument("<query>", "Search query").option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchText")).action(async (query, options) => {
   try {
-    const { textSearch } = await import("./search-UWLK4OL2.js");
+    const { textSearch } = await import("./search-KBJSWH35.js");
     await textSearch(query, options);
   } catch (error) {
     handleError(error);
@@ -171,23 +171,25 @@ searchCmd.command("text").description(CLI_DOCS.searchText.description).argument(
 });
 searchCmd.command("similar").description(CLI_DOCS.searchSimilar.description).requiredOption("--file <key>", "File key to search from").option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchSimilar")).action(async (options) => {
   try {
-    const { similarSearch } = await import("./search-UWLK4OL2.js");
+    const { similarSearch } = await import("./search-KBJSWH35.js");
     await similarSearch(options);
   } catch (error) {
     handleError(error);
   }
 });
-searchCmd.command("color").description(CLI_DOCS.searchColor.description).requiredOption("--hex <color>", "Hex color code").option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchColor")).action(async (options) => {
-  try {
-    const { colorSearch } = await import("./search-UWLK4OL2.js");
-    await colorSearch(options);
-  } catch (error) {
-    handleError(error);
+searchCmd.command("color").description(CLI_DOCS.searchColor.description).option("--hex <color>", "Hex color code (e.g. #ff6b35)").option("--name <name>", "Color name (e.g. terracotta, sage, navy)").option("--palette <colors...>", "2-5 hex colors for palette search").option("--mood-temp <value>", "Mood temperature: -1 (cool) to 1 (warm)").option("--mood-light <value>", "Mood lightness: 0 (dark) to 1 (light)").option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--dominant-only", "Only match dominant color per file").option("--min-proportion <value>", "Minimum color proportion (0-1)").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchColor")).action(
+  async (options) => {
+    try {
+      const { colorSearch } = await import("./search-KBJSWH35.js");
+      await colorSearch(options);
+    } catch (error) {
+      handleError(error);
+    }
   }
-});
+);
 searchCmd.command("diverse").description(CLI_DOCS.searchDiverse.description).option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchDiverse")).action(async (options) => {
   try {
-    const { diverseSearch } = await import("./search-UWLK4OL2.js");
+    const { diverseSearch } = await import("./search-KBJSWH35.js");
     await diverseSearch(options);
   } catch (error) {
     handleError(error);
@@ -412,7 +414,7 @@ program.command("open").description(CLI_DOCS.open.description).argument("<bucket
 });
 program.command("describe").argument("[command]", "Command path (dot notation, e.g. search.text)").description("Show command schema for AI agents").action(async (command) => {
   try {
-    const { describeCommand } = await import("./describe-NH3K3LLW.js");
+    const { describeCommand } = await import("./describe-TGIXQHN6.js");
     describeCommand(command ?? "");
   } catch (error) {
     handleError(error);

package/dist/describe-TGIXQHN6.js

@@ -0,0 +1,79 @@
+import {
+  CLI_DOCS
+} from "./chunk-JXITFFWI.js";
+import {
+  output
+} from "./chunk-KPIQZBTO.js";
+
+// src/commands/describe.ts
+var COMMAND_MAP = {
+  upload: "upload",
+  drop: "drop",
+  delete: "delete",
+  whoami: "whoami",
+  open: "open",
+  buckets: "buckets",
+  "buckets.create": "bucketsCreate",
+  "buckets.rename": "bucketsRename",
+  "buckets.delete": "bucketsDelete",
+  files: "files",
+  "files.get": "filesGet",
+  "files.update": "filesUpdate",
+  "files.enrich": "filesEnrich",
+  "files.missing": "filesMissing",
+  search: "search",
+  "search.text": "searchText",
+  "search.similar": "searchSimilar",
+  "search.color": "searchColor",
+  "search.diverse": "searchDiverse",
+  tags: "tags",
+  "tags.create": "tagsCreate",
+  "tags.delete": "tagsDelete",
+  drops: "drops",
+  "drops.delete": "dropsDelete",
+  profiles: "profiles",
+  "profiles.create": "profilesCreate",
+  "profiles.get": "profilesGet",
+  "profiles.delete": "profilesDelete",
+  jobs: "jobs",
+  "jobs.retry": "jobsRetry",
+  "jobs.delete": "jobsDelete",
+  admin: "admin",
+  "admin.health": "adminHealth",
+  "admin.backfill": "adminBackfill",
+  "admin.cleanup-drops": "adminCleanupDrops",
+  "admin.purge-events": "adminPurgeEvents",
+  "admin.reconcile-files": "adminReconcileFiles",
+  "admin.retry-sync-failures": "adminRetrySyncFailures",
+  "admin.jobs": "adminJobs",
+  "admin.jobs.retry": "adminJobsRetry",
+  "admin.jobs.delete": "adminJobsDelete",
+  "admin.queues": "adminQueues",
+  "admin.queues.clean": "adminQueuesClean"
+};
+function describeCommand(commandPath) {
+  if (!commandPath) {
+    output({
+      commands: Object.keys(COMMAND_MAP).sort()
+    });
+    return;
+  }
+  const docKey = COMMAND_MAP[commandPath];
+  if (!(docKey && CLI_DOCS[docKey])) {
+    console.error(`Unknown command: ${commandPath}`);
+    console.error(`Available: ${Object.keys(COMMAND_MAP).sort().join(", ")}`);
+    process.exit(1);
+    return;
+  }
+  const doc = CLI_DOCS[docKey];
+  output({
+    command: commandPath,
+    description: doc.description,
+    usage: doc.usage,
+    examples: doc.examples,
+    notes: doc.notes ?? []
+  });
+}
+export {
+  describeCommand
+};

package/dist/search-KBJSWH35.js

@@ -0,0 +1,134 @@
+import {
+  isJsonOutput,
+  output
+} from "./chunk-KPIQZBTO.js";
+import {
+  formatBytes,
+  formatTable
+} from "./chunk-PE6V3MVP.js";
+import {
+  createStow
+} from "./chunk-5LU25QZK.js";
+import "./chunk-TOADDO2F.js";
+
+// src/commands/search.ts
+async function textSearch(query, options) {
+  const stow = createStow();
+  const parsedLimit = options.limit ? Number.parseInt(options.limit, 10) : null;
+  const data = await stow.search.text({
+    query,
+    ...options.bucket ? { bucket: options.bucket } : {},
+    ...parsedLimit && parsedLimit > 0 ? { limit: parsedLimit } : {}
+  });
+  if (data.results.length === 0) {
+    if (isJsonOutput() || options.json) {
+      output(data);
+    } else {
+      console.log("No results found.");
+    }
+    return;
+  }
+  output(
+    data,
+    () => {
+      const rows = data.results.map((r) => [r.key, formatBytes(r.size), r.similarity.toFixed(3)]);
+      return formatTable(["Key", "Size", "Similarity"], rows);
+    },
+    { json: options.json }
+  );
+}
+async function similarSearch(options) {
+  const stow = createStow();
+  const parsedLimit = options.limit ? Number.parseInt(options.limit, 10) : null;
+  const data = await stow.search.similar({
+    fileKey: options.file,
+    ...options.bucket ? { bucket: options.bucket } : {},
+    ...parsedLimit && parsedLimit > 0 ? { limit: parsedLimit } : {}
+  });
+  if (data.results.length === 0) {
+    if (isJsonOutput() || options.json) {
+      output(data);
+    } else {
+      console.log("No similar files found.");
+    }
+    return;
+  }
+  output(
+    data,
+    () => {
+      const rows = data.results.map((r) => [r.key, formatBytes(r.size), r.similarity.toFixed(3)]);
+      return formatTable(["Key", "Size", "Similarity"], rows);
+    },
+    { json: options.json }
+  );
+}
+async function colorSearch(options) {
+  const hasInput = options.hex || options.name || options.palette || options.moodTemp && options.moodLight;
+  if (!hasInput) {
+    console.error("Provide one of: --hex, --name, --palette, or --mood-temp + --mood-light");
+    process.exit(1);
+  }
+  const stow = createStow();
+  const parsedLimit = options.limit ? Number.parseInt(options.limit, 10) : null;
+  const mood = options.moodTemp !== void 0 && options.moodLight !== void 0 ? {
+    temperature: Number.parseFloat(options.moodTemp),
+    lightness: Number.parseFloat(options.moodLight)
+  } : void 0;
+  const minProportion = options.minProportion ? Number.parseFloat(options.minProportion) : void 0;
+  const data = await stow.search.color({
+    ...options.hex ? { hex: options.hex } : {},
+    ...options.name ? { name: options.name } : {},
+    ...options.palette ? { palette: options.palette } : {},
+    ...mood ? { mood } : {},
+    ...options.bucket ? { bucket: options.bucket } : {},
+    ...parsedLimit && parsedLimit > 0 ? { limit: parsedLimit } : {},
+    ...options.dominantOnly ? { dominantOnly: true } : {},
+    ...minProportion !== void 0 ? { minProportion } : {}
+  });
+  if (data.results.length === 0) {
+    if (isJsonOutput() || options.json) {
+      output(data);
+    } else {
+      console.log("No results found.");
+    }
+    return;
+  }
+  output(
+    data,
+    () => {
+      const rows = data.results.map((r) => [r.key, r.contentType, r.colorDistance.toFixed(3)]);
+      return formatTable(["Key", "Type", "Distance"], rows);
+    },
+    { json: options.json }
+  );
+}
+async function diverseSearch(options) {
+  const stow = createStow();
+  const parsedLimit = options.limit ? Number.parseInt(options.limit, 10) : null;
+  const data = await stow.search.diverse({
+    ...options.bucket ? { bucket: options.bucket } : {},
+    ...parsedLimit && parsedLimit > 0 ? { limit: parsedLimit } : {}
+  });
+  if (data.results.length === 0) {
+    if (isJsonOutput() || options.json) {
+      output(data);
+    } else {
+      console.log("No results found.");
+    }
+    return;
+  }
+  output(
+    data,
+    () => {
+      const rows = data.results.map((r) => [r.key, formatBytes(r.size), r.similarity.toFixed(3)]);
+      return formatTable(["Key", "Size", "Similarity"], rows);
+    },
+    { json: options.json }
+  );
+}
+export {
+  colorSearch,
+  diverseSearch,
+  similarSearch,
+  textSearch
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stow-cli",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "CLI for Stow file storage",
   "keywords": [
     "cli",