pixelforge-uploader 2.0.0 → 2.1.0

package/README.md

@@ -22,22 +22,36 @@ Needs [Node.js](https://nodejs.org) 18+ (one-time install). Then, in a terminal:
 npx pixelforge-uploader
 ```
 
-The first time, it asks for your Open Cloud API key and creator id, then prints
-"PixelForge Uploader is running". Leave it open while you upload; close the
-window when you're done. Same command on Windows and macOS.
+The first time, it walks you through a short setup (your API key and where to
+upload), then shows a small status screen. Leave it open while you upload; close
+the window when you're done. Same command on Windows and macOS.
 
 ## First-run setup
 
-It asks for:
+A guided wizard asks for:
 
 - **API key** - an Open Cloud key with the `asset:write` scope. Create one at
   https://create.roblox.com/dashboard/credentials (add the "asset" API, check
   `asset:write`, set IP Address to `0.0.0.0/0`).
 - **Creator** - upload to your account (user) or a group, and the numeric id.
 
-These are saved to `~/.pixelforge-uploader/config.json` (permissions 600). To
-change them later run `npx pixelforge-uploader reconfigure`, or set the env vars
-`PIXELFORGE_API_KEY`, `PIXELFORGE_CREATOR_TYPE`, `PIXELFORGE_CREATOR_ID`.
+These are saved to `~/.pixelforge-uploader/config.json` (permissions 600).
+
+## The status screen
+
+While it's running it shows whether it's connected, where icons upload, and your
+recent uploads. Press a key any time to change things, no restart needed:
+
+- `k` - change your API key
+- `c` - switch between your account and a group
+- `t` - test your API key (a quick check that doesn't upload anything)
+- `o` - open the settings folder
+- `r` - redo the whole setup
+- `q` - quit
+
+You can also re-run setup with `npx pixelforge-uploader reconfigure`, or set the
+env vars `PIXELFORGE_API_KEY`, `PIXELFORGE_CREATOR_TYPE`, `PIXELFORGE_CREATOR_ID`
+(handy for scripts; this skips the status screen).
 
 ## Use it
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelforge-uploader",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Local helper that uploads PixelForge icons to Roblox via Open Cloud. The Studio plugin sends raw pixels over localhost; this app holds the API key, encodes the PNG, and uploads.",
   "license": "MIT",
   "engines": { "node": ">=18" },

package/src.js

@@ -10,14 +10,18 @@
 // user's own machine. The plugin itself stores no key and references no Roblox
 // API - it only POSTs raw pixels to localhost.
 //
-// Zero dependencies: plain Node http/https/zlib.
+// Zero dependencies: plain Node http/https/zlib (+ readline/child_process for
+// the friendly terminal UI). The UI is hand-rolled ANSI so there's nothing to
+// npm-install: `npx pixelforge-uploader` just runs.
 //
 // Config (API key + creator) is collected once, interactively, and saved to
 //   ~/.pixelforge-uploader/config.json
 // (override with env PIXELFORGE_API_KEY / PIXELFORGE_CREATOR_TYPE /
-// PIXELFORGE_CREATOR_ID; re-run setup with `node src.js reconfigure`).
+// PIXELFORGE_CREATOR_ID; re-run setup with `node src.js reconfigure`). When
+// running in a real terminal it shows a live dashboard with single-key commands
+// to change the key, switch creator, test the key, etc. without restarting.
 //
-// Transport from the plugin:
+// Transport from the plugin (UNCHANGED - the plugin depends on this exactly):
 //   POST http://127.0.0.1:<PORT>/upload
 //     headers: x-pf-width, x-pf-height, x-pf-name (plain text)
 //     body:    raw RGBA bytes (width*height*4)
@@ -41,6 +45,58 @@ const ASSETS_URL = "https://apis.roblox.com/assets/v1/assets";
 const OPERATION_URL = "https://apis.roblox.com/assets/v1/operations/";
 const POLL_INTERVAL_MS = 1500;
 const POLL_MAX_ATTEMPTS = 30;
+const CREDENTIALS_URL = "https://create.roblox.com/dashboard/credentials";
+
+// ---------- terminal styling (zero-dep ANSI) ----------
+
+// Only style when we're attached to a real terminal, and honour NO_COLOR.
+const useColor = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const C = {
+	reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+	green: "\x1b[32m", red: "\x1b[31m", yellow: "\x1b[33m",
+	cyan: "\x1b[36m", gray: "\x1b[90m", orange: "\x1b[38;5;214m",
+};
+const CLEAR = "\x1b[2J\x1b[3J\x1b[H"; // clear screen + scrollback + home
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+
+const paint = (code, s) => (useColor ? code + s + C.reset : String(s));
+const col = (name, s) => paint(C[name] || "", s);
+const bold = (s) => paint(C.bold, s);
+const stripAnsi = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, "");
+
+function termWidth() {
+	return Math.max(44, Math.min((process.stdout.columns || 60) - 2, 66));
+}
+
+function maskKey(k) {
+	if (!k) return "(none yet)";
+	const s = String(k);
+	return s.length <= 4 ? "••••" : "••••••••" + s.slice(-4);
+}
+
+function creatorPhrase(cfg) {
+	if (!cfg) return "(not set)";
+	return (cfg.creatorType === "group" ? "group " : "your account ") + cfg.creatorId;
+}
+
+// ---------- runtime state ----------
+
+let cfg = null;            // current config (may be swapped live from the menu)
+let server = null;
+let interactive = false;   // true only when both stdin and stdout are a TTY
+let uiMode = "plain";      // "plain" | "menu" | "busy" | "prompt"
+let uploadCount = 0;
+const logLines = [];       // recent activity shown in the dashboard
+
+function log(msg) {
+	const ts = new Date().toTimeString().slice(0, 5);
+	logLines.push(col("gray", ts) + "  " + msg);
+	while (logLines.length > 8) logLines.shift();
+	if (uiMode === "menu" || uiMode === "busy") renderDashboard();
+	else if (!interactive) console.log(stripAnsi(ts + "  " + msg));
+	// uiMode === "prompt": hold off, the prompt owns the screen; it renders after.
+}
 
 // ---------- config ----------
 
@@ -62,28 +118,255 @@ function loadConfig() {
 	return null;
 }
 
-function saveConfig(cfg) {
+function saveConfig(c) {
 	fs.mkdirSync(CONFIG_DIR, { recursive: true });
-	fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+	fs.writeFileSync(CONFIG_FILE, JSON.stringify(c, null, 2), { mode: 0o600 });
+}
+
+// ---------- the dashboard ----------
+
+function renderDashboard() {
+	if (!interactive) return;
+	const W = termWidth();
+	const rule = col("gray", "─".repeat(W));
+	const row = (label, value) => "  " + col("gray", label.padEnd(11)) + value;
+	const key = (k, label) => "    " + col("orange", k) + col("gray", "  ") + label;
+
+	const out = [CLEAR + HIDE_CURSOR, ""];
+	out.push("  " + col("orange", "◆ ") + bold("PixelForge Uploader"));
+	out.push("  " + rule);
+	out.push("");
+	out.push(row("Status", col("green", "● running")));
+	out.push(row("Address", col("cyan", "http://localhost:" + PORT)));
+	out.push(row("Upload to", creatorPhrase(cfg)));
+	out.push(row("API key", col("gray", maskKey(cfg && cfg.apiKey))));
+	out.push(row("Uploads", uploadCount + " this session"));
+	out.push("");
+	out.push("  " + rule);
+	out.push("  " + bold("What now?") + col("gray", "   (press a key)"));
+	out.push(key("k", "Change API key"));
+	out.push(key("c", "Change account / group"));
+	out.push(key("t", "Test my API key"));
+	out.push(key("o", "Open settings folder"));
+	out.push(key("r", "Redo setup"));
+	out.push(key("q", "Quit"));
+	out.push("  " + rule);
+	if (logLines.length) {
+		out.push("  " + bold("Recent"));
+		for (const l of logLines) out.push("    " + l);
+	} else {
+		out.push("  " + col("gray", "Waiting for icons from Studio. Leave this window open."));
+	}
+	out.push("");
+	process.stdout.write(out.join("\n") + "\n");
 }
 
-function ask(rl, q) {
-	return new Promise((res) => rl.question(q, (a) => res(a.trim())));
+// ---------- interactive prompts (shared by setup + the live menu) ----------
+
+// Reads a line of input. Loops on bad input; Enter on its own returns null so
+// callers can treat empty as "cancel / keep current".
+async function askApiKey(ask) {
+	while (true) {
+		const v = await ask("  Paste your API key (or press Enter to cancel): ");
+		if (!v) return null;
+		if (v.length < 10) { console.log("  " + col("yellow", "That looks too short. Paste the whole key.")); continue; }
+		return v;
+	}
 }
 
+async function askCreator(ask) {
+	const t = await ask("  Upload to (1) your account or (2) a group? [1/2]: ");
+	if (t === "") return null;
+	const creatorType = t === "2" ? "group" : "user";
+	while (true) {
+		const id = await ask("  Enter the " + (creatorType === "group" ? "group" : "account") + " id (numbers only): ");
+		if (!id) return null;
+		if (/^\d+$/.test(id)) return { creatorType, creatorId: id };
+		console.log("  " + col("yellow", "Please enter digits only (the numeric id)."));
+	}
+}
+
+// Runs `fn` with a line-reading prompt while the dashboard is paused. Restores
+// the dashboard (and raw key handling) afterwards no matter what.
+async function lineSession(fn) {
+	uiMode = "prompt";
+	if (interactive) { try { process.stdin.setRawMode(false); } catch (_) {} }
+	process.stdout.write(SHOW_CURSOR);
+	const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+	const ask = (q) => new Promise((r) => rl.question(q, (a) => r(a.trim())));
+	try {
+		return await fn(ask);
+	} finally {
+		rl.close();
+		if (interactive) {
+			try { process.stdin.setRawMode(true); } catch (_) {}
+			process.stdin.resume();
+		}
+		uiMode = "menu";
+		renderDashboard();
+	}
+}
+
+// ---------- first-run setup wizard ----------
+
 async function runSetup() {
+	if (interactive) process.stdout.write(CLEAR + SHOW_CURSOR);
+	const W = termWidth();
+	process.stdout.write("\n");
+	process.stdout.write("  " + col("orange", "◆ ") + bold("Welcome to the PixelForge Uploader") + "\n");
+	process.stdout.write("  " + col("gray", "─".repeat(W)) + "\n\n");
+	process.stdout.write("  This little app sends the icons you capture in Studio up to Roblox.\n");
+	process.stdout.write("  Let's set it up once. It takes about a minute.\n\n");
+	process.stdout.write("  " + bold("1.") + " Create an Open Cloud API key here:\n");
+	process.stdout.write("     " + col("cyan", CREDENTIALS_URL) + "\n");
+	process.stdout.write("     " + col("gray", 'Add the "Assets" API, tick asset:write, set IP to 0.0.0.0/0.') + "\n\n");
+
 	const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-	console.log("\nPixelForge Uploader - first-time setup\n");
-	console.log("Create an Open Cloud API key at https://create.roblox.com/dashboard/credentials");
-	console.log("(add the \"asset\" API, check asset:write, set IP 0.0.0.0/0).\n");
-	const apiKey = await ask(rl, "Paste your API key: ");
-	let creatorType = (await ask(rl, "Upload to (1) your account or (2) a group? [1/2]: ")) === "2" ? "group" : "user";
-	const creatorId = await ask(rl, `Enter your ${creatorType === "group" ? "group" : "user"} id (number): `);
+	const ask = (q) => new Promise((r) => rl.question(q, (a) => r(a.trim())));
+
+	let key;
+	while (true) {
+		key = await askApiKey(ask);
+		if (key) break;
+		process.stdout.write("  " + col("gray", "(An API key is needed to upload.)") + "\n");
+	}
+
+	process.stdout.write("\n  " + bold("2.") + " Where should your icons be uploaded?\n");
+	let cr;
+	while (true) {
+		cr = await askCreator(ask);
+		if (cr) break;
+		process.stdout.write("  " + col("gray", "(Pick 1 or 2, then enter the numeric id.)") + "\n");
+	}
+
+	process.stdout.write("\n  " + bold("Does this look right?") + "\n");
+	process.stdout.write("    API key    " + col("gray", maskKey(key)) + "\n");
+	process.stdout.write("    Upload to  " + (cr.creatorType === "group" ? "group " : "your account ") + cr.creatorId + "\n\n");
+	const ok = (await ask("  Save and start? [Y/n]: ")).toLowerCase();
 	rl.close();
-	const cfg = { apiKey, creatorType, creatorId };
-	saveConfig(cfg);
-	console.log(`\nSaved to ${CONFIG_FILE}\n`);
-	return cfg;
+
+	if (ok === "n" || ok === "no") {
+		process.stdout.write("\n  " + col("gray", "No problem, let's go again.") + "\n");
+		return runSetup();
+	}
+
+	const next = { apiKey: key, creatorType: cr.creatorType, creatorId: cr.creatorId };
+	saveConfig(next);
+	process.stdout.write("\n  " + col("green", "✓ Saved.") + " " + col("gray", "(" + CONFIG_FILE + ")") + "\n");
+	return next;
+}
+
+// ---------- live menu actions ----------
+
+function changeApiKey() {
+	return lineSession(async (ask) => {
+		process.stdout.write("\n  " + bold("Change API key") + "\n");
+		process.stdout.write("  " + col("gray", "Create one at " + CREDENTIALS_URL + " (asset:write).") + "\n");
+		const key = await askApiKey(ask);
+		if (!key) { log(col("yellow", "Cancelled. API key unchanged.")); return; }
+		cfg = Object.assign({}, cfg, { apiKey: key });
+		saveConfig(cfg);
+		log(col("green", "✓ API key updated."));
+	});
+}
+
+function changeCreator() {
+	return lineSession(async (ask) => {
+		process.stdout.write("\n  " + bold("Change where icons upload") + "\n");
+		const cr = await askCreator(ask);
+		if (!cr) { log(col("yellow", "Cancelled. Creator unchanged.")); return; }
+		cfg = Object.assign({}, cfg, cr);
+		saveConfig(cfg);
+		log(col("green", "✓ Now uploading to " + creatorPhrase(cfg) + "."));
+	});
+}
+
+function redoSetup() {
+	return lineSession(async (ask) => {
+		process.stdout.write("\n  " + bold("Redo setup") + "\n");
+		const key = await askApiKey(ask);
+		if (!key) { log(col("yellow", "Cancelled. Nothing changed.")); return; }
+		const cr = await askCreator(ask);
+		if (!cr) { log(col("yellow", "Cancelled. Nothing changed.")); return; }
+		cfg = { apiKey: key, creatorType: cr.creatorType, creatorId: cr.creatorId };
+		saveConfig(cfg);
+		log(col("green", "✓ Setup saved. Uploading to " + creatorPhrase(cfg) + "."));
+	});
+}
+
+function openConfigFolder() {
+	try { fs.mkdirSync(CONFIG_DIR, { recursive: true }); } catch (_) {}
+	const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+	try {
+		require("child_process").spawn(opener, [CONFIG_DIR], { detached: true, stdio: "ignore" }).unref();
+		log(col("green", "✓ Opened ") + col("gray", CONFIG_DIR));
+	} catch (_) {
+		log(col("yellow", "Settings are in ") + col("gray", CONFIG_DIR));
+	}
+}
+
+// Non-destructive key check: Open Cloud authenticates before it validates the
+// request body, so a junk request reveals whether the key is accepted without
+// ever creating an asset. 401/403 => bad key; anything else => key recognised.
+async function testKey() {
+	uiMode = "busy";
+	log(col("cyan", "→ Checking your API key with Roblox..."));
+	try {
+		const resp = await robloxRequest("POST", ASSETS_URL, {
+			"x-api-key": cfg.apiKey,
+			"Content-Type": "application/json",
+			"Content-Length": 2,
+		}, Buffer.from("{}"));
+		if (resp.status === 401 || resp.status === 403) {
+			log(col("red", "✗ Roblox rejected the key (HTTP " + resp.status + "). Check asset:write and the IP setting."));
+		} else {
+			log(col("green", "✓ Roblox accepted your key. You're ready to upload."));
+		}
+	} catch (e) {
+		log(col("red", "✗ Couldn't reach Roblox: " + (e && e.message ? e.message : e)));
+	} finally {
+		uiMode = "menu";
+		renderDashboard();
+	}
+}
+
+function quit() {
+	if (interactive) {
+		try { process.stdin.setRawMode(false); } catch (_) {}
+		process.stdout.write(SHOW_CURSOR + C.reset);
+	}
+	process.stdout.write("\n");
+	console.log("  " + col("orange", "PixelForge Uploader closed.") + " See you next time.\n");
+	if (server) { try { server.close(); } catch (_) {} }
+	process.exit(0);
+}
+
+function handleMenuKey(name) {
+	if (name === "q") return quit();
+	if (name === "k") return changeApiKey();
+	if (name === "c") return changeCreator();
+	if (name === "t") return testKey();
+	if (name === "o") return openConfigFolder();
+	if (name === "r") return redoSetup();
+	// anything else: ignore
+}
+
+function onKeypress(str, key) {
+	if (key && key.ctrl && key.name === "c") return quit();
+	if (uiMode !== "menu") return;
+	const name = (key && key.name) || str;
+	if (typeof name === "string") handleMenuKey(name.toLowerCase());
+}
+
+function attachMenu() {
+	if (!interactive) return;
+	readline.emitKeypressEvents(process.stdin);
+	try { process.stdin.setRawMode(true); } catch (_) {}
+	process.stdin.resume();
+	process.stdin.on("keypress", onKeypress);
+	uiMode = "menu";
+	// The first paint comes from the server's listen callback once the port is
+	// actually bound, so the dashboard never claims "running" prematurely.
 }
 
 // ---------- PNG encode (raw RGBA -> PNG, zlib) ----------
@@ -155,8 +438,8 @@ function robloxRequest(method, url, headers, bodyBuffer) {
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-async function uploadImage(cfg, name, pngBuffer) {
-	const creator = cfg.creatorType === "group" ? { groupId: Number(cfg.creatorId) } : { userId: Number(cfg.creatorId) };
+async function uploadImage(c, name, pngBuffer) {
+	const creator = c.creatorType === "group" ? { groupId: Number(c.creatorId) } : { userId: Number(c.creatorId) };
 	const meta = JSON.stringify({ assetType: "Image", displayName: name || "Icon", description: "Created with PixelForge", creationContext: { creator } });
 	const boundary = "----PixelForgeUploader" + Date.now().toString(16);
 	const CRLF = "\r\n";
@@ -166,7 +449,7 @@ async function uploadImage(cfg, name, pngBuffer) {
 	const body = Buffer.concat([pre, pngBuffer, Buffer.from(`${CRLF}--${boundary}--${CRLF}`, "utf8")]);
 
 	const post = await robloxRequest("POST", ASSETS_URL, {
-		"x-api-key": cfg.apiKey,
+		"x-api-key": c.apiKey,
 		"Content-Type": "multipart/form-data; boundary=" + boundary,
 		"Content-Length": body.length,
 	}, body);
@@ -190,7 +473,7 @@ async function uploadImage(cfg, name, pngBuffer) {
 	if (!opId) throw new Error("Upload accepted but no operation id returned.");
 	for (let i = 0; i < POLL_MAX_ATTEMPTS; i++) {
 		await sleep(POLL_INTERVAL_MS);
-		const poll = await robloxRequest("GET", OPERATION_URL + opId[1], { "x-api-key": cfg.apiKey });
+		const poll = await robloxRequest("GET", OPERATION_URL + opId[1], { "x-api-key": c.apiKey });
 		if (poll.status === 200 && poll.json) {
 			id = readId(poll.json);
 			if (id) return id;
@@ -216,58 +499,80 @@ function json(res, status, obj) {
 	res.end(b);
 }
 
-function startServer(cfg) {
-	const server = http.createServer(async (req, res) => {
+function startServer() {
+	server = http.createServer(async (req, res) => {
 		if (req.method === "GET" && req.url === "/ping") {
-			return json(res, 200, { ok: true, app: "PixelForge Uploader", version: "2", configured: !!cfg });
+			return json(res, 200, { ok: true, app: "PixelForge Uploader", version: "3", configured: !!cfg });
 		}
 		if (req.method === "POST" && req.url.startsWith("/upload")) {
+			const name = req.headers["x-pf-name"] || "Icon";
 			try {
 				if (!cfg) return json(res, 400, { error: "Uploader not configured. Restart it and complete setup." });
 				const width = Number(req.headers["x-pf-width"]);
 				const height = Number(req.headers["x-pf-height"]);
-				const name = req.headers["x-pf-name"] || "Icon";
 				const rgba = await readBody(req);
 				if (!width || !height) return json(res, 400, { error: "Missing image dimensions." });
 				if (rgba.length !== width * height * 4) {
 					return json(res, 400, { error: `Pixel data is ${rgba.length} bytes, expected ${width * height * 4}.` });
 				}
-				console.log(`[upload] ${name} (${width}x${height}) -> ${cfg.creatorType} ${cfg.creatorId}`);
+				log(col("cyan", "↑ ") + name + col("gray", " (" + width + "×" + height + ")"));
 				const png = encodePng(rgba, width, height);
 				const imageId = await uploadImage(cfg, name, png);
-				console.log(`[upload] done -> Image id ${imageId}`);
+				uploadCount++;
+				log(col("green", "✓ " + name) + col("gray", " → Image ") + col("cyan", imageId));
 				return json(res, 200, { imageId });
 			} catch (err) {
-				console.error("[upload] " + (err && err.message ? err.message : err));
-				return json(res, 502, { error: err && err.message ? err.message : String(err) });
+				const msg = err && err.message ? err.message : String(err);
+				log(col("red", "✗ " + name + ": " + msg));
+				return json(res, 502, { error: msg });
 			}
 		}
 		json(res, 404, { error: "Not found" });
 	});
 
 	server.listen(PORT, HOST, () => {
-		console.log("=================================================");
-		console.log("  PixelForge Uploader is running.");
-		console.log("  Listening on http://localhost:" + PORT);
-		console.log("  Uploading to " + cfg.creatorType + " " + cfg.creatorId + ".");
-		console.log("  Leave this window open while you upload icons.");
-		console.log("=================================================");
+		if (interactive) {
+			renderDashboard();
+		} else {
+			console.log("PixelForge Uploader running on http://localhost:" + PORT);
+			console.log("Uploading to " + creatorPhrase(cfg) + ". Leave this window open.");
+		}
 	});
 	server.on("error", (err) => {
+		if (interactive) {
+			try { process.stdin.setRawMode(false); } catch (_) {}
+			process.stdout.write(SHOW_CURSOR + C.reset);
+		}
 		if (err && err.code === "EADDRINUSE") {
-			console.error("Port " + PORT + " is already in use (another copy may be running).");
+			console.error("\n  Port " + PORT + " is already in use. Another copy may already be running.");
 		} else {
-			console.error("Server error:", err);
+			console.error("\n  Server error:", err);
 		}
 		process.exit(1);
 	});
 }
 
+// ---------- entry ----------
+
+process.on("SIGINT", quit);
+process.on("SIGTERM", quit);
+
 (async function main() {
-	let cfg = loadConfig();
-	if (process.argv[2] === "reconfigure" || !cfg) {
-		if (!cfg) console.log("No saved configuration found.");
+	interactive = !!(process.stdin.isTTY && process.stdout.isTTY);
+	cfg = loadConfig();
+
+	const wantReconfigure = process.argv[2] === "reconfigure";
+	if (wantReconfigure) cfg = null;
+
+	if (!cfg) {
+		if (!interactive) {
+			console.error("PixelForge Uploader isn't set up yet.");
+			console.error("Run it in a terminal to set it up, or pass PIXELFORGE_API_KEY and PIXELFORGE_CREATOR_ID.");
+			process.exit(1);
+		}
 		cfg = await runSetup();
 	}
-	startServer(cfg);
+
+	startServer();
+	attachMenu();
 })();