upscale4k 0.0.0-stage → 0.1.0

package/dist/scan-videos.d.ts

@@ -0,0 +1,9 @@
+export interface Scan {
+    files: string[];
+    sourceRoot: string;
+    stateRoot: string;
+    outputFor: (file: string) => string;
+}
+export declare function assertUniqueOutputs(scan: Pick<Scan, "files" | "outputFor">): void;
+export declare function scanVideos(input: string, out?: string): Promise<Scan>;
+export declare function outputExists(source: string, output: string): Promise<boolean>;

package/dist/scan-videos.js

@@ -0,0 +1,77 @@
+/** Discover inputs and apply the desktop output naming and skip rules. */
+import { readdir, stat } from "node:fs/promises";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { ApiError } from "./api-client.js";
+const supportedSource = (name) => /\.(mp4|mov)$/i.test(name) && !/ 4k\.mp4$/i.test(name);
+const pathIdentity = (path) => process.platform === "win32" ? resolve(path).toLowerCase() : resolve(path);
+export function assertUniqueOutputs(scan) {
+    const owners = new Map();
+    for (const source of scan.files) {
+        const output = scan.outputFor(source), identity = JSON.stringify([pathIdentity(dirname(output)), basename(output).toLowerCase()]);
+        const previous = owners.get(identity);
+        if (previous !== undefined)
+            throw new ApiError("local_error", `Sources "${previous}" and "${source}" resolve to the same output path "${output}". Rename one source before retrying.`);
+        owners.set(identity, source);
+    }
+}
+export async function scanVideos(input, out) {
+    const source = resolve(input), info = await stat(source);
+    const sourceRoot = info.isDirectory() ? source : dirname(source);
+    const stateRoot = out ? resolve(out) : sourceRoot;
+    const files = [];
+    async function walk(path) {
+        for (const item of await readdir(path, { withFileTypes: true })) {
+            const child = join(path, item.name);
+            if (item.isDirectory()) {
+                if (out && resolve(child).toLowerCase() === stateRoot.toLowerCase())
+                    continue;
+                await walk(child);
+            }
+            else if (item.isFile() && supportedSource(item.name))
+                files.push(child);
+        }
+    }
+    if (info.isDirectory())
+        await walk(source);
+    else if (info.isFile() && /\.(mp4|mov)$/i.test(source))
+        files.push(source);
+    else
+        throw new Error("Input must be an MP4/MOV file or directory.");
+    files.sort();
+    // A single-file request still accounts for its supported siblings so its
+    // output name agrees with a folder scan, including previously finished jobs.
+    const siblings = info.isDirectory() ? files : (await readdir(sourceRoot, { withFileTypes: true }))
+        .filter((item) => item.isFile() && supportedSource(item.name)).map((item) => join(sourceRoot, item.name));
+    const containsSource = siblings.some((file) => pathIdentity(file) === pathIdentity(source));
+    if (!info.isDirectory() && !containsSource)
+        siblings.push(source);
+    const folderFor = (file) => out
+        ? join(stateRoot, ...(info.isDirectory() ? [basename(sourceRoot)] : []), dirname(relative(sourceRoot, file))) : dirname(file);
+    const groupFor = (file) => JSON.stringify([pathIdentity(folderFor(file)), basename(file, extname(file)).toLowerCase()]);
+    const groups = new Map();
+    for (const file of siblings)
+        groups.set(groupFor(file), (groups.get(groupFor(file)) ?? 0) + 1);
+    const outputFor = (file) => {
+        const extension = extname(file), stem = basename(file, extension);
+        const suffix = (groups.get(groupFor(file)) ?? 0) > 1 ? ` (${extension.slice(1).toLowerCase()})` : "";
+        return join(folderFor(file), `${stem}${suffix} 4K.mp4`);
+    };
+    assertUniqueOutputs({ files: siblings, outputFor });
+    return { files, sourceRoot, stateRoot, outputFor };
+}
+export async function outputExists(source, output) {
+    const stem = basename(source, extname(source)).toLowerCase();
+    const colocated = pathIdentity(dirname(output)) === pathIdentity(dirname(source));
+    const computedName = basename(output).toLowerCase();
+    const allowAlternates = !colocated && computedName === `${stem} 4k.mp4`;
+    const names = new Set(allowAlternates ? [computedName, `${stem}.mp4`, `${stem}.mov`] : [computedName]);
+    try {
+        return (await readdir(dirname(output), { withFileTypes: true })).some((entry) => entry.isFile() && names.has(entry.name.toLowerCase()) &&
+            pathIdentity(join(dirname(output), entry.name)) !== pathIdentity(source));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}

package/dist/state-lock.d.ts

@@ -0,0 +1,9 @@
+export interface LockOptions {
+    waitMs?: number;
+    staleMs?: number;
+    refreshMs?: number;
+    maxLeaseMs?: number;
+    signal?: AbortSignal;
+}
+export declare function acquireStateLock(path: string, options?: LockOptions): Promise<() => Promise<void>>;
+export declare function withStateLock<T>(path: string, operation: () => Promise<T>, options?: LockOptions): Promise<T>;

package/dist/state-lock.js

@@ -0,0 +1,151 @@
+/** Filesystem leases shared by CLI processes and MCP calls. */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rmdir, stat, unlink, utimes, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { ApiError, sleep, throwIfCancelled } from "./api-client.js";
+const code = (error) => error.code;
+const transient = (error) => ["EPERM", "EACCES", "EBUSY"].includes(code(error) ?? "");
+async function removeEmpty(path) {
+    try {
+        await rmdir(path);
+        return true;
+    }
+    catch (error) {
+        if (code(error) === "ENOENT")
+            return true;
+        if (transient(error) || ["ENOTEMPTY", "EEXIST"].includes(code(error) ?? ""))
+            return false;
+        throw error;
+    }
+}
+function validOwner(value) {
+    const owner = value;
+    return !!owner && Number.isSafeInteger(owner.pid) && owner.pid > 0 &&
+        typeof owner.hostname === "string" && owner.hostname.length > 0 && Number.isFinite(owner.timestamp) && owner.timestamp > 0;
+}
+async function ownerMtime(ownerPath, path) {
+    try {
+        return (await stat(ownerPath)).mtimeMs;
+    }
+    catch {
+        return (await stat(path)).mtimeMs;
+    }
+}
+async function recover(path, staleMs) {
+    try {
+        const names = await readdir(path);
+        if (!names.length)
+            return removeEmpty(path);
+        if (names.length !== 1)
+            return false;
+        const ownerPath = join(path, names[0]);
+        let owner;
+        try {
+            owner = JSON.parse(await readFile(ownerPath, "utf8"));
+        }
+        catch (error) {
+            if (code(error) === "ENOENT")
+                return true;
+        }
+        let dead = false;
+        if (validOwner(owner) && owner.hostname === hostname()) {
+            try {
+                process.kill(owner.pid, 0);
+            }
+            catch (error) {
+                dead = code(error) === "ESRCH";
+            }
+        }
+        // Age also covers hung processes, PID reuse, permission-denied probes and corrupt metadata.
+        // Recheck the heartbeat after reading/probing so a refreshed lease is preserved.
+        if (!dead && Date.now() - await ownerMtime(ownerPath, path) < staleMs)
+            return false;
+        // Remove only this owner's unique file. A delayed reaper cannot unlink a successor.
+        await unlink(ownerPath);
+        return removeEmpty(path);
+    }
+    catch (error) {
+        if (code(error) === "ENOENT")
+            return true;
+        if (transient(error))
+            return false;
+        throw error;
+    }
+}
+export async function acquireStateLock(path, options = {}) {
+    throwIfCancelled(options.signal);
+    const waitMs = options.waitMs ?? 60_000, staleMs = options.staleMs ?? 120_000;
+    const started = performance.now();
+    await mkdir(dirname(path), { recursive: true });
+    const token = randomUUID(), candidate = `${path}.${token}.tmp`, name = `${token}.json`;
+    await mkdir(candidate);
+    let acquired = false;
+    try {
+        await writeFile(join(candidate, name), JSON.stringify({ pid: process.pid, hostname: hostname(), timestamp: Date.now() }), { flag: "wx", mode: 0o600 });
+        for (let attempt = 0;; attempt++) {
+            throwIfCancelled(options.signal);
+            try {
+                // Publish a nonempty directory atomically: rename cannot replace another owner.
+                // Unique children also make stale removal safe without a check/unlink race.
+                await rename(candidate, path);
+                acquired = true;
+                break;
+            }
+            catch (error) {
+                if (!transient(error) && !["EEXIST", "ENOTEMPTY"].includes(code(error) ?? ""))
+                    throw error;
+                if (await recover(path, staleMs)) {
+                    // Even a nonwaiting caller must be able to claim a recovered lease.
+                    try {
+                        await rename(candidate, path);
+                        acquired = true;
+                        break;
+                    }
+                    catch (retryError) {
+                        if (!transient(retryError) && !["EEXIST", "ENOTEMPTY"].includes(code(retryError) ?? ""))
+                            throw retryError;
+                    }
+                }
+            }
+            const remaining = waitMs - (performance.now() - started);
+            if (remaining <= 0)
+                throw new ApiError("state_locked", `State is locked by another run (${path}). Wait for it to finish, then rerun.`);
+            await sleep(Math.min(remaining, 20 * 2 ** Math.min(attempt, 4)), options.signal);
+        }
+    }
+    finally {
+        if (!acquired) {
+            await unlink(join(candidate, name)).catch((error) => { if (code(error) !== "ENOENT")
+                throw error; });
+            await removeEmpty(candidate);
+        }
+    }
+    const ownerPath = join(path, name);
+    const acquiredAt = performance.now(), maxLeaseMs = options.maxLeaseMs ?? 6 * 60 * 60 * 1000;
+    const refresh = options.refreshMs ? setInterval(() => {
+        if (performance.now() - acquiredAt >= maxLeaseMs) {
+            clearInterval(refresh);
+            return;
+        }
+        const now = new Date();
+        void utimes(ownerPath, now, now).catch(() => { });
+    }, options.refreshMs) : undefined;
+    refresh?.unref();
+    return async () => {
+        clearInterval(refresh);
+        await unlink(ownerPath).catch((error) => { if (code(error) !== "ENOENT")
+            throw error; });
+        await removeEmpty(path);
+    };
+}
+export async function withStateLock(path, operation, options) {
+    const release = await acquireStateLock(path, options);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}

package/dist/terminal-prompts.d.ts

@@ -0,0 +1,2 @@
+export declare function ask(question: string, hidden?: boolean): Promise<string>;
+export declare function agree(statement: string): Promise<void>;

package/dist/terminal-prompts.js

@@ -0,0 +1,23 @@
+/** Terminal prompts with credential echo suppressed for login. */
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+export async function ask(question, hidden = false) {
+    if (!process.stdin.isTTY)
+        throw new Error("Interactive input requires a terminal. For likeness consent, obtain the user's agreement before supplying --yes-self-likeness-consent.");
+    process.stderr.write(question);
+    const sink = hidden ? new Writable({ write(_chunk, _encoding, done) { done(); } }) : process.stderr;
+    const reader = createInterface({ input: process.stdin, output: sink, terminal: true });
+    try {
+        return (await reader.question("")).trim();
+    }
+    finally {
+        reader.close();
+        if (hidden)
+            process.stderr.write("\n");
+    }
+}
+export async function agree(statement) {
+    process.stderr.write(`${statement}\n`);
+    if (!/^(y|yes)$/i.test(await ask("Agree? (y/N) ")))
+        throw new Error("Consent declined; nothing submitted.");
+}

package/dist/upscale-runner.d.ts

@@ -0,0 +1,22 @@
+import { ApiClient } from "./api-client.js";
+import { type Account } from "./api-contract.js";
+import { type Scan } from "./scan-videos.js";
+import { type Emit, type FileResult } from "./run-file.js";
+export type { RunEvent, FileResult } from "./run-file.js";
+export interface UpscaleOptions {
+    path: string;
+    selfLikeness: boolean;
+    selfLikenessConsent?: boolean;
+    outputDir?: string;
+    concurrency?: number;
+    wait?: boolean;
+    pollMs?: number;
+    onEvent?: Emit;
+    signal?: AbortSignal;
+    scan?: Scan;
+}
+export interface RunResult {
+    results: FileResult[];
+    stopped?: string;
+}
+export declare function upscale(client: ApiClient, account: Account, options: UpscaleOptions): Promise<RunResult>;

package/dist/upscale-runner.js

@@ -0,0 +1,113 @@
+/** Coordinate admission, bounded file workers, durable resume and event reporting. */
+import { stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { ApiError, throwIfCancelled } from "./api-client.js";
+import { MAX_LONG_SIDE, MIN_LONG_SIDE, MAX_UPLOAD_BYTES } from "./api-contract.js";
+import { probeVideo } from "./probe-video.js";
+import { ResumeState } from "./resume-state.js";
+import { assertUniqueOutputs, outputExists, scanVideos } from "./scan-videos.js";
+import { runFile } from "./run-file.js";
+const stopCodes = new Set(["no_credits", "daily_limit", "api_locked", "consent_outdated", "state_locked", "upgrade_required"]);
+const actions = {
+    no_credits: "Add credits to your Upscale4K account, then rerun to resume.",
+    daily_limit: "Daily limit reached. Wait for the next daily allowance, then rerun.",
+    api_locked: "Unlock API access in your Upscale4K account before resuming.",
+    consent_outdated: "The server rejected the saved consent. Inspect the job and server response before resuming.",
+    state_locked: "Another run holds this state directory. Let it finish, then rerun to resume.",
+    upgrade_required: "This upscale4k version is no longer supported. Rerun with npx -y upscale4k@latest to resume.",
+};
+export async function upscale(client, account, options) {
+    throwIfCancelled(options.signal);
+    if (typeof options.selfLikeness !== "boolean")
+        throw new ApiError("validation_error", "self_likeness must be explicitly supplied; ask the user, never guess.");
+    if (options.selfLikeness && options.selfLikenessConsent !== true)
+        throw new ApiError("consent_required", account.consent.self_likeness_statement);
+    const concurrency = options.concurrency ?? 3;
+    if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 100)
+        throw new ApiError("validation_error", "Concurrency must be an integer from 1 to 100.");
+    const emit = options.onEvent ?? (() => { });
+    const scan = options.scan ?? await scanVideos(options.path, options.outputDir);
+    assertUniqueOutputs(scan);
+    const store = new ResumeState(join(scan.stateRoot, ".upscale4k-state.json"), { signal: options.signal });
+    await emit({ event: "scan", count: scan.files.length, path: options.path });
+    // Snapshot existing results before any paid work begins.
+    const existingOutputs = new Map(await Promise.all(scan.files.map(async (source) => [source, await outputExists(source, scan.outputFor(source))])));
+    const results = [];
+    let index = 0, stopped;
+    async function worker() {
+        while (!stopped && !options.signal?.aborted && index < scan.files.length) {
+            const source = scan.files[index++], output = scan.outputFor(source);
+            try {
+                let reason, message;
+                const info = await stat(source);
+                if (existingOutputs.get(source))
+                    reason = "output_exists";
+                else if (info.size <= 0)
+                    reason = "size_limit";
+                let body;
+                if (!reason) {
+                    const video = await probeVideo(source);
+                    const long = account.long_video, isLong = video.duration > account.max_seconds;
+                    // Long clips need an eligible account and upload in parts, so they get the larger long-video size cap.
+                    const longOk = isLong && long?.eligible === true && video.duration <= (long.max_seconds["runway-4k"] ?? 0);
+                    if (isLong && !longOk) {
+                        reason = "duration_limit";
+                        message = !long?.eligible
+                            ? `Long videos (over this account's max_seconds of ${account.max_seconds} seconds) are not yet available through the Upscale4K API for this account.`
+                            : `Video exceeds this account's long-video limit of ${long.max_seconds["runway-4k"] ?? 0} seconds.`;
+                    }
+                    else if (info.size > (isLong ? long.max_upload_bytes : MAX_UPLOAD_BYTES))
+                        reason = "size_limit";
+                    else if (Math.max(video.width, video.height) > MAX_LONG_SIDE || Math.max(video.width, video.height) < MIN_LONG_SIDE)
+                        reason = "resolution_limit";
+                    body = { filename: basename(source), size: info.size, ...video, consent: {
+                            selfLikeness: options.selfLikeness,
+                            ...(options.selfLikenessConsent ? { selfLikenessConsent: true } : {}),
+                        } };
+                }
+                if (reason) {
+                    results.push({ source, output_path: output, state: "skipped", ...(message ? { reason, message } : {}) });
+                    await emit({ event: "skipped", source, reason, ...(message ? { message } : {}) });
+                    continue;
+                }
+                throwIfCancelled(options.signal);
+                if (stopped)
+                    break;
+                const acquired = await store.withSource(source, async () => {
+                    throwIfCancelled(options.signal);
+                    if (stopped)
+                        return;
+                    const entry = await store.prepare(source, info.size, info.mtimeMs, output, body, undefined, client.keyPrefix);
+                    throwIfCancelled(options.signal);
+                    if (stopped)
+                        return;
+                    results.push(await runFile(client, store, entry, output, options.wait ?? true, emit, options.pollMs ?? 2000, body, options.signal));
+                });
+                if (!acquired) {
+                    results.push({ source, state: "skipped", reason: "in_progress_elsewhere" });
+                    await emit({ event: "skipped", source, reason: "in_progress_elsewhere" });
+                }
+            }
+            catch (error) {
+                const code = error instanceof ApiError ? error.code : "local_error";
+                const message = error instanceof Error ? error.message : "Upscale failed";
+                if (code === "cancelled")
+                    stopped = "cancelled: Rerun the same command to resume.";
+                if (stopCodes.has(code))
+                    stopped = `${code}: ${actions[code]}`;
+                results.push({ source, state: "failed", error: `${code}: ${message}` });
+                await emit({ event: "failed", source, code, message, ...(stopped ? { action: stopped } : {}) });
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, scan.files.length) }, worker));
+    if (options.signal?.aborted && !stopped) {
+        stopped = "cancelled: Rerun the same command to resume.";
+        await emit({ event: "failed", code: "cancelled", message: "Upscale cancelled; rerun the same command to resume." });
+    }
+    await emit({ event: "summary", scanned: scan.files.length, processed: results.length,
+        done: results.filter((r) => r.state === "done").length, skipped: results.filter((r) => r.state === "skipped").length,
+        failed: results.filter((r) => r.state === "failed").length, stopped });
+    throwIfCancelled(options.signal);
+    return { results, stopped };
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "upscale4k",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Upscale short videos to 4K with Upscale4K from the terminal or any MCP-capable AI agent.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "upscale4k": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^4.1.12"
+  }
+}