argus-media-cli 0.3.0 → 0.4.1

package/README.md

@@ -35,6 +35,45 @@ argus-media-cli upload photo.jpg
 argus-media-cli upload hero.png --project campaign-q2 --tags hero,banner
 ```
 
+### Sync
+
+Onboard an entire folder of assets in one shot — ideal for migrating a legacy
+brand folder. `sync` walks the folder recursively, filters out junk and
+unsupported files, dedupes, uploads what's left sequentially, and prints a
+manifest of what was synced, skipped, and failed.
+
+```bash
+argus-media-cli sync ./legacy-brand-folder --dry-run          # preview the plan
+argus-media-cli sync ./legacy-brand-folder                    # upload for real
+argus-media-cli sync ./assets --project brand-2019 --tags legacy,imported
+argus-media-cli sync ./assets --json                          # structured manifest
+```
+
+**What it uploads:** JPEG, PNG, GIF, WebP, and SVG files up to 20 MB.
+
+**What it skips (with a stated reason):**
+
+- Junk files (`.DS_Store`, `Thumbs.db`, `desktop.ini`) and hidden dotfiles
+- Unsupported file types
+- Files larger than the 20 MB server cap
+- Duplicates — identical file contents (hashed), and any asset already in the
+  target project with the same filename + size
+
+**Project:** defaults to the kebab-cased folder name (e.g. `Legacy Brand
+Folder` → `legacy-brand-folder`). Override with `--project`.
+
+**Credits:** each analyzable upload costs 1 credit. If the plan exceeds your
+remaining credits, `sync` warns and asks for confirmation; pass `--yes` to skip
+the prompt (uploads past the limit are stored without AI analysis).
+
+| Flag | Description |
+|---|---|
+| `--project NAME` | Target project (default: kebab-cased folder name) |
+| `--tags a,b,c` | Tags applied to every synced asset |
+| `--dry-run` | Print the plan without uploading |
+| `--json` | Emit the manifest as structured JSON |
+| `--yes` | Skip the credit-shortfall confirmation prompt |
+
 ### Search
 
 ```bash

package/dist/index.js

@@ -2,7 +2,9 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import * as readline from "node:readline";
+import { basicSkipReason, buildPlan, deriveProject, formatManifestText, toJsonManifest, walk, } from "./sync.js";
 // ─── Config ────────────────────────────────────────────────────────────────
 const CONFIG_DIR = join(homedir(), ".argus");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
@@ -307,6 +309,211 @@ async function cmdUsage(_args, flags) {
         console.log(`  Storage:  ${data.storage?.used != null ? formatBytes(data.storage.used) : "0 B"} / ${data.storage?.limit != null ? formatBytes(data.storage.limit) : "unlimited"}`);
     }
 }
+/** Upload a single file. Returns the created asset, or a duplicate marker on 409. */
+async function uploadFile(config, filePath, fileName, project, tags) {
+    const baseUrl = getBaseUrl(config);
+    const fileData = await readFile(filePath);
+    const ext = extname(fileName).toLowerCase();
+    const mimeType = MIME_TYPES[ext] || "application/octet-stream";
+    const blob = new Blob([fileData], { type: mimeType });
+    const form = new FormData();
+    form.append("file", blob, fileName);
+    if (project)
+        form.append("project", project);
+    if (tags)
+        form.append("tags", tags);
+    const res = await fetch(`${baseUrl}/assets/upload`, {
+        method: "POST",
+        headers: { ...getAuthHeaders(config) },
+        body: form,
+    });
+    // The server enforces workspace-wide exact-content dedup and returns 409 with
+    // the pre-existing asset. Surface that as a duplicate skip, not a failure.
+    if (res.status === 409) {
+        const body = (await res.json().catch(() => ({})));
+        const existing = body?.duplicate?.asset;
+        return {
+            duplicateOf: existing?.filename
+                ? `${existing.filename} (${existing.id})`
+                : "an existing asset",
+        };
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`upload failed (${res.status}): ${text}`);
+    }
+    const data = (await res.json());
+    return { asset: data.asset };
+}
+/** Poll an asset until it reaches a terminal status (ready/error) or times out. */
+async function pollUntilReady(config, id, timeoutMs = 60_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const data = (await apiRequest(config, "GET", `/assets/${id}`));
+        const status = data.asset?.status;
+        if (status === "ready" || status === "error")
+            return status;
+        await new Promise((r) => setTimeout(r, 2000));
+    }
+    return "pending"; // timed out — still queued, not a hard failure
+}
+/** Fetch every existing asset in a project (paginated) for filename+size dedup. */
+async function fetchExistingAssets(config, project) {
+    const existing = [];
+    const pageSize = 200;
+    let offset = 0;
+    for (;;) {
+        const params = new URLSearchParams({
+            project,
+            limit: String(pageSize),
+            offset: String(offset),
+        });
+        const data = (await apiRequest(config, "GET", `/assets?${params}`));
+        const assets = data.assets ?? [];
+        for (const a of assets) {
+            if (typeof a.size === "number")
+                existing.push({ filename: a.filename, size: a.size });
+        }
+        if (assets.length < pageSize)
+            break;
+        offset += pageSize;
+    }
+    return existing;
+}
+async function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(question, resolve));
+    rl.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+async function cmdSync(args, flags) {
+    const folder = args[0];
+    if (!folder) {
+        console.error("Usage: argus-media-cli sync <folder> [--project NAME] [--tags a,b,c] [--dry-run] [--json] [--yes]");
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const project = flags.project || deriveProject(folder);
+    const tags = flags.tags;
+    const dryRun = !!flags["dry-run"];
+    const asJson = !!flags.json;
+    const assumeYes = !!flags.yes;
+    // 1. Walk the folder.
+    let files;
+    try {
+        files = await walk(folder);
+    }
+    catch (err) {
+        throw new Error(`could not read folder '${folder}': ${err.message}`);
+    }
+    // 2. Hash the files that pass the cheap filters, so content-dedup can run.
+    const hashed = [];
+    for (const f of files) {
+        if (basicSkipReason(f)) {
+            hashed.push(f); // no hash needed — will be skipped in buildPlan
+            continue;
+        }
+        const buf = await readFile(f.path);
+        hashed.push({ ...f, hash: createHash("sha256").update(buf).digest("hex") });
+    }
+    // 3. Dedup against what's already in the target project.
+    const existing = await fetchExistingAssets(config, project);
+    const plan = buildPlan(hashed, existing);
+    const result = {
+        synced: [],
+        skipped: plan.skip.map((s) => ({ filename: s.filename, reason: s.reason })),
+        failed: [],
+    };
+    // 4. Dry run: show the plan and stop.
+    if (dryRun) {
+        result.synced = plan.include.map((f) => ({ id: "", filename: f.name }));
+        if (asJson) {
+            console.log(JSON.stringify(toJsonManifest(result, { project, dryRun: true }), null, 2));
+        }
+        else {
+            console.log(formatManifestText(result, { project, dryRun: true }));
+        }
+        return;
+    }
+    if (plan.include.length === 0) {
+        if (asJson) {
+            console.log(JSON.stringify(toJsonManifest(result, { project, dryRun: false }), null, 2));
+        }
+        else {
+            console.log(formatManifestText(result, { project, dryRun: false }));
+        }
+        return;
+    }
+    // 5. Credit check — each analyzable upload costs 1 credit. The server draws
+    //    from monthly credits first, then one-time bonus credits, so the real
+    //    balance is remaining + bonus.
+    try {
+        const usage = (await apiRequest(config, "GET", "/usage"));
+        const available = (usage.credits?.remaining ?? 0) + (usage.credits?.bonus ?? 0);
+        if (plan.include.length > available) {
+            const msg = `Plan uploads ${plan.include.length} file(s) but only ${available} credit(s) remain; uploads past the limit will store without AI analysis.`;
+            if (assumeYes) {
+                console.error(`Warning: ${msg}`);
+            }
+            else if (!asJson) {
+                const ok = await confirm(`${msg}\nContinue? [y/N] `);
+                if (!ok) {
+                    console.log("Aborted.");
+                    return;
+                }
+            }
+            else {
+                throw new Error(`${msg} Re-run with --yes to proceed.`);
+            }
+        }
+    }
+    catch (err) {
+        // Only abort if this was our own credit-guard error; usage lookups are best-effort.
+        if (/Re-run with --yes/.test(err.message))
+            throw err;
+    }
+    // 6. Upload sequentially, then poll each to a terminal state.
+    for (const f of plan.include) {
+        if (!asJson)
+            process.stderr.write(`Uploading ${f.name}… `);
+        try {
+            const outcome = await uploadFile(config, f.path, f.name, project, tags);
+            if (outcome.duplicateOf) {
+                result.skipped.push({
+                    filename: f.name,
+                    reason: `duplicate of ${outcome.duplicateOf}`,
+                });
+                if (!asJson)
+                    process.stderr.write("duplicate\n");
+                continue;
+            }
+            const asset = outcome.asset;
+            const status = await pollUntilReady(config, asset.id);
+            if (status === "error") {
+                result.failed.push({ filename: f.name, error: `analysis failed (${asset.id})` });
+                if (!asJson)
+                    process.stderr.write("error\n");
+            }
+            else {
+                result.synced.push({ id: asset.id, filename: f.name });
+                if (!asJson)
+                    process.stderr.write(status === "ready" ? "ready\n" : "queued\n");
+            }
+        }
+        catch (err) {
+            result.failed.push({ filename: f.name, error: err.message });
+            if (!asJson)
+                process.stderr.write("failed\n");
+        }
+    }
+    // 7. Manifest.
+    if (asJson) {
+        console.log(JSON.stringify(toJsonManifest(result, { project, dryRun: false }), null, 2));
+    }
+    else {
+        console.log("\n" + formatManifestText(result, { project, dryRun: false }));
+    }
+}
 // ─── Phase 2: Generative Commands ─────────────────────────────────────────
 async function cmdCreativeDirection(args, flags) {
     const id = args[0];
@@ -570,6 +777,7 @@ function printHelp() {
 \x1b[1mCommands:\x1b[0m
   login                   Authenticate with Argus
   upload <file>           Upload a media file
+  sync <folder>           Onboard a folder of assets in one shot
   search <query>          Search assets by description, tags, mood
   list                    List all assets
   get <id>                Get asset details and analysis
@@ -590,6 +798,12 @@ function printHelp() {
   --project NAME          Assign to a project
   --tags a,b,c            Comma-separated tags
 
+\x1b[1mSync Options:\x1b[0m
+  --project NAME          Target project (default: kebab-cased folder name)
+  --tags a,b,c            Tags applied to every synced asset
+  --dry-run               Print the plan without uploading
+  --yes                   Skip the credit-shortfall confirmation prompt
+
 \x1b[1mSearch/List Options:\x1b[0m
   --project NAME          Filter by project
   --status STATUS         Filter by status (pending, ready, error)
@@ -628,6 +842,8 @@ function printHelp() {
 \x1b[1mExamples:\x1b[0m
   argus-media-cli login
   argus-media-cli upload photo.jpg --project campaign-q2 --tags hero,banner
+  argus-media-cli sync ./legacy-brand-folder --dry-run
+  argus-media-cli sync ./legacy-brand-folder --project brand-2019 --tags legacy
   argus-media-cli search "sunset landscape" --json
   argus-media-cli list --project website --limit 20
   argus-media-cli get abc12345-def6-7890-abcd-ef1234567890
@@ -653,6 +869,7 @@ const COMMANDS = {
     dashboard: cmdDashboard,
     login: cmdLogin,
     upload: cmdUpload,
+    sync: cmdSync,
     search: cmdSearch,
     list: cmdList,
     get: cmdGet,
@@ -694,7 +911,7 @@ async function main() {
         return;
     }
     if (command === "version" || command === "--version" || command === "-v") {
-        console.log("argus-media-cli 0.3.0");
+        console.log("argus-media-cli 0.4.0");
         return;
     }
     const handler = COMMANDS[command];

package/dist/sync.d.ts

@@ -0,0 +1,76 @@
+/** Server-enforced upload cap. Files larger than this are skipped. */
+export declare const MAX_SYNC_SIZE: number;
+/**
+ * File types Argus can ingest and analyze. Mirrors the server's ANALYZABLE_TYPES
+ * (JPEG/PNG/GIF/WebP/SVG). Anything else is skipped with an "unsupported type" reason.
+ */
+export declare const SYNCABLE_EXTENSIONS: Record<string, string>;
+export interface FileEntry {
+    path: string;
+    name: string;
+    size: number;
+}
+export interface HashedFile extends FileEntry {
+    /** sha256 of file contents; undefined for files that never reach the dedup stage. */
+    hash?: string;
+}
+export interface ExistingAsset {
+    filename: string;
+    size: number;
+}
+export interface SyncPlan {
+    include: HashedFile[];
+    skip: {
+        filename: string;
+        path: string;
+        reason: string;
+    }[];
+}
+export interface SyncResult {
+    synced: {
+        id: string;
+        filename: string;
+    }[];
+    skipped: {
+        filename: string;
+        reason: string;
+    }[];
+    failed: {
+        filename: string;
+        error: string;
+    }[];
+}
+export declare function formatBytes(bytes: number): string;
+export declare function kebabCase(input: string): string;
+/** Default project name = kebab-cased basename of the folder. */
+export declare function deriveProject(folder: string): string;
+export declare function mimeForFile(name: string): string | null;
+/**
+ * Cheap, hash-free skip checks: junk, hidden, unsupported type, oversize.
+ * Returns a human-readable reason, or null if the file passes and should be hashed.
+ */
+export declare function basicSkipReason(f: FileEntry): string | null;
+/**
+ * Recursively collect files under `dir`. Hidden directories (`.git`, etc.) are
+ * skipped entirely; hidden *files* are still returned so they can be reported as
+ * skipped-with-reason. Output is sorted by path for deterministic manifests.
+ */
+export declare function walk(dir: string): Promise<FileEntry[]>;
+/**
+ * Decide which files to upload vs skip.
+ *
+ * Skip reasons, in priority order:
+ *   1. junk / hidden / unsupported / oversize (see basicSkipReason)
+ *   2. an existing asset in the target project with the same filename + size
+ *   3. an earlier file in this run with identical contents (hash)
+ *
+ * `files` should carry a `hash` for every entry that passes basicSkipReason;
+ * entries without a hash simply never match the content-dedup check.
+ */
+export declare function buildPlan(files: HashedFile[], existing: ExistingAsset[]): SyncPlan;
+export interface ManifestMeta {
+    project: string;
+    dryRun: boolean;
+}
+export declare function toJsonManifest(result: SyncResult, meta: ManifestMeta): object;
+export declare function formatManifestText(result: SyncResult, meta: ManifestMeta): string;

package/dist/sync.js

@@ -0,0 +1,189 @@
+// Pure, testable logic for the `sync <folder>` command.
+// Kept separate from index.ts so the walk/filter/dedup/manifest behaviour can be
+// unit-tested without spinning up the CLI or hitting the network.
+import { readdir, stat } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+/** Server-enforced upload cap. Files larger than this are skipped. */
+export const MAX_SYNC_SIZE = 20 * 1024 * 1024; // 20 MB
+/**
+ * File types Argus can ingest and analyze. Mirrors the server's ANALYZABLE_TYPES
+ * (JPEG/PNG/GIF/WebP/SVG). Anything else is skipped with an "unsupported type" reason.
+ */
+export const SYNCABLE_EXTENSIONS = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+/** OS/editor cruft that should never be uploaded. */
+const JUNK_FILENAMES = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+// ─── Formatting ──────────────────────────────────────────────────────────────
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+// ─── Project derivation ────────────────────────────────────────────────────────
+export function kebabCase(input) {
+    return input
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2") // camelCase → camel-Case
+        .replace(/[\s_]+/g, "-")
+        .replace(/[^a-zA-Z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase();
+}
+/** Default project name = kebab-cased basename of the folder. */
+export function deriveProject(folder) {
+    const trimmed = folder.replace(/[/\\]+$/, "");
+    const base = basename(trimmed);
+    return kebabCase(base) || "imports";
+}
+// ─── Classification ────────────────────────────────────────────────────────────
+export function mimeForFile(name) {
+    const ext = extname(name).toLowerCase();
+    return SYNCABLE_EXTENSIONS[ext] ?? null;
+}
+/**
+ * Cheap, hash-free skip checks: junk, hidden, unsupported type, oversize.
+ * Returns a human-readable reason, or null if the file passes and should be hashed.
+ */
+export function basicSkipReason(f) {
+    if (JUNK_FILENAMES.has(f.name))
+        return "junk file";
+    if (f.name.startsWith("."))
+        return "hidden file";
+    const mime = mimeForFile(f.name);
+    if (!mime) {
+        const ext = extname(f.name).toLowerCase();
+        return `unsupported type (${ext || "no extension"})`;
+    }
+    if (f.size > MAX_SYNC_SIZE) {
+        return `exceeds 20 MB limit (${formatBytes(f.size)})`;
+    }
+    return null;
+}
+// ─── Walk ──────────────────────────────────────────────────────────────────────
+/**
+ * Recursively collect files under `dir`. Hidden directories (`.git`, etc.) are
+ * skipped entirely; hidden *files* are still returned so they can be reported as
+ * skipped-with-reason. Output is sorted by path for deterministic manifests.
+ */
+export async function walk(dir) {
+    const out = [];
+    async function recurse(current) {
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith("."))
+                    continue; // skip .git, .cache, etc.
+                await recurse(full);
+            }
+            else if (entry.isFile()) {
+                const s = await stat(full);
+                out.push({ path: full, name: entry.name, size: s.size });
+            }
+        }
+    }
+    await recurse(dir);
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+}
+// ─── Plan ────────────────────────────────────────────────────────────────────
+/**
+ * Decide which files to upload vs skip.
+ *
+ * Skip reasons, in priority order:
+ *   1. junk / hidden / unsupported / oversize (see basicSkipReason)
+ *   2. an existing asset in the target project with the same filename + size
+ *   3. an earlier file in this run with identical contents (hash)
+ *
+ * `files` should carry a `hash` for every entry that passes basicSkipReason;
+ * entries without a hash simply never match the content-dedup check.
+ */
+export function buildPlan(files, existing) {
+    const include = [];
+    const skip = [];
+    const existingKeys = new Set(existing.map((a) => `${a.filename}:${a.size}`));
+    const seenHashes = new Map(); // hash → first filename seen
+    for (const f of files) {
+        const basic = basicSkipReason(f);
+        if (basic) {
+            skip.push({ filename: f.name, path: f.path, reason: basic });
+            continue;
+        }
+        // Content dedup within the run. The first file with a given hash claims it,
+        // even if that first file is then skipped for another reason (e.g. already
+        // in the project) — a later identical-content file is still a duplicate.
+        if (f.hash && seenHashes.has(f.hash)) {
+            skip.push({
+                filename: f.name,
+                path: f.path,
+                reason: `duplicate of ${seenHashes.get(f.hash)}`,
+            });
+            continue;
+        }
+        if (f.hash)
+            seenHashes.set(f.hash, f.name);
+        if (existingKeys.has(`${f.name}:${f.size}`)) {
+            skip.push({
+                filename: f.name,
+                path: f.path,
+                reason: "already in project (same name + size)",
+            });
+            continue;
+        }
+        include.push(f);
+    }
+    return { include, skip };
+}
+export function toJsonManifest(result, meta) {
+    return {
+        project: meta.project,
+        dryRun: meta.dryRun,
+        summary: {
+            synced: result.synced.length,
+            skipped: result.skipped.length,
+            failed: result.failed.length,
+        },
+        synced: result.synced,
+        skipped: result.skipped,
+        failed: result.failed,
+    };
+}
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+export function formatManifestText(result, meta) {
+    const lines = [];
+    const header = meta.dryRun ? "Sync plan (dry run)" : "Sync complete";
+    lines.push(`${BOLD}${header}${RESET} — project ${BOLD}${meta.project}${RESET}\n`);
+    const syncedLabel = meta.dryRun ? "Would sync" : "Synced";
+    lines.push(`${GREEN}${syncedLabel}: ${result.synced.length}${RESET}`);
+    for (const s of result.synced) {
+        const id = s.id ? `${DIM}${s.id}${RESET}  ` : "";
+        lines.push(`  ${id}${s.filename}`);
+    }
+    if (result.skipped.length) {
+        lines.push(`\n${YELLOW}Skipped: ${result.skipped.length}${RESET}`);
+        for (const s of result.skipped) {
+            lines.push(`  ${s.filename} ${DIM}— ${s.reason}${RESET}`);
+        }
+    }
+    if (result.failed.length) {
+        lines.push(`\n${RED}Failed: ${result.failed.length}${RESET}`);
+        for (const f of result.failed) {
+            lines.push(`  ${f.filename} ${DIM}— ${f.error}${RESET}`);
+        }
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argus-media-cli",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "CLI for Argus — AI-native media asset management. Upload, search, analyze, and manage media assets from the terminal.",
   "keywords": [
     "argus",
@@ -29,12 +29,14 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.2"
   },
   "engines": {
     "node": ">=18"