arcadible 0.1.45 → 0.1.47

package/src/schema/check/workflow.js

@@ -13,6 +13,7 @@ const fs = require("fs-extra");
 const isAbsolute = path.isAbsolute;
 const join = path.join;
 const pathExistsSync = fs.pathExistsSync; // eslint-disable-line no-sync
+const readdirSync = fs.readdirSync; // eslint-disable-line no-sync
 const relative = path.relative;
 const resolve = path.resolve;
 
@@ -71,6 +72,19 @@ const lacksFiles = function (root, target, names) {
   return names.every((name) => !exists(join(root, target), name));
 };
 
+// [function]
+
+// whether an existing `target` lacks a folder named `name` at its root, in any
+// letter case, since a build's paths are case-sensitive once it's served.
+const lacksFolder = function (root, target, name) {
+  if (!exists(root, target)) {
+    return true;
+  }
+  return !readdirSync(join(root, target), { withFileTypes: true }).some(
+    (entry) => entry.isDirectory() && entry.name.toLowerCase() === name,
+  );
+};
+
 // [export]
 
 module.exports = {
@@ -81,4 +95,5 @@ module.exports = {
   isRelative,
   isRoot,
   lacksFiles,
+  lacksFolder,
 };

package/src/schema/game.js

@@ -14,13 +14,12 @@ const z = require("zod");
 const cfgai = require("../config/ai");
 const cfgaudience = require("../config/audience");
 const cfgcode = require("../config/code");
-const cfgdoc = require("../config/doc");
+const cfgfile = require("../config/file");
 const cfggenre = require("../config/genre");
 const cfghtml = require("../config/html");
 const cfgimage = require("../config/image");
 const cfginput = require("../config/input");
 const cfgorientation = require("../config/orientation");
-const cfgproduct = require("../config/product");
 const cfgvideo = require("../config/video");
 const cfgvisibility = require("../config/visibility");
 const chars = require("../util/chars");
@@ -38,6 +37,7 @@ const cleanSemver = semver.clean;
 const docCheck = check.doc;
 const existsCheck = check.exists;
 const extname = path.extname;
+const posixDirname = path.posix.dirname;
 const ISSUE = cfgcode.ISSUE;
 const imageCheck = check.image;
 const invalidChars = chars.invalid;
@@ -51,13 +51,12 @@ const videoCheck = check.video;
 
 // [declare]
 
-const HANDLE = cfgproduct.handle;
 const message = schemaMessage.messages("game");
 
 // [declare]
 
-const GALLERY = `.${HANDLE}/gallery`;
-const MEDIA = `.${HANDLE}`;
+const GALLERY = cfgfile.GALLERY;
+const MEDIA = cfgfile.MEDIA;
 
 // [declare]
 
@@ -144,15 +143,16 @@ const required = function (field, lines) {
 // [function]
 
 // a list of distinct values. Without a max, its length is up to the values.
-const zSet = function (field, schema, { max = Infinity, min }) {
-  return z
-    .array(schema)
-    .min(min, atLeast(field, min, "element"))
-    .max(max, message(field, [`Must not exceed: ${max} elements`]))
-    .refine(
-      (items) => new Set(items).size === items.length,
-      message(field, ["Must not contain duplicate elements."], ISSUE.DUPLICATE),
-    );
+const zSet = function (field, schema, { max, min }) {
+  const list = z.array(schema).min(min, atLeast(field, min, "element"));
+  return (
+    max
+      ? list.max(max, message(field, [`Must not exceed: ${max} elements`]))
+      : list
+  ).refine(
+    (items) => new Set(items).size === items.length,
+    message(field, ["Must not contain duplicate elements."], ISSUE.DUPLICATE),
+  );
 };
 
 // [function]
@@ -174,11 +174,17 @@ const zSetBasefile = function (field, schema, { max, min }) {
 
 // [function]
 
+// a string of `min` to `max` characters, counted as Arcadible counts them: a
+// character outside the Basic Multilingual Plane, such as an emoji, is one,
+// though JavaScript's length counts it as two.
 const zString = function (field, char, { max, min }) {
   return z
     .string()
     .min(min, { ...atLeast(field, min, "character"), abort: min === 1 })
-    .max(max, message(field, [`Must not exceed: ${max} characters`]))
+    .refine(
+      (str) => [...str].length <= max,
+      message(field, [`Must not exceed: ${max} characters`], ISSUE.TOO_LONG),
+    )
     .superRefine((str, ctx) => {
       const invalid = invalidChars(str, char);
       if (invalid.length) {
@@ -197,8 +203,12 @@ const zString = function (field, char, { max, min }) {
 
 // [function]
 
+// plain text, which can't be only spaces.
 const zText = function (field, opts) {
-  return zString(field, /[\p{L}0-9 .,!?'"():;-]/u, opts);
+  return zString(field, /[\p{L}0-9 .,!?'"():;-]/u, opts).refine(
+    (str) => str.trim() !== "",
+    message(field, ["Must not be blank."], ISSUE.EMPTY),
+  );
 };
 
 // [function]
@@ -206,7 +216,7 @@ const zText = function (field, opts) {
 const zHtml = function (field, root, { max, min, ...opts }) {
   const char = /[\p{L}\p{M}\p{N}\p{P}\p{S}\p{Zs}\r\n]/u;
   return zString(field, char, { max, min }).superRefine((str, ctx) => {
-    const issues = docCheck(root, str, { ...opts, type: cfgdoc[".html"] });
+    const issues = docCheck(root, str, opts);
     if (issues.length) {
       ctx.addIssue({
         code: "custom",
@@ -284,27 +294,34 @@ const zMp4 = function (field, root, opts) {
 const zPngMp4 = function (field, root, optsPng, optsMp4) {
   const pngSchema = zPng(field, root, optsPng);
   const mp4Schema = zMp4(field, root, optsMp4);
-  return z.string().superRefine((file, ctx) => {
-    const ext = extname(file);
-    let schema = null;
-    if (Object.hasOwn(cfgimage, ext)) {
-      schema = pngSchema;
-    }
-    if (Object.hasOwn(cfgvideo, ext)) {
-      schema = mp4Schema;
-    }
-    if (!schema) {
-      ctx.addIssue({
-        code: "custom",
-        ...message(field, ["Must be a PNG or MP4 file."], ISSUE.MEDIA_INVALID),
-      });
-      return;
-    }
-    const result = schema.safeParse(file);
-    if (!result.success) {
-      result.error.issues.forEach((issue) => ctx.addIssue(issue));
-    }
-  });
+  return z
+    .string()
+    .min(1, { ...atLeast(field, 1), abort: true })
+    .superRefine((file, ctx) => {
+      const ext = extname(file);
+      let schema = null;
+      if (Object.hasOwn(cfgimage, ext)) {
+        schema = pngSchema;
+      }
+      if (Object.hasOwn(cfgvideo, ext)) {
+        schema = mp4Schema;
+      }
+      if (!schema) {
+        ctx.addIssue({
+          code: "custom",
+          ...message(
+            field,
+            ["Must be a PNG or MP4 file."],
+            ISSUE.MEDIA_INVALID,
+          ),
+        });
+        return;
+      }
+      const result = schema.safeParse(file);
+      if (!result.success) {
+        result.error.issues.forEach((issue) => ctx.addIssue(issue));
+      }
+    });
 };
 
 // [function]
@@ -383,6 +400,10 @@ const checkSrc = function (root, src, tag) {
   ) {
     return false;
   }
+  // the store page finds it by the gallery's path, exactly.
+  if (posixDirname(src) !== GALLERY) {
+    return phrase.docMediaPath(src, GALLERY);
+  }
   return existsCheck(root, src) || phrase.docMediaMissing(src);
 };
 
@@ -465,6 +486,7 @@ const zId = function () {
     .string(
       required(field, [`Run ${phrase.cmdInit()} to generate a new game ID.`]),
     )
+    .min(1, { ...atLeast(field, 1), abort: true })
     .uuid(message(field, ["Must be a valid UUID."]))
     .refine(
       (value) => value === value.toLowerCase(),
@@ -542,10 +564,11 @@ const zVersion = function () {
     .string(
       required(field, ["A version is required unless one can be derived."]),
     )
-    .refine(
-      (value) => validSemver(value) !== null,
-      message(field, ["Must be valid semver."], ISSUE.VERSION_INVALID),
-    )
+    .min(1, { ...atLeast(field, 1), abort: true })
+    .refine((value) => validSemver(value) !== null, {
+      ...message(field, ["Must be valid semver."], ISSUE.VERSION_INVALID),
+      abort: true,
+    })
     .refine(
       // lowercase too, since the database refuses an uppercase prerelease.
       (value) => cleanSemver(value) === value && value === value.toLowerCase(),

package/src/schema/workflow.js

@@ -7,14 +7,17 @@ const z = require("zod");
 // [import]
 
 const cfgcode = require("../config/code");
+const cfgfile = require("../config/file");
 const cfgproduct = require("../config/product");
 const check = require("./check/workflow");
+const commands = require("../util/command");
 const phrase = require("../phrase");
 const schemaMessage = require("./message");
 
 // [use]
 
 const avoidsCheck = check.avoids;
+const buildCommand = commands.buildCommand;
 const ISSUE = cfgcode.ISSUE;
 const existsCheck = check.exists;
 const hasFileCheck = check.hasFile;
@@ -22,23 +25,23 @@ const isInsideCheck = check.isInside;
 const isRelativeCheck = check.isRelative;
 const isRootCheck = check.isRoot;
 const lacksFilesCheck = check.lacksFiles;
+const lacksFolderCheck = check.lacksFolder;
 
 // [declare]
 
-const HANDLE = cfgproduct.handle;
 const message = schemaMessage.messages("workflow");
-const MEDIA = `.${HANDLE}`;
+const MEDIA = cfgfile.MEDIA;
 const INDEX = "index.html";
-const RESERVED = [`${HANDLE}.json`, MEDIA];
+const RESERVED = [cfgfile.PACKAGED, MEDIA];
+// the folder every build's origin keeps for Arcadible's own files, such as
+// the script games include. arc pack checks it again after the build.
+const RESERVED_FOLDER = cfgproduct.handle;
 
 // [function]
 
-// whether `build` runs anything: a command that isn't blank, as `arc build`
-// trims and drops blank ones (action/build/tool.js).
+// whether `build` runs anything, as `arc build` runs it.
 const hasBuild = function (build) {
-  return [build]
-    .flat()
-    .some((cmd) => typeof cmd === "string" && cmd.trim() !== "");
+  return buildCommand(build) !== "";
 };
 
 // [function]
@@ -120,6 +123,16 @@ const zDeployDir = function (root, { build }) {
         ISSUE.PATH_INVALID,
       ),
       abort: true,
+    })
+    .refine((file) => lacksFolderCheck(root, file, RESERVED_FOLDER), {
+      ...message(
+        field,
+        [
+          `Must not have an ${RESERVED_FOLDER} folder at its root, in any letter case. It's reserved for ${cfgproduct.title}'s own files.`,
+        ],
+        ISSUE.PATH_INVALID,
+      ),
+      abort: true,
     });
 };
 

package/src/util/argv.js

@@ -19,6 +19,11 @@ const parse = helpers.Parser;
 
 // [declare]
 
+// the --browser option of arc open and arc play.
+const BROWSER = {
+  describe: "Open in a web browser",
+  type: "boolean",
+};
 // the -C, --cwd option of every project command.
 const CWD = {
   alias: "C",
@@ -26,6 +31,18 @@ const CWD = {
   describe: "Set the working directory",
   type: "string",
 };
+// the -j, --json option, which prints one JSON document (OUTPUT.md).
+const JSON_OUTPUT = {
+  alias: "j",
+  describe: "Format output as JSON",
+  type: "boolean",
+};
+// the -q, --quiet option, which prints only errors.
+const QUIET = {
+  alias: "q",
+  describe: "Output only errors",
+  type: "boolean",
+};
 
 // [function]
 
@@ -87,4 +104,13 @@ const fail = function (argv) {
 
 // [export]
 
-module.exports = { CWD, cwd, fail, json, normalize };
+module.exports = {
+  BROWSER,
+  CWD,
+  JSON_OUTPUT,
+  QUIET,
+  cwd,
+  fail,
+  json,
+  normalize,
+};

package/src/util/command.js

@@ -0,0 +1,18 @@
+"use strict";
+
+// [function]
+
+// workflow.build as the shell runs it: each command trimmed, blank ones
+// dropped, and a list joined with `&&`. Blank when there's nothing to run.
+const buildCommand = function (build) {
+  return [build]
+    .flat()
+    .filter((cmd) => typeof cmd === "string")
+    .map((cmd) => cmd.trim())
+    .filter(Boolean)
+    .join(" && ");
+};
+
+// [export]
+
+module.exports = { buildCommand };

package/src/util/delay.js

@@ -1,21 +1,5 @@
 "use strict";
 
-// [import]
-
-const phrase = require("../phrase");
-const time = require("./time");
-
-// [declare]
-
-const POLL = {
-  delay: time.s(1),
-  factor: 1,
-  interval: time.m(1),
-  maxDelay: time.s(1),
-  timeout: Infinity,
-  timeoutError: phrase.timedOut(),
-};
-
 // [function]
 
 const backoff = function (elapsed, delay, factor, interval, maxDelay) {
@@ -39,10 +23,13 @@ const wait = function (delay, next) {
 
 // [function]
 
+// calls fn(value) until it resolves to something other than null, backing
+// off by `factor` every `interval`, up to `maxDelay`. After `timeout`, it
+// throws timeoutError(), the caller's own error, with its code.
 const poll = function (
   fn,
   value,
-  { delay, factor, interval, maxDelay, timeout, timeoutError } = POLL,
+  { delay, factor, interval, maxDelay, timeout, timeoutError },
 ) {
   const started = Date.now();
   const next = function () {
@@ -52,10 +39,7 @@ const poll = function (
       }
       const elapsed = Date.now() - started;
       if (elapsed >= timeout) {
-        // a function makes the caller's own error, with its code.
-        throw typeof timeoutError === "function"
-          ? timeoutError()
-          : new Error(timeoutError);
+        throw timeoutError();
       }
       return wait(backoff(elapsed, delay, factor, interval, maxDelay), next);
     });

package/src/util/doc.js

@@ -6,7 +6,6 @@ const jsdom = require("jsdom");
 
 // [import]
 
-const cfgdoc = require("../config/doc");
 const phrase = require("../phrase");
 
 // [use]
@@ -59,23 +58,15 @@ const checkNode = function (node, opts, issues) {
 
 // [function]
 
-// checks HTML as written, before anything sanitizes it: every element must be
-// allowed, with only its allowed attributes, each passing its hook. Each
-// problem is reported once.
-const checkHtml = function (str, { allowed, hooks = {} }) {
+// checks the description's HTML as written, before anything sanitizes it:
+// every element must be allowed, with only its allowed attributes, each
+// passing its hook. Each problem is reported once.
+const check = function (str, { allowed, hooks = {} }) {
   const issues = new Set();
   checkNode(JSDOM.fragment(str), { allowed, hooks }, issues);
   return [...issues];
 };
 
-// [function]
-
-const check = function (str, { type, ...opts }) {
-  const checks = { [cfgdoc[".html"]]: checkHtml };
-  const checkDoc = checks[type];
-  return checkDoc ? checkDoc(str, opts) : [phrase.docUnsupported()];
-};
-
 // [export]
 
 module.exports = { check };

package/src/util/links.js

@@ -41,13 +41,26 @@ const storePage = function (game) {
 
 // [function]
 
+// a game's store page on the web.
+const storeUrl = function (game) {
+  return `${cfguri.HOST_HTTP_WWW}${storePage(game)}`;
+};
+
+// [function]
+
+// a game's page in Studio, on one of its tabs, such as `builds`.
+const studioUrl = function (game, tab) {
+  return `${cfguri.HOST_HTTP_STUDIO}/games/${game}/${tab}`;
+};
+
+// [function]
+
 // where a deployed version will be, once it's published: its channel, that
 // channel's play link, and for production, its store page.
 const published = function ({ handle, id, version }) {
   const game = handle ?? id;
   const release = channel(version);
-  const store =
-    release === PRODUCTION ? `${cfguri.HOST_HTTP_WWW}${storePage(game)}` : null;
+  const store = release === PRODUCTION ? storeUrl(game) : null;
   return { channel: release, store, url: playUrl(game, release) };
 };
 
@@ -60,4 +73,6 @@ module.exports = {
   playUrl,
   published,
   storePage,
+  storeUrl,
+  studioUrl,
 };

package/src/util/media.js

@@ -2,12 +2,12 @@
 
 // [import]
 
-const limits = require("../action/pack/limits");
+const cfglimit = require("../config/limit");
 
 // [declare]
 
 // a file too large to pack isn't read.
-const MAX_READ = limits.MAX_FILE_SIZE;
+const MAX_READ = cfglimit.FILE_SIZE;
 
 // [function]
 

package/src/util/objs.js

@@ -29,10 +29,17 @@ const deepCompact = function (obj) {
 
 // [function]
 
+// a TOML table: an object, not an array.
+const isTable = function (value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+};
+
+// [function]
+
 const deepSort = function (obj) {
   return JSON.parse(stringify(obj));
 };
 
 // [export]
 
-module.exports = { deepCompact, deepSort };
+module.exports = { deepCompact, deepSort, isTable };

package/src/util/output.js

@@ -41,7 +41,7 @@ const printToml = function (data, key, nl = false) {
   }
   try {
     write(TOML.stringify(deepSort(data)), nl);
-  } catch (ex) {
+  } catch {
     write(TOML.stringify(deepSort({ [field]: data })), nl);
   }
 };
@@ -107,6 +107,20 @@ const abort = function (
 
 // [function]
 
+// where arc open or arc play opened the page, with its URL, or that it
+// couldn't, with the URL to open by hand.
+const launched = function (where, url) {
+  if (where) {
+    log.result(phrase.opened(where), [url]);
+    return;
+  }
+  log.result(phrase.unableToOpen(), [url, phrase.openToContinue()], {
+    color: "yellow",
+  });
+};
+
+// [function]
+
 // arc validate's warnings, such as an unknown field, on stderr in yellow,
 // before a command that validates goes on. Left out with `--json` and
 // `--quiet`; arc validate --json lists them.
@@ -134,4 +148,12 @@ const warning = function (code, message, path = null) {
 
 // [export]
 
-module.exports = { abort, print, printJson, printToml, warn, warning };
+module.exports = {
+  abort,
+  launched,
+  print,
+  printJson,
+  printToml,
+  warn,
+  warning,
+};

package/src/util/rc.js

@@ -81,7 +81,7 @@ const read = function (file) {
   let str = null;
   try {
     str = readFileSync(file, "utf8");
-  } catch (ex) {
+  } catch {
     return {};
   }
   if (!/^\s*\{/u.test(str)) {
@@ -111,7 +111,7 @@ const findRc = function (cmd, subcmd, argv) {
       {},
     );
   } catch (ex) {
-    return abort(`${subcmd[0].toUpperCase()}${subcmd.slice(1)} aborted.`, ex, {
+    return abort(phrase.aborted(subcmd), ex, {
       json: args.json(argv),
     });
   }

package/src/util/request.js

@@ -27,7 +27,7 @@ const json = function (resp) {
   return resp.text().then((text) => {
     try {
       return JSON.parse(text);
-    } catch (ex) {
+    } catch {
       return null;
     }
   });

package/src/util/s3.js

@@ -8,7 +8,7 @@ const https = require("node:https");
 // [import]
 
 const cfgcode = require("../config/code");
-const error = require("../util/error");
+const error = require("./error");
 const phrase = require("../phrase");
 
 // [use]

package/src/util/schema.js

@@ -24,7 +24,7 @@ const NUMBERS = new Set(["bigint", "int", "number"]);
 // a zod issue's code (config/code.js, ISSUE). Our own checks name theirs in
 // params; zod's built-in ones, which drop params, are named from what zod
 // reports. Anything else is `invalid`, so every issue has a code.
-const codeOf = function (issue) {
+const issueCodeOf = function (issue) {
   switch (issue.code) {
     case "custom":
       return issue.params?.code ?? ISSUE.INVALID;
@@ -71,7 +71,7 @@ const codeOf = function (issue) {
 const toIssue = function (name, issue) {
   const { details, message } = schemaMessage.parse(issue.message);
   return {
-    code: codeOf(issue),
+    code: issueCodeOf(issue),
     details,
     link: issue.path.length
       ? schemaMessage.link(name, String(issue.path[0]))
@@ -128,4 +128,10 @@ const validator = function (name, schema) {
 
 // [export]
 
-module.exports = { codeOf, compare, dereference, print, validator };
+module.exports = {
+  compare,
+  dereference,
+  issueCodeOf,
+  print,
+  validator,
+};

package/src/util/uris.js

@@ -8,7 +8,7 @@
 const isSafeUri = function (uri) {
   try {
     return new URL(uri).protocol === "https:";
-  } catch (ex) {
+  } catch {
     return false;
   }
 };

package/src/util/zip.js

@@ -21,7 +21,7 @@ const join = path.posix.join;
 
 // [class]
 
-const Main = class {
+const Zip = class {
 
   // [constructor]
 
@@ -85,4 +85,4 @@ const Main = class {
 
 // [export]
 
-module.exports = Main;
+module.exports = Zip;

package/src/config/doc.js

@@ -1,7 +0,0 @@
-"use strict";
-
-// [export]
-
-module.exports = {
-  ".html": "text/html",
-};