arcadible 0.1.47 → 0.1.49

package/README.md

@@ -46,6 +46,7 @@ Your repository is the store page: `arcadible.toml` holds the game's settings, `
 | `arc inspect`  | Prints the manifest Arcadible will see, or one value from it                   |
 | `arc build`    | Runs your project's build command                                              |
 | `arc pack`     | Packages your project into the zip that `arc deploy` uploads                   |
+| `arc serve`    | Serves your game locally, framed in a play page, as Arcadible does             |
 | `arc deploy`   | Validates, builds, packages, and publishes, directly or through GitHub Actions |
 | `arc play`     | Plays a deployed game from any channel or version                              |
 | `arc open`     | Opens a game's store page                                                      |

package/bin/arc-default.js

@@ -39,6 +39,7 @@ const main = function (argv) {
       .command("validate", "Validate project")
       .command("build", "Build project")
       .command("pack", "Package project")
+      .command("serve", "Serve a game locally")
       .command("deploy", "Deploy project")
       .command("open", "Open a game's store page")
       .command("play", "Play a game")

package/bin/arc-init.js

@@ -149,7 +149,7 @@ const main = function (argv) {
         default: conf.template,
         describe: [
           "Project template",
-          "Public GitHub repository (format: user/repo).",
+          "Public GitHub repository, or a folder in one (user/repo[/folder]).",
         ].join("\n"),
         type: "string",
       })

package/bin/arc-serve.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+"use strict";
+
+// [import]
+
+const path = require("node:path");
+
+// [import]
+
+const hideBin = require("yargs/helpers").hideBin;
+const yargs = require("yargs/yargs");
+
+// [import]
+
+const args = require("../src/util/argv");
+const cfgcode = require("../src/config/code");
+const cfgpackage = require("../src/config/package");
+const cfgproduct = require("../src/config/product");
+const cfgurl = require("../src/config/url");
+const error = require("../src/util/error");
+const log = require("../src/util/log");
+const output = require("../src/util/output");
+const phrase = require("../src/phrase");
+const rc = require("../src/util/rc");
+const serve = require("../src/cli/serve");
+const shell = require("../src/util/shell");
+const spinner = require("../src/util/spinner");
+
+// [use]
+
+const abort = output.abort;
+const ArcError = error.ArcError;
+const findRc = rc.findRc;
+const launch = shell.launch;
+const launched = output.launched;
+const relative = path.relative;
+const resolve = path.resolve;
+const SpinnerWheel = spinner.SpinnerWheel;
+
+// [declare]
+
+const COMMAND = "serve";
+const PORT = 4100;
+const TOOL = cfgproduct.tool;
+const VERSION = cfgpackage.version;
+
+// [define]
+
+const conf = {
+  build: true,
+  open: false,
+  port: PORT,
+  quiet: false,
+  ...findRc(TOOL, COMMAND, process.argv),
+};
+
+// [function]
+
+// fails unless the port is one a server can listen on.
+const checkPort = function (port) {
+  if (Number.isInteger(port) && port > 0 && port < 65536) {
+    return Promise.resolve();
+  }
+  return Promise.reject(
+    new ArcError(cfgcode.ARGUMENT_INVALID, phrase.portInvalid()),
+  );
+};
+
+// [function]
+
+// the page --url names, as a URL, or a failure when it isn't an http one.
+const checkUrl = function (url) {
+  if (url === null || typeof url === "undefined") {
+    return Promise.resolve(null);
+  }
+  try {
+    const parsed = new URL(String(url));
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      return Promise.resolve(parsed.href);
+    }
+  } catch (ex) {
+    // not a URL at all: refused below, as one that isn't http.
+  }
+  return Promise.reject(
+    new ArcError(cfgcode.ARGUMENT_INVALID, phrase.urlInvalid()),
+  );
+};
+
+// [function]
+
+// warns once for each of Arcadible's files that's a kept copy, or can't be
+// had, rather than on every request.
+const remoteWarnings = function ({ quiet }) {
+  const warned = new Set();
+  return function (name, file, ex) {
+    const message = ex
+      ? phrase.remoteUnreachable(name)
+      : file?.kept && phrase.remoteKept(name, file.fetchedAt);
+    if (!message || quiet || warned.has(message)) {
+      return;
+    }
+    warned.add(message);
+    log.pw(message);
+  };
+};
+
+// [function]
+
+const start = function (argv) {
+  const quiet = argv.quiet;
+  // `.arcrc` values are strings, and a flag that isn't a number is NaN.
+  const port = Number(argv.port);
+  const root = resolve(process.cwd(), argv.cwd);
+  const sw = new SpinnerWheel("Building... %s");
+  return checkPort(port)
+    .then(() => checkUrl(argv.url))
+    .then((url) =>
+      serve({
+        build: argv.build,
+        handler: {
+          onBuild: () => sw.start(quiet),
+          onReload() {
+            if (!quiet) {
+              log.p(phrase.reloaded());
+            }
+          },
+          onRemote: remoteWarnings({ quiet }),
+        },
+        port,
+        root,
+        url,
+      }),
+    )
+    .then((served) => {
+      sw.stop(true);
+      const stop = () => {
+        served.close();
+        process.exit(0);
+      };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+      if (!quiet) {
+        log.result(phrase.served(served), [
+          ["Play:", `${served.page}/`],
+          [phrase.serveAlone(), served.game],
+          served.url
+            ? phrase.serveNextUrl()
+            : phrase.serveNext(relative(root, served.deployDir) || "."),
+        ]);
+        if (served.probed && !served.probed.reachable) {
+          log.nlpw(phrase.urlUnreachable(served.url));
+        } else if (served.probed && !served.probed.frameable) {
+          log.nlpw(phrase.urlNotFrameable(served.url, cfgurl.SERVE_URL));
+        }
+      }
+      return argv.open ? launch(`${served.page}/`) : false;
+    })
+    .then((where) => {
+      if (where !== false && !quiet) {
+        launched(where, `http://localhost:${port}/`);
+      }
+    })
+    .catch((ex) => abort(phrase.aborted(COMMAND), ex, { sw }));
+};
+
+// [function]
+
+const main = function (argv) {
+  return start(
+    yargs(args.normalize(hideBin(argv)))
+      .scriptName(`${TOOL} ${COMMAND}`)
+      .usage("$0 [options]")
+      .option("port", {
+        alias: "p",
+        default: conf.port,
+        describe: "Port to serve on",
+        type: "number",
+      })
+      .option("build", {
+        default: conf.build,
+        describe: "Run the build command first",
+        type: "boolean",
+      })
+      .option("url", {
+        describe: "Frame another server's page instead of deploy_dir",
+        type: "string",
+      })
+      .option("open", {
+        alias: "o",
+        default: conf.open,
+        describe: "Open the play page in a web browser",
+        type: "boolean",
+      })
+      .option("quiet", { ...args.QUIET, default: conf.quiet })
+      .option("cwd", args.CWD)
+      .help("help")
+      .alias("help", "h")
+      .version(VERSION)
+      .alias("version", "v")
+      .strict()
+      .parse(),
+  );
+};
+
+// [start]
+
+if (require.main === module) {
+  main(process.argv);
+}
+
+// [export]
+
+module.exports = { main };

package/package.json

@@ -11,6 +11,7 @@
     "arc-open": "bin/arc-open.js",
     "arc-pack": "bin/arc-pack.js",
     "arc-play": "bin/arc-play.js",
+    "arc-serve": "bin/arc-serve.js",
     "arc-validate": "bin/arc-validate.js",
     "arc-whoami": "bin/arc-whoami.js"
   },
@@ -28,10 +29,12 @@
     "ini": "^6.0.0",
     "jsdom": "^27.3.0",
     "marked": "^17.0.1",
+    "mime-types": "^3.0.2",
     "mp4box": "^2.3.0",
     "open": "^8.4.2",
     "pretty-toml": "^1.0.0",
     "qrcode-terminal": "^0.12.0",
+    "range-parser": "^1.3.0",
     "semver": "^7.7.3",
     "yargs": "^17.7.2",
     "zod": "^4.1.13"
@@ -52,6 +55,7 @@
     "./pack": "./src/cli/pack.js",
     "./play": "./src/cli/play.js",
     "./predeploy": "./src/cli/predeploy.js",
+    "./serve": "./src/cli/serve.js",
     "./validate": "./src/cli/validate.js",
     "./whoami": "./src/cli/whoami.js"
   },
@@ -75,5 +79,5 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.js\""
   },
-  "version": "0.1.47"
+  "version": "0.1.49"
 }

package/src/action/serve/tool.js

@@ -0,0 +1,166 @@
+"use strict";
+// arc serve: builds the project unless told not to, then serves deploy_dir
+// framed in a local play page (src/serve), reloading the game when deploy_dir
+// changes.
+
+// [import]
+
+const path = require("node:path");
+
+// [import]
+
+const fs = require("fs-extra");
+
+// [import]
+
+const buildTool = require("../build/tool");
+const cfgcode = require("../../config/code");
+const cfgproduct = require("../../config/product");
+const cfguri = require("../../config/uri");
+const commands = require("../../util/command");
+const error = require("../../util/error");
+const files = require("../../serve/files");
+const given = require("../../parser/given");
+const os = require("../../util/os");
+const phrase = require("../../phrase");
+const reload = require("../../serve/reload");
+const remote = require("../../serve/remote");
+const server = require("../../serve/server");
+
+// [use]
+
+const ArcError = error.ArcError;
+const buildCommand = commands.buildCommand;
+const configDir = os.configDir;
+const dirFiles = files.dirFiles;
+const join = path.join;
+const pathExists = fs.pathExists;
+const relative = path.relative;
+const remoteFiles = remote.remoteFiles;
+const resolvePath = path.resolve;
+const serve = server.serve;
+const watchDir = reload.watchDir;
+
+// [declare]
+
+// what build.channel says while served locally (docs: arc-serve.md).
+const CHANNEL = "local";
+// the saves of a game with no id yet, kept apart from any other's.
+const UNNAMED = "local";
+
+// [function]
+
+// the headers a page needs for the play page to frame it: the play page is
+// cross-origin isolated, so a cross-origin frame must be too, and allow it.
+const FRAMEABLE = {
+  "cross-origin-embedder-policy": ["credentialless", "require-corp"],
+  "cross-origin-resource-policy": ["cross-origin"],
+};
+
+// [function]
+
+// what `url` says when asked: `{ reachable, frameable }`, where `frameable`
+// says whether it sends the headers the play page needs to frame it.
+const probe = async function (url) {
+  try {
+    const res = await fetch(url, { method: "GET" });
+    await res.body?.cancel();
+    const frameable = Object.entries(FRAMEABLE).every(([name, values]) =>
+      values.includes(res.headers.get(name)?.trim().toLowerCase()),
+    );
+    return { frameable, reachable: true };
+  } catch (ex) {
+    return { frameable: false, reachable: false };
+  }
+};
+
+// [function]
+
+// listens, turning a port in use into its code.
+const listen = async function (options) {
+  try {
+    return await serve(options);
+  } catch (ex) {
+    if (ex.code === "EADDRINUSE") {
+      throw new ArcError(cfgcode.PORT_IN_USE, phrase.portInUse(options.port), {
+        cause: ex,
+      });
+    }
+    throw ex;
+  }
+};
+
+// [function]
+
+// serves the project at `conf.root`. `conf.build` false skips the build, and
+// `conf.url` frames that server's page instead of serving deploy_dir.
+// `conf.handler` hears `onBuild()` as a build starts, `onRemote(name, file,
+// error)` for each of Arcadible's files, and `onReload()` for each reload.
+// resolves with `{ page, game, built, deployDir, url, probed, version,
+// close() }`, where `probed` is what `conf.url` answered.
+const main = async function (conf) {
+  const { port, root, url } = conf;
+  const handler = {
+    onBuild() {},
+    onReload() {},
+    onRemote() {},
+    ...conf.handler,
+  };
+  const project = await given(conf);
+  const game = project.game;
+  const options = {
+    info: {
+      channel: CHANNEL,
+      id: game.id ?? UNNAMED,
+      title: game.title ?? game.handle ?? cfgproduct.title,
+      version: game.version ?? null,
+    },
+    onRemote: handler.onRemote,
+    port,
+    remote: remoteFiles({
+      asset: cfguri.ARCADIBLE_ASSET,
+      dir: join(configDir(), cfgproduct.tool, "sdk"),
+      sdk: cfguri.ARCADIBLE_SDK,
+    }),
+  };
+  const version = game.version ?? null;
+  if (url) {
+    const served = await listen({ ...options, src: url });
+    const probed = await probe(url);
+    return { ...served, built: false, deployDir: null, probed, url, version };
+  }
+  const built =
+    conf.build !== false && Boolean(buildCommand(project.workflow.build));
+  if (built) {
+    handler.onBuild();
+    await buildTool({ project, root });
+  }
+  const deployDir = resolvePath(root, project.workflow.deploy_dir);
+  if (!(await pathExists(deployDir))) {
+    throw new ArcError(
+      cfgcode.DEPLOY_DIR_MISSING,
+      phrase.deployDirMissing(relative(root, deployDir) || "."),
+    );
+  }
+  const served = await listen({ ...options, files: dirFiles(deployDir) });
+  const stop = watchDir(deployDir, () => {
+    served.reload();
+    handler.onReload();
+  });
+  return {
+    ...served,
+    built,
+    close() {
+      stop();
+      served.close();
+    },
+    deployDir,
+    probed: null,
+    url: null,
+    version,
+  };
+};
+
+// [export]
+
+module.exports = main;

package/src/cli/index.js

@@ -12,6 +12,7 @@ const open = require("./open");
 const pack = require("./pack");
 const play = require("./play");
 const predeploy = require("./predeploy");
+const serve = require("./serve");
 const validate = require("./validate");
 const whoami = require("./whoami");
 
@@ -28,6 +29,7 @@ module.exports = {
   pack,
   play,
   predeploy,
+  serve,
   validate,
   whoami,
 };

package/src/cli/serve.js

@@ -0,0 +1,15 @@
+"use strict";
+
+// [import]
+
+const serveTool = require("../action/serve/tool");
+
+// [function]
+
+const main = function (conf) {
+  return serveTool(conf);
+};
+
+// [export]
+
+module.exports = main;

package/src/config/code.js

@@ -37,6 +37,7 @@ const CLI = {
   PACKAGE_UNCOMPRESSED_TOO_LARGE: "package_uncompressed_too_large",
   PARSE_FAILED: "parse_failed",
   PATH_NOT_FOUND: "path_not_found",
+  PORT_IN_USE: "port_in_use",
   PROJECT_NOT_REPO_ROOT: "project_not_repo_root",
   SESSION_EXPIRED: "session_expired",
   TEMPLATE_MISSING: "template_missing",

package/src/config/template.js

@@ -8,7 +8,7 @@ const phrase = require("../phrase");
 // [declare]
 
 const HANDLE = cfgproduct.handle;
-const STARTER = `${HANDLE}/starter`;
+const STARTERS = `${HANDLE}/starters`;
 
 // [export]
 
@@ -17,29 +17,29 @@ module.exports = {
     {
       description: phrase.starterBlank(),
       name: "Blank",
-      value: STARTER,
+      value: `${STARTERS}/blank`,
     },
     {
       description: phrase.starterThreeJs(),
       name: "Three.js",
-      value: `${STARTER}-threejs`,
+      value: `${STARTERS}/threejs`,
     },
     {
       description: phrase.starterPhaser(),
       name: "Phaser",
-      value: `${STARTER}-phaser`,
+      value: `${STARTERS}/phaser`,
     },
     {
       description: phrase.starterPixiJs(),
       name: "PixiJS",
-      value: `${STARTER}-pixijs`,
+      value: `${STARTERS}/pixijs`,
     },
     {
       description: phrase.starterBabylonJs(),
       name: "Babylon.js",
-      value: `${STARTER}-babylonjs`,
+      value: `${STARTERS}/babylonjs`,
     },
   ],
-  default: STARTER,
+  default: `${STARTERS}/blank`,
   message: "Template",
 };

package/src/config/uri.js

@@ -12,6 +12,11 @@ const PROTOCOL = cfgproduct.protocol;
 // [export]
 
 module.exports = {
+  // where arc serve fetches Arcadible's own files (src/serve/remote.js): the
+  // asset site, which has the play page's host, and a build origin, any of
+  // which serves the SDK's hosted script at /arcadible/sdk/.
+  ARCADIBLE_ASSET: "https://asset.offst.net",
+  ARCADIBLE_SDK: `https://sdk.${cfgproduct.handle}.io`,
   HOST_APP_PLAY: `${PROTOCOL}://play`,
   HOST_APP_STORE: `${PROTOCOL}://store`,
   HOST_HTTP_ACCOUNT: `https://account.${DOMAIN}`,

package/src/config/url.js

@@ -15,4 +15,6 @@ module.exports = {
   ERRORS: `${cfguri.HOST_HTTP_DEVELOPER}/references/errors`,
   LINK: `${cfguri.HOST_HTTP_ACCOUNT}/link`,
   MANIFEST: `${cfguri.HOST_HTTP_DEVELOPER}/references/${HANDLE}-manifest`,
+  // how to let arc serve's play page frame another server.
+  SERVE_URL: `${cfguri.HOST_HTTP_DEVELOPER}/references/${HANDLE}-cli/arc-serve#url`,
 };

package/src/phrase.js

@@ -272,6 +272,103 @@ const packed = function () {
 
 // [function]
 
+const portInvalid = function () {
+  return "The port must be a whole number from 1 to 65535.";
+};
+
+// [function]
+
+const portInUse = function (port) {
+  return blocks(
+    `Port ${port} is in use.`,
+    "Stop what's using it, or pass another with --port.",
+  );
+};
+
+// [function]
+
+// what one of Arcadible's files is, for arc serve's warnings: `host`, the play
+// page's, or a path under /arcadible/, such as sdk/v1.js.
+const remoteName = function (name) {
+  return name === "host"
+    ? "the play page's host"
+    : `/${cfgproduct.handle}/${name}`;
+};
+
+// [function]
+
+// arc serve's copy of one of Arcadible's files, kept from `fetchedAt`.
+const remoteKept = function (name, fetchedAt) {
+  return `${TITLE} can't be reached: serving ${remoteName(name)} from ${fetchedAt.slice(0, 10)}.`;
+};
+
+// [function]
+
+const remoteUnreachable = function (name) {
+  return `${TITLE} can't be reached, and there's no copy of ${remoteName(name)} yet: the game runs without it until ${TITLE} can be.`;
+};
+
+// [function]
+
+const reloaded = function () {
+  return `Reloaded at ${new Date().toTimeString().slice(0, 8)}.`;
+};
+
+// [function]
+
+const serveAlone = function () {
+  return "The game alone, without the play page:";
+};
+
+// [function]
+
+const serveNext = function (dir) {
+  return `Reloads when ${dir}/ changes. Press Ctrl+C to stop.`;
+};
+
+// [function]
+
+const served = function ({ built, url, version }) {
+  const what = version ? `v${version}` : "the game";
+  if (url) {
+    return `Serving ${what} locally, from ${url}`;
+  }
+  return built
+    ? `Built and serving ${what} locally.`
+    : `Serving ${what} locally.`;
+};
+
+// [function]
+
+const serveNextUrl = function () {
+  return "Your server reloads the game. Press Ctrl+C to stop.";
+};
+
+// [function]
+
+const urlInvalid = function () {
+  return "The URL must be an http or https one, such as http://localhost:5173.";
+};
+
+// [function]
+
+// --url's server sent no headers that let the play page frame it. `link`
+// says how to add them.
+const urlNotFrameable = function (url, link) {
+  return blocks(
+    `⚠ ${url} can't be framed by the play page: it needs to send Cross-Origin-Embedder-Policy: require-corp and Cross-Origin-Resource-Policy: cross-origin.`,
+    ["Add them to your server, as the starters' vite.config.js does:", link],
+  );
+};
+
+// [function]
+
+const urlUnreachable = function (url) {
+  return `⚠ Nothing answers at ${url} yet. Start your server, then reload the play page.`;
+};
+
+// [function]
+
 const pressEnterToOpen = function () {
   return "Press Enter to open the URL.";
 };
@@ -726,7 +823,7 @@ const tagPushed = function (tag) {
 const templateUnavailable = function (template) {
   return blocks(
     `Unable to download template ${template}.`,
-    "Check that it's a public GitHub repository.",
+    "Check that it's a public GitHub repository, or a folder in one.",
   );
 };
 
@@ -971,6 +1068,8 @@ module.exports = {
   packageTooManyFiles,
   packageUncompressedTooLarge,
   packed,
+  portInUse,
+  portInvalid,
   pressEnterToOpen,
   projectNotRepoRoot,
   releaseFailed,
@@ -978,7 +1077,14 @@ module.exports = {
   releasePublished,
   releaseTimedOut,
   releaseWaiting,
+  reloaded,
+  remoteKept,
+  remoteUnreachable,
   repoNotConnected,
+  serveAlone,
+  serveNext,
+  serveNextUrl,
+  served,
   sessionExpired,
   sizeB,
   sizeGb,
@@ -1001,6 +1107,9 @@ module.exports = {
   unknownTable,
   uploadFailed,
   uploadRateLimited,
+  urlInvalid,
+  urlNotFrameable,
+  urlUnreachable,
   versionExists,
   versionPrerelease,
   versionRelease,