stow-cli 2.0.4 → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/app-Q6EW7VSM.js

@@ -0,0 +1,249 @@
+import {
+  formatBytes
+} from "./chunk-FZGOTXTE.js";
+import {
+  createStow
+} from "./chunk-5LU25QZK.js";
+import "./chunk-TOADDO2F.js";
+
+// src/interactive/app.tsx
+import { render } from "ink";
+import { useEffect as useEffect3, useState as useState3 } from "react";
+
+// src/interactive/components/bucket-list.tsx
+import { Box as Box3, Text as Text3, useApp, useInput } from "ink";
+import Spinner from "ink-spinner";
+import { useEffect, useState } from "react";
+
+// src/interactive/components/header.tsx
+import { Box, Text } from "ink";
+import { jsx, jsxs } from "react/jsx-runtime";
+function Header({ path, email, size }) {
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsxs(Box, { justifyContent: "space-between", width: "100%", children: [
+      /* @__PURE__ */ jsxs(Text, { bold: true, children: [
+        "STOW",
+        path ? ` > ${path}` : ""
+      ] }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: size || email || "" })
+    ] }),
+    /* @__PURE__ */ jsx(Text, { dimColor: true, children: "\u2500".repeat(50) })
+  ] });
+}
+
+// src/interactive/components/status-bar.tsx
+import { Box as Box2, Text as Text2 } from "ink";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function StatusBar({ hints }) {
+  return /* @__PURE__ */ jsx2(Box2, { marginTop: 1, children: hints.map((h, i) => /* @__PURE__ */ jsx2(Box2, { marginRight: 2, children: /* @__PURE__ */ jsxs2(Text2, { dimColor: true, children: [
+    "[",
+    h.key,
+    "]",
+    h.label,
+    i < hints.length - 1 ? "" : ""
+  ] }) }, h.key)) });
+}
+
+// src/interactive/components/bucket-list.tsx
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function toBucket(result) {
+  return {
+    id: result.id,
+    name: result.name,
+    description: result.description ?? null,
+    fileCount: result.fileCount ?? 0,
+    isPublic: result.isPublic ?? false,
+    usageBytes: result.usageBytes ?? 0
+  };
+}
+function BucketList({ onSelect, email }) {
+  const { exit } = useApp();
+  const [buckets, setBuckets] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [cursor, setCursor] = useState(0);
+  useEffect(() => {
+    const stow = createStow();
+    stow.listBuckets().then((data) => {
+      setBuckets(data.buckets.map(toBucket));
+      setLoading(false);
+    }).catch((err) => {
+      setError(err instanceof Error ? err.message : String(err));
+      setLoading(false);
+    });
+  }, []);
+  useInput((input, key) => {
+    if (input === "q") {
+      exit();
+      return;
+    }
+    if (key.upArrow) {
+      setCursor((c) => Math.max(0, c - 1));
+    } else if (key.downArrow) {
+      setCursor((c) => Math.min(buckets.length - 1, c + 1));
+    } else if (key.return && buckets.length > 0) {
+      onSelect(buckets[cursor]);
+    }
+  });
+  if (loading) {
+    return /* @__PURE__ */ jsx3(Box3, { children: /* @__PURE__ */ jsxs3(Text3, { children: [
+      /* @__PURE__ */ jsx3(Spinner, { type: "dots" }),
+      " Loading buckets..."
+    ] }) });
+  }
+  if (error) {
+    return /* @__PURE__ */ jsx3(Box3, { flexDirection: "column", children: /* @__PURE__ */ jsxs3(Text3, { color: "red", children: [
+      "Error: ",
+      error
+    ] }) });
+  }
+  return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx3(Header, { email }),
+    buckets.length === 0 ? /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "No buckets yet. Press 'n' to create one." }) : buckets.map((b, i) => /* @__PURE__ */ jsx3(Box3, { children: /* @__PURE__ */ jsxs3(Text3, { color: i === cursor ? "cyan" : void 0, children: [
+      i === cursor ? "\u25B8 " : "  ",
+      b.name.padEnd(20),
+      `${b.fileCount} files`.padEnd(14),
+      formatBytes(b.usageBytes)
+    ] }) }, b.id)),
+    /* @__PURE__ */ jsx3(
+      StatusBar,
+      {
+        hints: [
+          { key: "\u2191\u2193", label: "navigate" },
+          { key: "\u21B5", label: "open" },
+          { key: "q", label: "uit" }
+        ]
+      }
+    )
+  ] });
+}
+
+// src/interactive/components/file-list.tsx
+import { Box as Box4, Text as Text4, useInput as useInput2 } from "ink";
+import Spinner2 from "ink-spinner";
+import { useEffect as useEffect2, useState as useState2 } from "react";
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+function FileList({ bucket, onBack }) {
+  const [files, setFiles] = useState2([]);
+  const [loading, setLoading] = useState2(true);
+  const [error, setError] = useState2(null);
+  const [cursor, setCursor] = useState2(0);
+  const [nextCursor, setNextCursor] = useState2(null);
+  const [copied, setCopied] = useState2(false);
+  useEffect2(() => {
+    loadFiles();
+  }, []);
+  function loadFiles(pageCursor) {
+    setLoading(true);
+    const stow = createStow();
+    stow.listFiles({
+      bucket: bucket.name,
+      ...pageCursor ? { cursor: pageCursor } : {}
+    }).then((data) => {
+      setFiles(
+        (prev) => pageCursor ? [...prev, ...data.files] : data.files
+      );
+      setNextCursor(data.nextCursor);
+      setLoading(false);
+    }).catch((err) => {
+      setError(err instanceof Error ? err.message : String(err));
+      setLoading(false);
+    });
+  }
+  useInput2((input, key) => {
+    if (key.escape || key.backspace || key.leftArrow && !loading) {
+      onBack();
+      return;
+    }
+    if (key.upArrow) {
+      setCursor((c) => Math.max(0, c - 1));
+    } else if (key.downArrow) {
+      setCursor((c) => {
+        const next = Math.min(files.length - 1, c + 1);
+        if (next >= files.length - 3 && nextCursor && !loading) {
+          loadFiles(nextCursor);
+        }
+        return next;
+      });
+    } else if (input === "c" && files.length > 0) {
+      import("clipboardy").then(({ default: clipboard }) => {
+        clipboard.write(files[cursor].url).then(() => {
+          setCopied(true);
+          setTimeout(() => setCopied(false), 2e3);
+        });
+      });
+    }
+  });
+  if (error) {
+    return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsxs4(Text4, { color: "red", children: [
+        "Error: ",
+        error
+      ] }),
+      /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: "Press Esc to go back." })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx4(Header, { path: bucket.name, size: formatBytes(bucket.usageBytes) }),
+    loading && files.length === 0 && /* @__PURE__ */ jsxs4(Text4, { children: [
+      /* @__PURE__ */ jsx4(Spinner2, { type: "dots" }),
+      " Loading files..."
+    ] }),
+    !loading && files.length === 0 && /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: "No files in this bucket." }),
+    files.length > 0 && files.map((f, i) => /* @__PURE__ */ jsx4(Box4, { children: /* @__PURE__ */ jsxs4(Text4, { color: i === cursor ? "cyan" : void 0, children: [
+      i === cursor ? "\u25B8 " : "  ",
+      f.key.padEnd(28),
+      formatBytes(f.size).padEnd(10),
+      f.lastModified.split("T")[0]
+    ] }) }, f.key)),
+    loading && files.length > 0 && /* @__PURE__ */ jsxs4(Text4, { dimColor: true, children: [
+      /* @__PURE__ */ jsx4(Spinner2, { type: "dots" }),
+      " Loading more..."
+    ] }),
+    copied && /* @__PURE__ */ jsx4(Text4, { color: "green", children: "Copied URL to clipboard!" }),
+    /* @__PURE__ */ jsx4(
+      StatusBar,
+      {
+        hints: [
+          { key: "\u2191\u2193", label: "navigate" },
+          { key: "c", label: "opy url" },
+          { key: "\u2190", label: "back" }
+        ]
+      }
+    )
+  ] });
+}
+
+// src/interactive/app.tsx
+import { jsx as jsx5 } from "react/jsx-runtime";
+function App() {
+  const [screen, setScreen] = useState3({ type: "buckets" });
+  const [email, setEmail] = useState3();
+  useEffect3(() => {
+    const stow = createStow();
+    stow.whoami().then((data) => setEmail(data.user.email)).catch(() => {
+    });
+  }, []);
+  if (screen.type === "files") {
+    return /* @__PURE__ */ jsx5(
+      FileList,
+      {
+        bucket: screen.bucket,
+        onBack: () => setScreen({ type: "buckets" })
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx5(
+    BucketList,
+    {
+      email,
+      onSelect: (bucket) => setScreen({ type: "files", bucket })
+    }
+  );
+}
+function startInteractive() {
+  render(/* @__PURE__ */ jsx5(App, {}));
+}
+export {
+  startInteractive
+};

package/dist/backfill-EVZT7RH6.js

@@ -0,0 +1,67 @@
+import {
+  adminRequest
+} from "./chunk-QF7PVPWQ.js";
+import {
+  output
+} from "./chunk-P2BKGBQE.js";
+import "./chunk-TOADDO2F.js";
+
+// src/commands/admin/backfill.ts
+async function runBackfill(type, options) {
+  const parsedLimit = options.limit ? Number.parseInt(options.limit, 10) : null;
+  const body = {};
+  if (options.bucket) {
+    body.bucketId = options.bucket;
+  }
+  if (parsedLimit && parsedLimit > 0) {
+    body.limit = parsedLimit;
+  }
+  if (options.dryRun) {
+    body.dryRun = true;
+  }
+  const result = await adminRequest({
+    method: "POST",
+    path: `/internal/files/${type}/backfill`,
+    body
+  });
+  output(
+    result,
+    () => {
+      const lines = [];
+      if (result.dryRun) {
+        lines.push(
+          `[dry run] ${result.remaining} files need ${type} processing`
+        );
+        return lines.join("\n");
+      }
+      lines.push(`Enqueued: ${result.enqueued ?? 0}`);
+      lines.push(`Remaining: ${result.remaining}`);
+      if (result.errors && result.errors.length > 0) {
+        lines.push(`
+Errors (${result.errors.length}):`);
+        for (const err of result.errors) {
+          lines.push(`  ${err.fileId}: ${err.error}`);
+        }
+      }
+      if (result.nextCursor) {
+        lines.push("\n(more files available -- run again to continue)");
+      }
+      return lines.join("\n");
+    },
+    { json: options.json }
+  );
+}
+async function backfillDimensions(options) {
+  await runBackfill("dimensions", options);
+}
+async function backfillColors(options) {
+  await runBackfill("colors", options);
+}
+async function backfillEmbeddings(options) {
+  await runBackfill("embeddings", options);
+}
+export {
+  backfillColors,
+  backfillDimensions,
+  backfillEmbeddings
+};