@flekh/review 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @flekh/review
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Upload a file from your computer to [Flekh](https://flekh.com), from Claude Code or any AI agent with a terminal.
+
+You don't run this yourself. Connect Flekh to your AI (connector URL `https://api.flekh.com/mcp`) and ask:
+
+> upload ~/Movies/cut_v3.mp4 to Acme Studio as version 2 of Summer teaser
+
+The connector's `start_upload(path)` checks the project's Agents rules and gives your AI one command with a one-time
+ticket; your AI runs it:
+
+```bash
+npx -y @flekh/review upload ~/Movies/cut_v3.mp4 --ticket rvw_…
+```
+
+It sends the file straight to Flekh's storage in 16 MB parts (4 at a time, retried), then finishes the upload and
+prints the file's link. Big files are fine (up to your plan's file limit).
+
+- **Ticket:** one file, upload only, as you and your AI connection. Start it within 30 minutes; once started it
+  lasts as long as the upload (24 h). It can't read anything in Flekh.
+- **Resume:** run the same command again; it sends only the parts Flekh doesn't have.
+- **Ctrl-C** cancels the upload; Flekh removes what it made.
+- **Options:** `--api <url>` (or `FLEKH_API`) for a non-production Flekh, `--json` for one line of JSON.
+- **Exit codes:** 0 uploaded · 1 refused by Flekh (message says why) · 2 network or storage problem (run again to resume).
+
+Needs Node 18 or newer. No dependencies.
+
+## Develop
+
+```bash
+npm test          # vitest, fake Flekh + S3
+npm run build     # dist/
+npm publish       # @flekh org, public (prepublishOnly builds)
+```
+
+API: `Flekh-Backend-Service/docs/api/agents/02-agent-actions-contract.md` §1 "Upload tickets".

package/dist/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// flekh-review upload <path> --ticket rvw_… [--api URL] [--json]
+// Run by an AI agent (Claude Code, Codex, Cursor…) as the Flekh connector's start_upload(path) tells it to.
+import { ReviewError, cancel, upload } from "./upload.js";
+const HELP = `Upload a file from this computer to Flekh.
+
+  npx -y @flekh/review upload <path> --ticket <rvw_…> [--api <url>] [--json]
+
+Ask your AI (with the Flekh connector) to upload a file by its path; it gets a one-time ticket and runs this for you.
+Exit codes: 0 uploaded · 1 refused by Flekh (see the message) · 2 network or S3 problem (run it again to resume).`;
+function args(argv) {
+    const out = { json: false, help: false, version: false };
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--ticket")
+            out.ticket = argv[++i];
+        else if (a.startsWith("--ticket="))
+            out.ticket = a.slice(9);
+        else if (a === "--api")
+            out.api = argv[++i];
+        else if (a.startsWith("--api="))
+            out.api = a.slice(6);
+        else if (a === "--json")
+            out.json = true;
+        else if (a === "-h" || a === "--help")
+            out.help = true;
+        else if (a === "-v" || a === "--version")
+            out.version = true;
+        else
+            rest.push(a);
+    }
+    [out.cmd, out.path] = rest;
+    return out;
+}
+export function bytes(n) {
+    const u = ["B", "KB", "MB", "GB", "TB"];
+    let i = 0;
+    while (n >= 1000 && i < u.length - 1) {
+        n /= 1000;
+        i++;
+    }
+    return `${i === 0 ? n : n.toFixed(n >= 100 ? 0 : 1)} ${u[i]}`;
+}
+async function main() {
+    const a = args(process.argv.slice(2));
+    if (a.version) {
+        console.log("0.1.0");
+        return 0;
+    }
+    if (a.help || a.cmd !== "upload" || !a.path || !a.ticket) {
+        console.log(HELP);
+        return a.help ? 0 : 1;
+    }
+    const api = a.api || process.env.FLEKH_API;
+    const tty = process.stderr.isTTY && !a.json;
+    let lastPct = -1;
+    const onProgress = (p) => {
+        const pct = Math.floor((p.sent / p.size) * 100);
+        if (tty)
+            process.stderr.write(`\r${pct}% · ${bytes(p.sent)} of ${bytes(p.size)} · part ${p.partsDone}/${p.partsTotal}   `);
+        else if (!a.json && pct >= lastPct + 10) {
+            console.log(`${pct}% (${p.partsDone}/${p.partsTotal} parts)`);
+            lastPct = pct - (pct % 10);
+        }
+    };
+    let finished = false;
+    process.once("SIGINT", () => {
+        if (finished)
+            process.exit(130);
+        console.error("\nCancelling…");
+        void cancel({ ticket: a.ticket, api }).finally(() => process.exit(130));
+    });
+    try {
+        const r = await upload({ path: a.path, ticket: a.ticket, api, onProgress });
+        finished = true;
+        if (tty)
+            process.stderr.write("\n");
+        if (a.json)
+            console.log(JSON.stringify({ ok: true, ...r }));
+        else
+            console.log(`✓ ${r.name} (${bytes(r.size)})${r.version ? ` → v${r.version}` : ""}${r.project ? ` in ${r.project}` : ""}${r.link ? ` · ${r.link}` : ""}\n  Flekh is processing it now (thumbnail and preview in a minute).`);
+        return 0;
+    }
+    catch (e) {
+        finished = true;
+        if (tty)
+            process.stderr.write("\n");
+        const err = e instanceof ReviewError ? e : new ReviewError(e.message, "ERROR");
+        if (a.json)
+            console.log(JSON.stringify({ ok: false, error: err.code, message: err.message }));
+        else
+            console.error(`✗ ${err.message}`);
+        return err.refused ? 1 : 2;
+    }
+}
+main().then((code) => process.exit(code));

package/dist/upload.js

@@ -0,0 +1,153 @@
+// One file from this computer into Flekh with a one-time upload ticket (made by the Flekh connector's start_upload(path)).
+// start (size, type) → part URLs in batches → PUT 16 MiB parts straight to S3, a few at a time, with retries → complete.
+// A re-run with the same ticket resumes: Flekh says which parts it already has. Signed URLs never leave this process.
+import { open, stat } from "node:fs/promises";
+import { basename, extname } from "node:path";
+export const PROD_API = "https://api.flekh.com";
+const BATCH = 32; // part URLs per /parts call (Flekh's cap)
+const TRIES = 4;
+export class ReviewError extends Error {
+    code;
+    refused;
+    constructor(message, code, refused = false) {
+        super(message);
+        this.code = code;
+        this.refused = refused;
+    }
+}
+const MIME = {
+    ".mp4": "video/mp4", ".m4v": "video/x-m4v", ".mov": "video/quicktime", ".webm": "video/webm", ".mkv": "video/x-matroska",
+    ".avi": "video/x-msvideo", ".mxf": "application/mxf", ".mp3": "audio/mpeg", ".wav": "audio/wav", ".aac": "audio/aac",
+    ".m4a": "audio/mp4", ".flac": "audio/flac", ".ogg": "audio/ogg", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png",
+    ".gif": "image/gif", ".webp": "image/webp", ".heic": "image/heic", ".tif": "image/tiff", ".tiff": "image/tiff", ".pdf": "application/pdf",
+    ".txt": "text/plain", ".md": "text/markdown", ".csv": "text/csv",
+};
+export function mimeOf(path) {
+    return MIME[extname(path).toLowerCase()] ?? "application/octet-stream";
+}
+export async function upload(o) {
+    const f = o.fetch ?? fetch;
+    const sleep = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const api = (o.api || PROD_API).replace(/\/+$/, "");
+    const st = await stat(o.path).catch(() => null);
+    if (!st || !st.isFile())
+        throw new ReviewError(`No file at ${o.path}`, "NO_FILE", true);
+    if (st.size === 0)
+        throw new ReviewError(`${o.path} is empty`, "EMPTY_FILE", true);
+    const size = st.size;
+    const flekh = async (method, path, body, okCodes = []) => {
+        for (let i = 1;; i++) {
+            let res;
+            try {
+                res = await f(`${api}/v1/upload-tickets${path}`, {
+                    method,
+                    headers: { Authorization: `Ticket ${o.ticket}`, "Content-Type": "application/json" },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                });
+            }
+            catch (e) {
+                if (i < TRIES) {
+                    await sleep(500 * 2 ** i);
+                    continue;
+                }
+                throw new ReviewError(`Can't reach Flekh (${api}): ${e.message}`, "NETWORK");
+            }
+            const json = (await res.json().catch(() => ({})));
+            if (res.ok || okCodes.includes(res.status))
+                return { status: res.status, json };
+            if (res.status >= 500 && i < TRIES) {
+                await sleep(500 * 2 ** i);
+                continue;
+            }
+            throw new ReviewError(json.message || `Flekh answered ${res.status}`, json.error || `HTTP_${res.status}`, res.status < 500);
+        }
+    };
+    // start, or resume a run of the same ticket
+    let s;
+    const started = await flekh("POST", "/start", { name: basename(o.path), size, mime: mimeOf(o.path) }, [409]);
+    if (started.status === 409 && started.json.error === "ALREADY_STARTED") {
+        s = (await flekh("GET", "/status")).json;
+        if (s.size !== undefined && s.size !== size) {
+            throw new ReviewError("This ticket's upload is for a different file (size changed). Ask the AI to start the upload again.", "SIZE_CHANGED", true);
+        }
+    }
+    else if (started.status === 409) {
+        throw new ReviewError(started.json.message || "This upload ticket was already used.", started.json.error || "CONFLICT", true);
+    }
+    else {
+        s = started.json;
+    }
+    const partSize = s.part_size;
+    const total = s.parts_total;
+    const done = new Set(Array.isArray(s.parts_done) ? s.parts_done : []);
+    const urls = new Map((s.parts ?? []).map((p) => [p.n, p.url]));
+    const lenOf = (n) => (n === total ? size - (n - 1) * partSize : partSize);
+    let sent = 0;
+    for (const n of done)
+        sent += lenOf(n);
+    const report = () => o.onProgress?.({ sent, size, partsDone: done.size, partsTotal: total });
+    report();
+    const todo = Array.from({ length: total }, (_, i) => i + 1).filter((n) => !done.has(n));
+    let refill = null;
+    const urlFor = async (n, fresh = false) => {
+        if (fresh)
+            urls.delete(n);
+        while (!urls.has(n)) {
+            if (!refill) {
+                const want = [n, ...todo.filter((m) => m !== n && !urls.has(m) && !done.has(m))].slice(0, BATCH);
+                refill = flekh("POST", "/parts", { parts: want })
+                    .then((r) => { for (const p of r.json.parts)
+                    urls.set(p.n, p.url); })
+                    .finally(() => { refill = null; });
+            }
+            await refill;
+        }
+        return urls.get(n);
+    };
+    const fh = await open(o.path, "r");
+    try {
+        const sendPart = async (n) => {
+            const len = lenOf(n);
+            const buf = Buffer.alloc(len);
+            const { bytesRead } = await fh.read(buf, 0, len, (n - 1) * partSize);
+            if (bytesRead !== len)
+                throw new ReviewError(`${o.path} changed while uploading`, "FILE_CHANGED", true);
+            for (let i = 1;; i++) {
+                const url = await urlFor(n, i > 1);
+                let status = 0;
+                try {
+                    const res = await f(url, { method: "PUT", body: buf, headers: { "Content-Length": String(len) } });
+                    status = res.status;
+                    if (res.ok)
+                        break;
+                }
+                catch { /* network: retry */ }
+                if (i >= TRIES)
+                    throw new ReviewError(`Part ${n} of ${total} didn't upload${status ? ` (S3 ${status})` : ""}. Run the same command again to resume.`, "PART_FAILED");
+                await sleep(500 * 2 ** i);
+            }
+            urls.delete(n);
+            done.add(n);
+            sent += len;
+            report();
+        };
+        const queue = [...todo];
+        const workers = Math.max(1, Math.min(o.parallel ?? s.max_parallel ?? 4, 8, queue.length || 1));
+        await Promise.all(Array.from({ length: workers }, async () => {
+            for (let n = queue.shift(); n !== undefined; n = queue.shift())
+                await sendPart(n);
+        }));
+    }
+    finally {
+        await fh.close();
+    }
+    const card = (await flekh("POST", "/complete")).json;
+    const a = card.asset ?? {};
+    return { name: a.name ?? s.asset_name ?? basename(o.path), version: a.version ?? s.version, size, link: a.link, project: a.project?.name, status: card.status };
+}
+/** Cancel the ticket's upload (Ctrl-C): Flekh removes what it made. */
+export async function cancel(o) {
+    const f = o.fetch ?? fetch;
+    const api = (o.api || PROD_API).replace(/\/+$/, "");
+    await f(`${api}/v1/upload-tickets/cancel`, { method: "POST", headers: { Authorization: `Ticket ${o.ticket}` } }).catch(() => undefined);
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@flekh/review",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Upload files from your computer to Flekh, from Claude Code or any AI agent with a terminal",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "flekh-review": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://flekh.com",
+  "keywords": [
+    "flekh",
+    "upload",
+    "mcp",
+    "claude",
+    "review"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run --root ."
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}