stow-cli 2.0.3 → 2.1.0

package/README.md

@@ -0,0 +1,363 @@
+# stow-cli
+
+CLI for [Stow](https://stow.sh) file storage. Upload, search, and manage files from the terminal.
+
+## Installation
+
+```bash
+npm install -g stow-cli
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+export STOW_API_KEY="stow_..."
+
+# Check connection
+stow whoami
+
+# Upload a file
+stow upload ./photo.jpg --bucket photos
+
+# Quick share (returns a short URL)
+stow drop ./screenshot.png
+
+# Search
+stow search text 'sunset beach' -b photos
+```
+
+## Authentication
+
+Stow CLI uses environment variables for authentication:
+
+| Variable | Required | Description |
+|---|---|---|
+| `STOW_API_KEY` | Yes | Your Stow API key (get one at `app.stow.sh/dashboard/api-keys`) |
+| `STOW_API_URL` | No | Override the default API URL (`https://api.stow.sh`) |
+| `STOW_ADMIN_SECRET` | No | Required for `admin` commands only |
+
+## Commands
+
+### Upload and Share
+
+**`stow upload <file>`** -- Upload a file to a bucket.
+
+```bash
+stow upload ./logo.png --bucket brand-assets
+stow upload ./clip.mov --quiet
+```
+
+Options: `-b, --bucket <name>`, `-q, --quiet`
+
+**`stow drop <file>`** -- Upload a file and get a short URL (quick share).
+
+```bash
+stow drop ./video.mp4
+stow drop ./notes.txt --quiet
+```
+
+Options: `-q, --quiet`
+
+### Buckets
+
+**`stow buckets`** -- List your buckets.
+
+**`stow buckets create <name>`** -- Create a new bucket.
+
+```bash
+stow buckets create photos
+stow buckets create docs --description "Product docs"
+stow buckets create public-media --public
+```
+
+Options: `-d, --description <text>`, `--public`
+
+**`stow buckets rename <name> <new-name>`** -- Rename a bucket. Note: renaming can break existing public URLs.
+
+```bash
+stow buckets rename old-name new-name --yes
+```
+
+Options: `-y, --yes` (skip confirmation)
+
+**`stow buckets delete <id>`** -- Delete a bucket by ID.
+
+```bash
+stow buckets delete 8f3d1ab4-...
+```
+
+### Files
+
+**`stow files <bucket>`** -- List files in a bucket.
+
+```bash
+stow files photos
+stow files photos --search avatars/ --limit 100
+stow files photos --json
+```
+
+Options: `-s, --search <prefix>`, `-l, --limit <count>`, `--json`
+
+**`stow files get <bucket> <key>`** -- Get details for a single file.
+
+```bash
+stow files get photos hero.png
+stow files get photos hero.png --json
+```
+
+Options: `--json`
+
+**`stow files update <bucket> <key>`** -- Update file metadata.
+
+```bash
+stow files update photos hero.png -m alt='Hero image'
+stow files update photos hero.png -m category=banner -m priority=high
+```
+
+Options: `-m, --metadata <kv...>`, `--json`
+
+**`stow files enrich <bucket> <key>`** -- Generate title, description, and alt text for an image. Requires a searchable bucket with image files.
+
+```bash
+stow files enrich photos hero.jpg
+```
+
+**`stow files missing <bucket> <type>`** -- List files missing processing data. Valid types: `dimensions`, `embeddings`, `colors`.
+
+```bash
+stow files missing brera dimensions
+stow files missing brera embeddings --limit 200
+stow files missing brera colors --json
+```
+
+Options: `-l, --limit <count>`, `--json`
+
+### Search
+
+**`stow search text <query>`** -- Semantic text search.
+
+```bash
+stow search text 'sunset beach' -b photos --limit 10 --json
+```
+
+**`stow search similar --file <key>`** -- Find files similar to a given file.
+
+```bash
+stow search similar --file hero.png -b photos
+```
+
+**`stow search color --hex <color>`** -- Search by color.
+
+```bash
+stow search color --hex "#ff0000" -b photos --limit 20
+```
+
+**`stow search diverse`** -- Diversity-aware search.
+
+```bash
+stow search diverse -b photos --limit 20
+```
+
+All search commands accept: `-b, --bucket <name>`, `-l, --limit <count>`, `--json`
+
+### Tags
+
+**`stow tags`** -- List tags.
+
+**`stow tags create <name>`** -- Create a new tag.
+
+```bash
+stow tags create "Hero Images"
+stow tags create "Featured" --color "#ff6600"
+```
+
+Options: `--color <hex>`, `--json`
+
+**`stow tags delete <id>`** -- Delete a tag by ID.
+
+### Drops
+
+**`stow drops`** -- List your drops with usage info.
+
+**`stow drops delete <id>`** -- Delete a drop by ID.
+
+```bash
+stow drops delete drop_abc123
+```
+
+### Profiles
+
+**`stow profiles create`** -- Create a taste profile.
+
+```bash
+stow profiles create --name "My Profile" -b photos
+```
+
+Options: `--name <name>` (required), `-b, --bucket <id>`, `--json`
+
+**`stow profiles get <id>`** -- Get a taste profile with clusters.
+
+```bash
+stow profiles get profile_abc123 --json
+```
+
+Options: `--json`
+
+**`stow profiles delete <id>`** -- Delete a taste profile.
+
+### Jobs
+
+**`stow jobs`** -- List processing jobs for a bucket.
+
+```bash
+stow jobs --bucket <id>
+stow jobs --bucket <id> --status failed
+stow jobs --bucket <id> --queue extract-colors --json
+```
+
+Options: `-b, --bucket <id>` (required), `-s, --status <status>`, `-q, --queue <name>`, `-l, --limit <count>`, `--json`
+
+**`stow jobs retry <id>`** -- Retry a failed job.
+
+```bash
+stow jobs retry job123 --queue generate-title --bucket <id>
+```
+
+Options: `-q, --queue <name>` (required), `-b, --bucket <id>` (required)
+
+**`stow jobs delete <id>`** -- Remove a job.
+
+```bash
+stow jobs delete job123 --queue extract-colors --bucket <id>
+```
+
+Options: `-q, --queue <name>` (required), `-b, --bucket <id>` (required)
+
+### Admin
+
+All admin commands require the `STOW_ADMIN_SECRET` environment variable.
+
+**`stow admin health`** -- Check system health and queue depths.
+
+```bash
+stow admin health
+stow admin health --json
+```
+
+**`stow admin backfill <type>`** -- Backfill processing data. Valid types: `dimensions`, `colors`, `embeddings`.
+
+```bash
+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
+```
+
+Options: `--bucket <id>`, `-l, --limit <count>`, `--dry-run`, `--json`
+
+**`stow admin cleanup-drops`** -- Remove expired drops.
+
+```bash
+stow admin cleanup-drops --max-age-hours 24 --dry-run
+```
+
+Options: `--max-age-hours <hours>`, `--dry-run`, `--json`
+
+**`stow admin purge-events`** -- Purge old webhook events.
+
+```bash
+stow admin purge-events --dry-run
+```
+
+Options: `--dry-run`, `--json`
+
+**`stow admin reconcile-files`** -- Reconcile files between R2 and database.
+
+```bash
+stow admin reconcile-files --bucket <id> --dry-run
+```
+
+Options: `--bucket <id>` (required), `--dry-run`, `--json`
+
+**`stow admin retry-sync-failures`** -- Retry failed S3 sync operations.
+
+```bash
+stow admin retry-sync-failures
+```
+
+Options: `--json`
+
+**`stow admin jobs`** -- List and manage processing jobs (cross-org).
+
+```bash
+stow admin jobs
+stow admin jobs --status failed
+stow admin jobs --org <id> --queue generate-title
+```
+
+Options: `--org <id>`, `--bucket <id>`, `-s, --status`, `-q, --queue`, `-l, --limit`, `--json`
+
+**`stow admin jobs retry <id>`** / **`stow admin jobs delete <id>`** -- Retry or remove a job.
+
+```bash
+stow admin jobs retry job123 --queue generate-title
+stow admin jobs delete job123 --queue extract-colors
+```
+
+**`stow admin queues`** -- Show queue depths and counts.
+
+```bash
+stow admin queues
+stow admin queues --json
+```
+
+**`stow admin queues clean <name>`** -- Clean jobs from a queue.
+
+```bash
+stow admin queues clean generate-title --failed
+stow admin queues clean extract-colors --completed --grace 3600
+```
+
+Options: `--failed`, `--completed`, `--grace <seconds>`
+
+### Utility
+
+**`stow whoami`** -- Show account info, usage stats, and API key details.
+
+**`stow open <bucket>`** -- Open a bucket in the browser.
+
+**`stow delete <bucket> <key>`** -- Delete a file from a bucket.
+
+```bash
+stow delete photos hero/banner.png
+```
+
+## Interactive Mode
+
+Run `stow` with no arguments or `stow -i` to launch the interactive TUI. Browse buckets, files, and perform actions with a keyboard-driven interface.
+
+```bash
+stow
+stow --interactive
+```
+
+## JSON Output
+
+Most commands support `--json` for machine-readable output. Useful for scripting and piping into tools like `jq`:
+
+```bash
+stow files photos --json | jq '.[].key'
+stow search text 'landscape' -b photos --json | jq length
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `STOW_API_KEY` | -- | API key for authentication |
+| `STOW_API_URL` | `https://api.stow.sh` | API base URL |
+| `STOW_ADMIN_SECRET` | -- | Secret for admin commands |
+
+## License
+
+MIT

package/dist/buckets-ESAOL6CH.js

@@ -0,0 +1,115 @@
+import {
+  validateBucketName
+} from "./chunk-OHAFRKN5.js";
+import {
+  formatBytes,
+  formatTable
+} from "./chunk-ELSDWMEB.js";
+import {
+  createStow
+} from "./chunk-5LU25QZK.js";
+import "./chunk-TOADDO2F.js";
+
+// src/commands/buckets.ts
+async function listBuckets() {
+  const stow = createStow();
+  const data = await stow.listBuckets();
+  if (data.buckets.length === 0) {
+    console.log("No buckets yet. Create one with: stow buckets create <name>");
+    return;
+  }
+  const rows = data.buckets.map((b) => [
+    b.name,
+    b.isPublic ? "public" : "private",
+    b.searchable ? "yes" : "no",
+    `${b.fileCount ?? 0} files`,
+    formatBytes(b.usageBytes ?? 0),
+    b.description || ""
+  ]);
+  console.log(
+    formatTable(
+      ["Name", "Access", "Search", "Files", "Size", "Description"],
+      rows
+    )
+  );
+}
+async function createBucket(name, options) {
+  validateBucketName(name);
+  if (options.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          dryRun: true,
+          action: "createBucket",
+          details: {
+            name,
+            description: options.description ?? null,
+            isPublic: options.public ?? false
+          }
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  const stow = createStow();
+  const bucket = await stow.createBucket({
+    name,
+    ...options.description ? { description: options.description } : {},
+    ...options.public ? { isPublic: true } : {}
+  });
+  console.log(`Created bucket: ${bucket.name}`);
+}
+async function renameBucket(name, newName, options) {
+  validateBucketName(name);
+  validateBucketName(newName);
+  if (options.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          dryRun: true,
+          action: "renameBucket",
+          details: { name, newName }
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  if (!options.yes) {
+    console.error(
+      "Warning: Renaming a bucket will break any existing URLs using the old name."
+    );
+    console.error("Use --yes to skip this warning.");
+  }
+  const stow = createStow();
+  const bucket = await stow.renameBucket(name, newName);
+  console.log(`Renamed bucket: ${name} \u2192 ${bucket.name}`);
+}
+async function deleteBucket(id, options = {}) {
+  if (options.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          dryRun: true,
+          action: "deleteBucket",
+          details: { id }
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  const stow = createStow();
+  await stow.deleteBucket(id);
+  console.log(`Deleted bucket: ${id}`);
+}
+export {
+  createBucket,
+  deleteBucket,
+  listBuckets,
+  renameBucket
+};

package/dist/chunk-OHAFRKN5.js

@@ -0,0 +1,40 @@
+// src/lib/validate-input.ts
+var InputValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InputValidationError";
+  }
+};
+function validateInput(value, context) {
+  if (value.includes("../") || value.includes("..\\")) {
+    throw new InputValidationError(`${context}: path traversal not allowed`);
+  }
+  if (context !== "url" && value.includes("?")) {
+    throw new InputValidationError(
+      `${context}: embedded query parameters not allowed`
+    );
+  }
+  if (/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(value)) {
+    throw new InputValidationError(
+      `${context}: control characters not allowed`
+    );
+  }
+  if (/%25/.test(value)) {
+    throw new InputValidationError(
+      `${context}: double-encoded values not allowed`
+    );
+  }
+  return value;
+}
+function validateBucketName(name) {
+  return validateInput(name, "bucket name");
+}
+function validateFileKey(key) {
+  return validateInput(key, "file key");
+}
+
+export {
+  validateInput,
+  validateBucketName,
+  validateFileKey
+};