updateday 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UpdateDay contributors
+
+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

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# UpdateDay
 
-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.
+**Free, open-source update-day automation for Roblox games.**
+
+Pick an update time and UpdateDay runs the whole day for you: countdown icons and titles, a sale, a Roblox event,
+in-game warnings and server restarts. Everything is put back exactly as it was afterwards. It runs on your own
+computer with an Open Cloud API key, needs no logins or cookies, and there's no UpdateDay server.
+
+![The UpdateDay setup page](docs/screenshot.png)
+
+## What it can do
+
+Everything is optional and off until you turn it on.
+
+- **Countdown icons** built from your game's own icon: 24 hours … 5 minutes, then NOW. Pick a style (hand-drawn,
+  classic, pixel, rounded, glow, blocky, outline) or upload your own art, and move and resize the hourglass and the text.
+- **Title countdown**: "[6H] Your Game" → "[LIVE] Your Game" → back to normal, for players in your game's main language.
+- **Moderation check**: Roblox reviews every icon days ahead, so nothing gets rejected on the day.
+- **Sale**: X% off game passes and products, with "[30% OFF]" name tags. Every price and name goes back afterwards.
+- **Events**: create and edit Roblox events, or get one made automatically for every update.
+- **In-game**: warnings before the update, a live "UPDATE IN 04:59" banner, and old servers restarted onto the new version.
+- **Alerts**: Discord messages (with the icon to upload attached) and desktop pop-ups.
+- **Extras**: several games at once, repeating updates, a game page checklist, a history of everything it did,
+  a player-data editor with backups, gifts, translated labels in 15 languages, and an [AI agent hook](docs/AGENTS.md).
+
+## Start in 3 minutes
+
+**1. Install [Node.js](https://nodejs.org) 22.18 or newer.**
+
+**2. Open the setup page** in any folder you like:
+
+```bash
+npx updateday ui updateday.json
+```
+
+It opens on `http://127.0.0.1:4747`, which only your own computer can reach.
+
+**3. Add your game**: paste its Roblox link (`https://www.roblox.com/games/...`) in **Settings**.
+
+**4. Make an API key**: Creator Hub → **Open Cloud → API Keys → Create API Key**. Add your experience, then add the
+permissions for the features you want:
+
+| Feature | Permission to add |
+|---|---|
+| Always | Universe: read |
+| Countdown icons | Legacy universe: manage |
+| Title countdown | Places: read + write |
+| Moderation check | Assets: read + write |
+| Sale | Game passes: read + write, Developer products: read + write |
+| Events | Universe events: read + write |
+| In-game warnings and banner | Messaging service: publish |
+| Server restarts | Universe: write |
+| Player data and gifts | DataStore: list stores, read, create and update entries |
+
+Paste the key in the page (the **▴** at the bottom right). It's kept in memory only and never saved to disk.
+**Check plan** tells you if a permission is missing.
+
+**5. Plan it**: set the update time, choose what you want in each tab, and press **Save**.
+
+**6. Press Start** and leave the page open. **Check plan** runs first and tells you if anything needs fixing.
+Changed your mind? **Undo all** puts every price, name, title and icon back.
+
+## Good to know
+
+- **The main game icon.** Roblox doesn't let API keys change a game's main icon. UpdateDay either reminds you to
+  upload each finished icon (with a download button and a Discord alert), or does it automatically with a
+  *language swap*: it briefly makes another language the game's main one and sets the countdown for every
+  other language. Players whose Roblox language is that temporary one see your normal icon.
+  [More in the guide](docs/GUIDE.md#how-the-icon-changes-on-roblox).
+- **Safe by design.** Original prices, names and titles are saved before anything changes, and every change is
+  read back. If UpdateDay is closed or crashes part-way, it picks up where it left off.
+- **PC off?** Run it from GitHub Actions instead. [See the guide](docs/GUIDE.md#with-your-pc-off-github-actions).
+- **In your game:** download the Roblox kit from **Settings** for the countdown banner and warning pop-ups.
+  [See the guide](docs/GUIDE.md#in-game-countdown).
+
+## Using the terminal instead
+
+The page and these commands share the same `updateday.json`, so you can mix them.
+
+```bash
+npx updateday check updateday.json     # pre-flight check
+npx updateday plan updateday.json      # the full schedule
+npx updateday preview updateday.json   # every countdown icon into ./preview
+npx updateday watch updateday.json     # run it
+npx updateday restore updateday.json   # undo everything now
+```
+
+The key comes from the `UPDATEDAY_API_KEY` environment variable. Every setting is in the [guide](docs/GUIDE.md).
+
+## For AI agents
+
+`npx updateday mcp updateday.json` runs UpdateDay as an MCP server. Claude, Cursor and other agents can then plan
+and check update days for you. Anything that changes your live game needs an explicit confirmation.
+See [docs/AGENTS.md](docs/AGENTS.md).
+
+## Contributing
+
+```bash
+git clone https://github.com/hiyouwhatsapp/UpdateDay && cd UpdateDay
+npm install
+npm test          # unit tests, a full update day against a fake Roblox, edge cases, security
+npm run test:ui   # every tab at desktop and phone size, light and dark (needs Chrome)
+node src/cli.ts ui example/updateday.json
+```
+
+Issues and pull requests are welcome. [docs/COVERAGE.md](docs/COVERAGE.md) lists every Roblox API UpdateDay uses.
+
+## License
+
+MIT. Free for everyone, forever.

package/bin/updateday.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+
+const built = new URL("../dist/cli.js", import.meta.url);
+await import(existsSync(built) ? built.href : new URL("../src/cli.ts", import.meta.url).href);

package/dist/bundle.js

@@ -0,0 +1,54 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { activeMarks, showsNow } from "./config.js";
+import { renderIcon } from "./icons.js";
+import { LABEL_LANGUAGES } from "./labels.js";
+import { zip } from "./zip.js";
+const KIT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../roblox");
+const KIT_README = `UpdateDay in-game kit
+
+UpdateDayListener.luau   ModuleScript (ServerScriptService). Receives UpdateDay's warnings.
+UpdateDayCountdown.server.luau   Script (ServerScriptService). Starts the listener and shares the update time with players.
+UpdateDayBanner.client.luau   LocalScript (StarterPlayerScripts). Shows the countdown banner and warnings.
+UpdateDayGifts.luau   ModuleScript (ServerScriptService). Optional: the gift box used by the Gifts tab.
+
+Every option sits at the top of each file. Turn on "Warn players in live servers"
+in UpdateDay so the game hears about the update.
+`;
+export function iconMarks(countdown) {
+    const marks = activeMarks(countdown);
+    if (showsNow(countdown)) {
+        marks.push("now");
+    }
+    marks.push("final");
+    return marks;
+}
+function fileName(mark, index) {
+    return `${String(index + 1).padStart(2, "0")}-${mark}.png`;
+}
+export async function iconZip(config, base, translated) {
+    const countdown = config.countdown;
+    const marks = iconMarks(countdown);
+    const entries = [];
+    for (const [index, mark] of marks.entries()) {
+        entries.push({ name: fileName(mark, index), data: await renderIcon(base, mark, countdown) });
+    }
+    if (translated) {
+        for (const language of LABEL_LANGUAGES) {
+            for (const [index, mark] of marks.entries()) {
+                if (mark === "final") {
+                    continue;
+                }
+                entries.push({ name: `languages/${language}/${fileName(mark, index)}`, data: await renderIcon(base, mark, countdown, language) });
+            }
+        }
+    }
+    return zip(entries);
+}
+export function kitZip() {
+    const files = readdirSync(KIT_DIR).filter((name) => name.endsWith(".luau"));
+    const entries = files.map((name) => ({ name, data: readFileSync(join(KIT_DIR, name)) }));
+    entries.push({ name: "README.txt", data: Buffer.from(KIT_README) });
+    return zip(entries);
+}

package/dist/cli.js

@@ -0,0 +1,254 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { iconMarks } from "./bundle.js";
+import { loadConfigs, nextOccurrence } from "./config.js";
+import { recording } from "./history.js";
+import { fetchCurrentIcon, renderIcon } from "./icons.js";
+import { startMcp } from "./mcp.js";
+import { discordNotifier } from "./notify.js";
+import { preflight } from "./preflight.js";
+import { OpenCloud } from "./openCloud.js";
+import { endCountdown, restorePrices, tick } from "./runner.js";
+import { checkKey } from "./doctor.js";
+import { startServer } from "./server.js";
+import { buildSchedule } from "./schedule.js";
+import { loadState, saveState } from "./state.js";
+const DEFAULT_CONFIG = "updateday.json";
+const WATCH_INTERVAL_MS = 30 * 1000;
+const PREVIEW_DIR = "preview";
+const KEY_COMMANDS = ["tick", "watch", "restore"];
+const DEFAULT_UI_PORT = 4747;
+const USAGE = `UpdateDay - schedule a Roblox update day with an Open Cloud API key
+
+Usage: updateday <command> [config.json] [--game <name or universeId>] [--dry-run]
+
+Commands:
+  ui        Open the setup page in your browser (http://127.0.0.1:4747)
+  doctor    Check the API key has every permission this config needs
+  plan      Show the full schedule and what has already run
+  check     Pre-flight: check the key, times, files, icons, sale items and alerts
+  preview   Build every countdown icon from the live game icon into ./preview (no key needed)
+  tick      Run every step that is due now, then exit (for cron / GitHub Actions)
+  watch     Keep running and tick every 30 seconds until every schedule is done
+  restore   Put prices, names and the countdown icon back to normal now
+  mcp       Run as an MCP server so AI agents can plan and run update days
+
+A config can hold one game, or several under "games". Commands run for every
+game unless --game picks one. The API key is read from UPDATEDAY_API_KEY, or
+from the variable a game names in "apiKeyEnv".`;
+function formatTime(date) {
+    return date.getTime() === 0 ? "immediately" : date.toLocaleString();
+}
+function header(config, multi) {
+    if (multi) {
+        console.log(`\n=== ${config.name} (${config.universeId}) ===`);
+    }
+}
+function hasDueSteps(game) {
+    const now = new Date();
+    return game.steps.some((step) => step.at <= now && !game.ctx.state.done[step.id]);
+}
+function printPlan(game) {
+    console.log(`Update at ${new Date(game.config.updateAt).toLocaleString()}\n`);
+    for (const step of game.steps) {
+        const status = game.ctx.state.done[step.id] ? "done" : step.at <= game.ctx.now ? "DUE " : "    ";
+        console.log(`[${status}] ${formatTime(step.at).padEnd(24)} ${step.label}`);
+    }
+}
+const CHECK_MARKS = { ok: "OK  ", warn: "WARN", bad: "FIX ", info: "    " };
+function printPreflight(report) {
+    for (const check of report.checks) {
+        console.log(`[${CHECK_MARKS[check.level]}] ${check.title}`);
+        if (check.detail) {
+            console.log(`       ${check.detail}`);
+        }
+    }
+    console.log(report.ready ? "Ready." : "Fix the lines marked FIX before the update.");
+}
+async function preview(config, multi) {
+    if (!config.countdown) {
+        console.log("Countdown icons are turned off for this game.");
+        return;
+    }
+    const folder = multi ? join(PREVIEW_DIR, config.name.replace(/[^\w-]+/g, "_")) : PREVIEW_DIR;
+    const outDir = resolve(config.baseDir, folder);
+    mkdirSync(outDir, { recursive: true });
+    const base = await fetchCurrentIcon(config.universeId);
+    for (const mark of iconMarks(config.countdown)) {
+        const path = join(outDir, `${mark}.png`);
+        writeFileSync(path, await renderIcon(base, mark, config.countdown));
+        console.log(`wrote ${path}`);
+    }
+}
+function webhookFor(config) {
+    return config.notify ? process.env[config.notify.discordWebhookEnv] : undefined;
+}
+function makeGame(config, needsKey) {
+    const apiKey = process.env[config.apiKeyEnv];
+    if (needsKey && !apiKey) {
+        throw new Error(`${config.name}: set ${config.apiKeyEnv} to an Open Cloud API key for this game`);
+    }
+    const ctx = {
+        config,
+        state: loadState(config.statePath, config.updateAt),
+        cloud: apiKey ? new OpenCloud(apiKey, config.universeId) : null,
+        now: new Date(),
+        notify: discordNotifier(config, webhookFor(config)),
+    };
+    return { config, steps: buildSchedule(config), ctx };
+}
+function pickGames(configs, filter) {
+    if (!filter) {
+        return configs;
+    }
+    const picked = configs.filter((config) => config.name === filter || String(config.universeId) === filter);
+    if (picked.length === 0) {
+        throw new Error(`No game named "${filter}" in this config`);
+    }
+    return picked;
+}
+async function tickGame(game, dryRun) {
+    try {
+        game.ctx.now = new Date();
+        const run = () => tick(game.steps, game.ctx, dryRun);
+        return dryRun ? await run() : await recording(game.config, run);
+    }
+    catch (error) {
+        console.error(`${game.config.name}: ${error instanceof Error ? error.message : error}`);
+        process.exitCode = 1;
+        return -1;
+    }
+}
+async function watch(load, multi) {
+    const finished = new Set();
+    while (true) {
+        let waiting = 0;
+        for (const config of load()) {
+            const id = `${config.universeId}|${config.updateAt}`;
+            if (finished.has(id)) {
+                waiting += nextOccurrence(config) ? 1 : 0;
+                continue;
+            }
+            const game = makeGame(config, true);
+            header(game.config, multi && hasDueSteps(game));
+            const remaining = await tickGame(game, false);
+            if (remaining !== 0) {
+                waiting++;
+                continue;
+            }
+            finished.add(id);
+            const next = nextOccurrence(config);
+            console.log(next ? `${config.name}: done. Next update day ${next.toLocaleString()}.` : `${config.name}: schedule complete.`);
+            waiting += next ? 1 : 0;
+        }
+        if (waiting === 0) {
+            return;
+        }
+        await new Promise((done) => setTimeout(done, WATCH_INTERVAL_MS));
+    }
+}
+const DOCTOR_MARKS = { ok: "OK  ", missing: "MISS", error: "ERR ", untested: "--  " };
+async function printDoctor(game) {
+    const probes = await checkKey(game.ctx.cloud, game.config);
+    for (const probe of probes) {
+        const flag = probe.used ? "" : " (not used by this config)";
+        console.log(`[${DOCTOR_MARKS[probe.status]}] ${probe.feature.padEnd(26)} ${probe.permission}${flag}`);
+        if (probe.detail && probe.status !== "ok") {
+            console.log(`       ${probe.detail}`);
+        }
+    }
+    const blocking = probes.filter((probe) => probe.used && (probe.status === "missing" || probe.status === "error"));
+    if (blocking.length > 0) {
+        process.exitCode = 1;
+    }
+}
+function readFlag(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function positional(args) {
+    return args.filter((arg, index) => !arg.startsWith("--") && !["--game", "--port"].includes(args[index - 1]));
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const dryRun = args.includes("--dry-run");
+    const [command, configPath = DEFAULT_CONFIG] = positional(args);
+    if (!command || command === "help") {
+        console.log(USAGE);
+        return;
+    }
+    if (command === "mcp") {
+        await startMcp(configPath);
+        return;
+    }
+    if (command === "ui") {
+        const port = Number(readFlag(args, "--port")) || DEFAULT_UI_PORT;
+        const { url } = await startServer(configPath, port);
+        console.log(`UpdateDay is open at ${url}  (Ctrl+C to quit)`);
+        return;
+    }
+    const allConfigs = loadConfigs(configPath);
+    const configs = pickGames(allConfigs, readFlag(args, "--game"));
+    const multi = allConfigs.length > 1;
+    const needsKey = !dryRun && [...KEY_COMMANDS, "doctor"].includes(command);
+    if (command === "check") {
+        let ok = true;
+        for (const config of configs) {
+            header(config, multi);
+            const apiKey = process.env[config.apiKeyEnv];
+            const report = await preflight(config, apiKey ? new OpenCloud(apiKey, config.universeId) : null, webhookFor(config));
+            printPreflight(report);
+            ok = report.ready && ok;
+        }
+        process.exitCode = ok ? 0 : 1;
+        return;
+    }
+    if (command === "preview") {
+        for (const config of configs) {
+            header(config, multi);
+            await preview(config, multi);
+        }
+        return;
+    }
+    const games = configs.map((config) => makeGame(config, needsKey));
+    switch (command) {
+        case "doctor":
+            for (const game of games) {
+                header(game.config, multi);
+                await printDoctor(game);
+            }
+            return;
+        case "plan":
+            for (const game of games) {
+                header(game.config, multi);
+                printPlan(game);
+            }
+            return;
+        case "tick":
+            for (const game of games) {
+                header(game.config, multi);
+                await tickGame(game, dryRun);
+            }
+            return;
+        case "watch":
+            await watch(() => pickGames(loadConfigs(configPath), readFlag(args, "--game")), multi);
+            return;
+        case "restore":
+            for (const game of games) {
+                header(game.config, multi);
+                await recording(game.config, async () => {
+                    await restorePrices(game.ctx);
+                    await endCountdown(game.ctx);
+                });
+                saveState(game.config.statePath, game.ctx.state);
+            }
+            return;
+        default:
+            console.log(USAGE);
+            process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});