arcadible 0.1.42 → 0.1.44

package/README.md

@@ -35,7 +35,7 @@ arc init star-drift && cd star-drift
 arc deploy
 ```
 
-Your repository is the store page: `arcadible.toml` holds the game's settings, `README.md` its title and description, and `.arcadible/` its art. `arc deploy` validates, builds, packages, and publishes it, then waits until the release is live.
+Your repository is the store page: `arcadible.toml` holds the game's settings, `README.md` its title and description, and `.arcadible/` its art. `arc deploy` validates, builds, packages, and publishes it, then waits until the release is live. A new project starts at a prerelease version, `0.1.0-beta.1`, so its first deploy goes to staging: a link to play and share, before players see it.
 
 ## Commands
 

package/bin/arc-build.js

@@ -35,6 +35,8 @@ const print = output.print;
 const relative = path.relative;
 const resolve = path.resolve;
 const SpinnerWheel = spinner.SpinnerWheel;
+const warn = output.warn;
+const warning = output.warning;
 
 // [declare]
 
@@ -58,6 +60,8 @@ const start = function (argv) {
   const root = resolve(process.cwd(), argv.cwd);
   // the project, parsed once for both steps.
   let parsed = null;
+  // what --json lists under `warnings`.
+  let warnings = [];
   let sw = new SpinnerWheel("Validating... %s");
   sw.start(json || quiet);
   return project(root)
@@ -65,23 +69,34 @@ const start = function (argv) {
       parsed = proj;
       return validate({ project: parsed, root });
     })
-    .then((issues) => {
-      const count = issues.length;
+    .then((validated) => {
+      const count = validated.issues.length;
+      warnings = validated.warnings;
       if (count) {
         throw new ArcError(
           cfgcode.VALIDATION_FAILED,
           phrase.issuesFound(count),
-          { data: { issues } },
+          { data: { issues: validated.issues } },
         );
       }
       sw.stop(true);
+      warn(warnings, { json, quiet });
       sw = new SpinnerWheel("Building... %s");
       sw.start(json || quiet);
       return build({ project: parsed, root });
     })
     .then((artifact) => {
       if (json) {
-        print({ artifact });
+        const missing = artifact?.missing
+          ? [
+              warning(
+                cfgcode.WARNING.DEPLOY_DIR_NOT_BUILT,
+                phrase.buildOutputMissing(relative(root, artifact.missing)),
+                "workflow.deploy_dir",
+              ),
+            ]
+          : [];
+        print({ artifact, warnings: [...warnings, ...missing] });
         return;
       }
       if (!quiet) {
@@ -101,7 +116,9 @@ const start = function (argv) {
         log.hs("Nothing to do.");
       }
     })
-    .catch((ex) => abort("Build aborted.", ex, { json, sw }));
+    .catch((ex) =>
+      abort("Build aborted.", ex, { data: { warnings }, json, sw }),
+    );
 };
 
 // [function]

package/bin/arc-deploy.js

@@ -41,6 +41,8 @@ const print = output.print;
 const ProgressBar = progress.ProgressBar;
 const resolve = path.resolve;
 const SpinnerWheel = spinner.SpinnerWheel;
+const warn = output.warn;
+const warning = output.warning;
 
 // [declare]
 
@@ -64,7 +66,9 @@ const conf = {
 
 // [function]
 
-const handler = function ({ json, pb, quiet, sw }) {
+// `warnings` collects what --json lists, such as a version that couldn't be
+// checked.
+const handler = function ({ json, pb, quiet, sw, warnings }) {
   return {
     onAccountRefresh(refresh) {
       sw.start(json || quiet);
@@ -75,7 +79,10 @@ const handler = function ({ json, pb, quiet, sw }) {
         pb.start();
       }
     },
-    onLogInfo({ level, message }) {
+    onLogInfo({ code, level, message }) {
+      if (code) {
+        warnings.push(warning(code, message));
+      }
       if (!json && !quiet) {
         switch (level) {
           case "warn":
@@ -252,6 +259,8 @@ const start = function (argv) {
   // the project, parsed once and given to each step. A build can write files
   // the manifest reads, such as art, so it's parsed again after one runs.
   let parsed = null;
+  // what --json lists under `warnings`: arc validate's, then the deploy's.
+  const warnings = [];
   let sw = new SpinnerWheel("Validating... %s");
   sw.start(json || quiet);
   return checkTimeout(timeout)
@@ -260,25 +269,29 @@ const start = function (argv) {
       parsed = proj;
       return validate({ project: parsed, root });
     })
-    .then((issues) => {
-      const count = issues.length;
+    .then((validated) => {
+      const count = validated.issues.length;
+      warnings.push(...validated.warnings);
       if (count) {
         throw new ArcError(
           cfgcode.VALIDATION_FAILED,
           phrase.issuesFound(count),
-          { data: { issues } },
+          { data: { issues: validated.issues } },
         );
       }
       sw.stop(true);
+      warn(validated.warnings, { json, quiet });
       sw = new SpinnerWheel("Checking... %s");
       // git deploys need no login: anyone who can push to the repository can
       // release, and the Arcadible GitHub App publishes the release. Anyone
       // can wait for it too; the game's owner, logged in, waits among their
       // own releases, which also say when the repository isn't connected.
       if (git) {
-        return whoamiIfAny({ handler: handler({ json, pb, quiet, sw }) });
+        return whoamiIfAny({
+          handler: handler({ json, pb, quiet, sw, warnings }),
+        });
       }
-      return whoami({ handler: handler({ json, pb, quiet, sw }) });
+      return whoami({ handler: handler({ json, pb, quiet, sw, warnings }) });
     })
     .then((current) => {
       if (!current && !git) {
@@ -293,7 +306,7 @@ const start = function (argv) {
         predeploy({
           current,
           git,
-          handler: handler({ json, pb, quiet, sw }),
+          handler: handler({ json, pb, quiet, sw, warnings }),
           project: parsed,
           root,
         }),
@@ -314,7 +327,23 @@ const start = function (argv) {
     .then(([current, artifact]) =>
       Promise.all([current, artifact, artifact ? project(root) : parsed]),
     )
-    .then(([current, artifact, proj]) => {
+    .then(([current, artifact, proj]) =>
+      Promise.all([
+        current,
+        artifact,
+        proj,
+        proj === parsed ? null : validate({ project: proj, root }),
+      ]),
+    )
+    .then(([current, artifact, proj, validated]) => {
+      const count = validated?.issues.length ?? 0;
+      if (count) {
+        throw new ArcError(
+          cfgcode.VALIDATION_FAILED,
+          phrase.issuesAfterBuild(count),
+          { data: { issues: validated.issues } },
+        );
+      }
       parsed = proj;
       sw.stop(true);
       sw = new SpinnerWheel("Packing... %s");
@@ -341,7 +370,7 @@ const start = function (argv) {
           artifact,
           current,
           git,
-          handler: handler({ json, pb, quiet, sw }),
+          handler: handler({ json, pb, quiet, sw, warnings }),
           project: parsed,
           root,
         }),
@@ -358,7 +387,7 @@ const start = function (argv) {
       const shown = { ...deployed };
       delete shown.game;
       delete shown.release;
-      const result = git ? shown : { built, ...shown };
+      const result = { ...(git ? shown : { built, ...shown }), warnings };
       sw.stop(true);
       if (argv.wait) {
         return waitAndReport(current, deployed, result, {
@@ -378,7 +407,9 @@ const start = function (argv) {
       }
       return null;
     })
-    .catch((ex) => abort("Deploy aborted.", ex, { json, pb, sw }));
+    .catch((ex) =>
+      abort("Deploy aborted.", ex, { data: { warnings }, json, pb, sw }),
+    );
 };
 
 // [function]

package/bin/arc-pack.js

@@ -34,6 +34,7 @@ const findRc = rc.findRc;
 const print = output.print;
 const resolve = path.resolve;
 const SpinnerWheel = spinner.SpinnerWheel;
+const warn = output.warn;
 
 // [declare]
 
@@ -59,6 +60,8 @@ const start = function (argv) {
   const root = resolve(process.cwd(), argv.cwd);
   // the project, parsed once for both steps.
   let parsed = null;
+  // what --json lists under `warnings`.
+  let warnings = [];
   let sw = new SpinnerWheel("Validating... %s");
   sw.start(json || quiet);
   return project(root)
@@ -66,16 +69,18 @@ const start = function (argv) {
       parsed = proj;
       return validate({ project: parsed, root });
     })
-    .then((issues) => {
-      const count = issues.length;
+    .then((validated) => {
+      const count = validated.issues.length;
+      warnings = validated.warnings;
       if (count) {
         throw new ArcError(
           cfgcode.VALIDATION_FAILED,
           phrase.issuesFound(count),
-          { data: { issues } },
+          { data: { issues: validated.issues } },
         );
       }
       sw.stop(true);
+      warn(warnings, { json, quiet });
       sw = new SpinnerWheel("Packing... %s");
       sw.start(json || quiet);
       return pack({
@@ -87,7 +92,7 @@ const start = function (argv) {
     })
     .then((artifact) => {
       if (json) {
-        print({ artifact });
+        print({ artifact, warnings });
         return;
       }
       if (!quiet) {
@@ -96,7 +101,9 @@ const start = function (argv) {
         print(artifact, { nl: true, toml: true });
       }
     })
-    .catch((ex) => abort("Pack aborted.", ex, { json, sw }));
+    .catch((ex) =>
+      abort("Pack aborted.", ex, { data: { warnings }, json, sw }),
+    );
 };
 
 // [function]

package/bin/arc-validate.js

@@ -28,6 +28,7 @@ const dereference = schema.dereference;
 const findRc = rc.findRc;
 const print = output.print;
 const resolve = path.resolve;
+const schemaPrint = schema.print;
 
 // [declare]
 
@@ -48,24 +49,30 @@ const conf = {
 const start = function (argv) {
   const json = argv.json;
   return validate({ root: resolve(process.cwd(), argv.cwd) })
-    .then((issues) => {
+    .then(({ issues, warnings }) => {
       const count = issues.length;
       if (json) {
-        print({ issues });
-      } else if (count) {
+        print({ issues, warnings });
+      } else {
         const [probs, refs] = dereference(issues);
         const probcount = probs.length;
         if (probcount) {
           log.hdo(`${probcount} ${probcount === 1 ? "issue" : "issues"}:`);
           log.p(probs.map((prob) => `✗ ${prob}`));
         }
+        const warncount = argv.quiet ? 0 : warnings.length;
+        if (warncount) {
+          log.hwo(`${warncount} ${warncount === 1 ? "warning" : "warnings"}:`);
+          log.p(warnings.map((each) => `⚠ ${schemaPrint(each)}`));
+        }
         const refcount = refs.length;
         if (refcount) {
           log.h(`${refcount} ${refcount === 1 ? "reference" : "references"}:`);
           log.p(refs);
         }
-      } else if (!argv.quiet) {
-        log.hs("No issues found.");
+        if (!count && !argv.quiet) {
+          log.hs("No issues found.");
+        }
       }
       process.exit(count ? 1 : 0);
     })

package/package.json

@@ -75,5 +75,5 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.js\""
   },
-  "version": "0.1.42"
+  "version": "0.1.44"
 }

package/src/action/login/flow.js

@@ -28,7 +28,7 @@ const POLL = {
   interval: time.s(15),
   maxDelay: time.s(5),
   timeoutError: () =>
-    new ArcError(cfgcode.LOGIN_EXPIRED, phrase.loginExpired()),
+    new ArcError(cfgcode.LOGIN_CODE_EXPIRED, phrase.loginCodeExpired()),
 };
 
 // [function]
@@ -73,7 +73,10 @@ const pollFlow = function (value, onLoginPoll) {
       case "failed":
         throw new ArcError(cfgcode.LOGIN_FAILED, phrase.loginFailed());
       default:
-        throw new ArcError(cfgcode.LOGIN_EXPIRED, phrase.loginExpired());
+        throw new ArcError(
+          cfgcode.LOGIN_CODE_EXPIRED,
+          phrase.loginCodeExpired(),
+        );
     }
   });
 };

package/src/action/pack/tool.js

@@ -69,15 +69,26 @@ const verifyTotal = function (zip) {
 
 // [function]
 
-const pack = function (name, game, { inputPath, mediaPath, outputPath }) {
+// `deployDir` when the input is deploy_dir, rather than a folder --input
+// named: a missing deploy_dir means the build hasn't written it.
+const pack = function (
+  name,
+  game,
+  { deployDir, inputPath, mediaPath, outputPath },
+) {
   const zip = new Zip(name);
   return pathExists(inputPath)
     .then((existsInput) => {
       if (!existsInput) {
-        throw new ArcError(
-          cfgcode.PATH_NOT_FOUND,
-          phrase.unableToFind(inputPath),
-        );
+        throw deployDir
+          ? new ArcError(
+              cfgcode.DEPLOY_DIR_MISSING,
+              phrase.deployDirMissing(inputPath),
+            )
+          : new ArcError(
+              cfgcode.PATH_NOT_FOUND,
+              phrase.unableToFind(inputPath),
+            );
       }
       zip.addDir(inputPath);
       return zip;
@@ -105,8 +116,11 @@ const main = function ({ input, output, ...conf }) {
   return given(conf).then(({ game, workflow }) => {
     const name = game.handle ?? game.id;
     const file = output ?? `${OUTPUT}/${name}-v${game.version}.zip`;
+    const deployDir = resolve(root, workflow.deploy_dir);
+    const inputPath = resolve(root, input ?? workflow.deploy_dir);
     return pack(parse(file).name, game, {
-      inputPath: resolve(root, input ?? workflow.deploy_dir),
+      deployDir: inputPath === deployDir,
+      inputPath,
       mediaPath: resolve(root, MEDIA),
       outputPath: resolve(root, file),
     });

package/src/action/predeploy/git.js

@@ -77,11 +77,28 @@ const ensureClean = function (root) {
 
 // [function]
 
+// fails with git_remote_missing when there's no origin, and with
+// git_remote_unreachable when it's there but can't be reached.
 const ensureRemote = function (root) {
-  return git(root, ["ls-remote", "origin"]).then(
-    () => null,
-    failWith(cfgcode.GIT_REMOTE_UNAVAILABLE, phrase.gitRemoteMissing()),
-  );
+  return git(root, ["remote", "get-url", "origin"])
+    .then(
+      () => null,
+      failWith(cfgcode.GIT_REMOTE_MISSING, phrase.gitRemoteMissing()),
+    )
+    .then(() => git(root, ["ls-remote", "origin"]))
+    .then(
+      () => null,
+      // git_remote_missing passes through.
+      (err) => {
+        if (err instanceof ArcError) {
+          throw err;
+        }
+        failWith(
+          cfgcode.GIT_REMOTE_UNREACHABLE,
+          phrase.gitRemoteUnreachable(),
+        )(err);
+      },
+    );
 };
 
 // [function]
@@ -168,7 +185,7 @@ const hasTagLocal = function (root, tag) {
 const hasTagRemote = function (root, tag) {
   return git(root, ["ls-remote", "--tags", "origin", `refs/tags/${tag}`]).then(
     (stdout) => Boolean(stdout.trim()),
-    failWith(cfgcode.GIT_REMOTE_UNAVAILABLE, phrase.gitRemoteMissing()),
+    failWith(cfgcode.GIT_REMOTE_UNREACHABLE, phrase.gitRemoteUnreachable()),
   );
 };
 

package/src/action/predeploy/tool-git.js

@@ -57,6 +57,7 @@ const ensurePublishable = function ({ handle, id, version }, handler) {
     if (game === null || build === null) {
       if (handler.onLogInfo) {
         handler.onLogInfo({
+          code: cfgcode.WARNING.VERSION_UNCHECKED,
           level: "warn",
           message: phrase.versionUnchecked(version),
         });

package/src/action/validate/tool.js

@@ -8,6 +8,7 @@ const readme = require("../../schema/readme");
 const readmeFile = require("../../parser/readme-file");
 const schema = require("../../util/schema");
 const sections = require("../../parser/sections");
+const unknown = require("./unknown");
 const workflow = require("../../schema/workflow");
 
 // [use]
@@ -49,10 +50,14 @@ const validate = function (proj, readmeStructure, { root }) {
 
 // [function]
 
+// the project's issues, which fail it, and its warnings, which don't.
 const main = function (conf) {
   const root = conf.root;
-  return Promise.all([given(conf), structure(root)]).then(
-    ([proj, readmeStructure]) => validate(proj, readmeStructure, { root }),
+  return Promise.all([given(conf), structure(root), unknown(root)]).then(
+    ([proj, readmeStructure, warnings]) => ({
+      issues: validate(proj, readmeStructure, { root }),
+      warnings: warnings.sort(schema.compare),
+    }),
   );
 };
 

package/src/action/validate/unknown.js

@@ -0,0 +1,85 @@
+"use strict";
+
+// [import]
+
+const cfgcode = require("../../config/code");
+const game = require("../../schema/game");
+const manifest = require("../../parser/manifest");
+const strs = require("../../util/strs");
+const workflow = require("../../schema/workflow");
+
+// [use]
+
+const closest = strs.closest;
+const WARNING = cfgcode.WARNING;
+
+// [function]
+
+// the fields each table takes, from its schema.
+const known = function (root) {
+  return {
+    game: Object.keys(game({}, { root }).shape),
+    workflow: Object.keys(workflow({}, { root }).shape),
+  };
+};
+
+// [function]
+
+// a warning, in an issue's shape: Arcadible ignores what it doesn't know, so
+// it's reported without failing, with the name it might have meant.
+const warning = function (path, message, near) {
+  return {
+    code: WARNING.FIELD_UNKNOWN,
+    details: near ? [`Did you mean: ${near}?`] : [],
+    link: null,
+    message,
+    path,
+  };
+};
+
+// [function]
+
+// a value outside any table, such as a `handle` above `[game]`: the field
+// it is, in the table that takes it, if any.
+const untabled = function (fields, name) {
+  const table = Object.keys(fields).find((each) => fields[each].includes(name));
+  return warning(name, "Unknown field.", table ? `${table}.${name}` : null);
+};
+
+// [function]
+
+const isTable = function (value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+};
+
+// [function]
+
+// the tables and fields in arcadible.toml that Arcadible doesn't know, such
+// as a misspelled `genre`, as warnings.
+const main = function (root) {
+  const fields = known(root);
+  const tables = Object.keys(fields);
+  return manifest(root).then((conf) =>
+    Object.entries(conf).flatMap(([table, values]) => {
+      if (!isTable(values)) {
+        return Object.hasOwn(fields, table) ? [] : [untabled(fields, table)];
+      }
+      if (!Object.hasOwn(fields, table)) {
+        return [warning(table, "Unknown table.", closest(table, tables))];
+      }
+      return Object.keys(values)
+        .filter((field) => !fields[table].includes(field))
+        .map((field) =>
+          warning(
+            `${table}.${field}`,
+            "Unknown field.",
+            closest(field, fields[table]),
+          ),
+        );
+    }),
+  );
+};
+
+// [export]
+
+module.exports = main;

package/src/config/code.js

@@ -8,24 +8,26 @@
 
 // the CLI's own codes.
 const CLI = {
-  API_ERROR: "api_error",
+  API_REFUSED: "api_refused",
+  API_UNREACHABLE: "api_unreachable",
   ARGUMENT_INVALID: "argument_invalid",
   BUILD_FAILED: "build_failed",
+  DEPLOY_DIR_MISSING: "deploy_dir_missing",
   GAME_EXISTS: "game_exists",
   GAME_ID_MISSING: "game_id_missing",
   GAME_NOT_DEPLOYED: "game_not_deployed",
   GAME_NOT_FOUND: "game_not_found",
-  GIT_REMOTE_UNAVAILABLE: "git_remote_unavailable",
+  GIT_REMOTE_MISSING: "git_remote_missing",
+  GIT_REMOTE_UNREACHABLE: "git_remote_unreachable",
   GIT_REPO_MISSING: "git_repo_missing",
   GIT_TAG_CREATE_FAILED: "git_tag_create_failed",
   GIT_TAG_EXISTS: "git_tag_exists",
   GIT_TAG_PUSH_FAILED: "git_tag_push_failed",
   GIT_UNCOMMITTED: "git_uncommitted",
   LOCKFILE_MISSING: "lockfile_missing",
-  LOGIN_EXPIRED: "login_expired",
+  LOGIN_CODE_EXPIRED: "login_code_expired",
   LOGIN_FAILED: "login_failed",
   MANIFEST_MISSING: "manifest_missing",
-  NETWORK_ERROR: "network_error",
   NOT_LOGGED_IN: "not_logged_in",
   PACKAGE_FILE_TOO_LARGE: "package_file_too_large",
   PACKAGE_INDEX_MISSING: "package_index_missing",
@@ -48,24 +50,26 @@ const CLI = {
 // thing wherever it appears: GAME_UNAVAILABLE, INTERNAL, REPO_NOT_CONNECTED,
 // and VERSION_EXISTS are the CLI's too.
 const RELEASE = {
-  APP_NOT_INSTALLED: "app_not_installed",
-  EXPIRED: "expired",
+  BUILD_RATE_LIMITED: "build_rate_limited",
   GAME_LIMIT_REACHED: "game_limit_reached",
   GAME_MISMATCH: "game_mismatch",
   GAME_UNAVAILABLE: "game_unavailable",
+  GITHUB_APP_NOT_INSTALLED: "github_app_not_installed",
   INTERNAL: "internal",
   MANIFEST_INVALID: "manifest_invalid",
-  RATE_LIMITED: "rate_limited",
+  RELEASE_EXPIRED: "release_expired",
   REPO_NOT_CONNECTED: "repo_not_connected",
   VERSION_EXISTS: "version_exists",
+  VERSION_MISMATCH: "version_mismatch",
   ZIP_INVALID: "zip_invalid",
+  ZIP_MISSING: "zip_missing",
   ZIP_TOO_LARGE: "zip_too_large",
 };
 // the Arcadible check's own codes on GitHub, for a `git` release that fails
-// before there's a release (the queue publisher Lambda). `arc deploy git`
+// before there's a release (the queue publisher and subscriber Lambdas). `arc deploy git`
 // checks for workflow_missing before it pushes.
 const GITHUB = {
-  TAG_INVALID: "tag_invalid",
+  GIT_TAG_INVALID: "git_tag_invalid",
   WORKFLOW_MISSING: "workflow_missing",
 };
 // an `arc validate` issue's codes, named for the rule it breaks; the field
@@ -92,6 +96,14 @@ const ISSUE = {
   UUID_INVALID: "uuid_invalid",
   VERSION_INVALID: "version_invalid",
 };
+// a warning's codes: what's reported without failing, in an issue's shape.
+// they follow the same rules, and share the Errors page, so no warning code
+// is also an error or issue code.
+const WARNING = {
+  DEPLOY_DIR_NOT_BUILT: "deploy_dir_not_built",
+  FIELD_UNKNOWN: "field_unknown",
+  VERSION_UNCHECKED: "version_unchecked",
+};
 // every error code, for checking one exists.
 const ALL = new Set([
   ...Object.values(CLI),
@@ -100,6 +112,8 @@ const ALL = new Set([
 ]);
 // every issue code.
 const ISSUES = new Set(Object.values(ISSUE));
+// every warning code.
+const WARNINGS = new Set(Object.values(WARNING));
 
 // [export]
 
@@ -112,4 +126,6 @@ module.exports = {
   ISSUE,
   ISSUES,
   RELEASE,
+  WARNING,
+  WARNINGS,
 };

package/src/phrase.js

@@ -101,6 +101,15 @@ const cmdValidate = function () {
 
 // [function]
 
+const deployDirMissing = function (dir) {
+  return blocks(
+    `Unable to find deploy_dir: ${dir}`,
+    "Run `arc build`, or set deploy_dir to the folder your build writes.",
+  );
+};
+
+// [function]
+
 const docAttrInvalid = function (tag, attr, value) {
   return `Value '${value}' is not valid for the '${attr}' attribute on the '${tag}' tag.`;
 };
@@ -207,8 +216,17 @@ const gitChangesPresent = function () {
 
 const gitRemoteMissing = function () {
   return blocks(
-    "Unable to access Git remote 'origin'.",
-    "Check that it exists and that you can access it.",
+    "No Git remote 'origin'.",
+    "Add the game's GitHub repository as origin.",
+  );
+};
+
+// [function]
+
+const gitRemoteUnreachable = function () {
+  return blocks(
+    "Unable to reach Git remote 'origin'.",
+    "Check your connection, and that you can access it.",
   );
 };
 
@@ -216,7 +234,7 @@ const gitRemoteMissing = function () {
 
 const noManifest = function (file, dir, found) {
   return blocks(
-    dir === "." ? `No ${file} in this directory.` : `No ${file} in ${dir}`,
+    dir === "." ? `No ${file} in this directory.` : `No ${file} in ${dir}.`,
     found
       ? `The project is in \`${found}\`: run arc there, or pass \`-C ${found}\`.`
       : "Run arc in the project's directory, or pass -C, or start a project with `arc init`.",
@@ -337,6 +355,17 @@ const timeoutInvalid = function () {
 
 // [function]
 
+// issues in what the build wrote, such as its art, once arc deploy has
+// parsed the project again.
+const issuesAfterBuild = function (count) {
+  return blocks(
+    `${count} ${count === 1 ? "issue" : "issues"} found after the build.`,
+    `The build writes files the manifest reads. Run ${cmdValidate()} for details.`,
+  );
+};
+
+// [function]
+
 const issuesFound = function (count) {
   return blocks(
     `${count} ${count === 1 ? "issue" : "issues"} found.`,
@@ -346,8 +375,8 @@ const issuesFound = function (count) {
 
 // [function]
 
-const loginExpired = function () {
-  return "Login request expired.";
+const loginCodeExpired = function () {
+  return "Login code expired.";
 };
 
 // [function]
@@ -458,10 +487,9 @@ const packageUncompressedTooLarge = function (size) {
 // and where to see it.
 // `studio` is the game's builds in Studio, for its owner; anyone else can't
 // open it.
-const releaseFailed = function ({ message, reason }, studio) {
+const releaseFailed = function ({ message }, studio) {
   return blocks(
     (message ?? "").split(/(?<=\.)\s+/u).join("\n"),
-    `Reason: ${reason}.`,
     ...(studio ? [[`${TITLE} Studio:`, studio]] : []),
   );
 };
@@ -756,6 +784,7 @@ module.exports = {
   buildSubmitted,
   cmdInit,
   cmdInspect,
+  deployDirMissing,
   docAttrInvalid,
   docAttrUnallowed,
   docCommentUnallowed,
@@ -772,6 +801,7 @@ module.exports = {
   gameUnavailable,
   gitChangesPresent,
   gitRemoteMissing,
+  gitRemoteUnreachable,
   gitRepoMissing,
   gitTagCreateFailed,
   gitTagPushFailed,
@@ -786,8 +816,9 @@ module.exports = {
   imageUnsupported,
   imageWidthMax,
   imageWidthMin,
+  issuesAfterBuild,
   issuesFound,
-  loginExpired,
+  loginCodeExpired,
   loginFailed,
   noGameId,
   noLockFile,

package/src/schema/game.js

@@ -177,7 +177,7 @@ const zSetBasefile = function (field, schema, { max, min }) {
 const zString = function (field, char, { max, min }) {
   return z
     .string()
-    .min(min, atLeast(field, min, "character"))
+    .min(min, { ...atLeast(field, min, "character"), abort: min === 1 })
     .max(max, message(field, [`Must not exceed: ${max} characters`]))
     .superRefine((str, ctx) => {
       const invalid = invalidChars(str, char);
@@ -430,15 +430,29 @@ const zGenres = function () {
 
 // [function]
 
+// each of a handle's rules on its own, so a handle lists every one it breaks:
+// its length, its characters, and its hyphens. The database's
+// check (db/check/game.sql) is the same rules in one regex.
 const zHandle = function () {
   const field = "handle";
   return z.optional(
-    z
-      .string()
-      .min(1, { ...atLeast(field, 1), abort: true })
-      .regex(
-        /^[a-z0-9](?:(?![-]{2})[a-z0-9-]){1,22}[a-z0-9]$/u,
-        message(field, ["Contains invalid characters."]),
+    zString(field, /[a-z0-9-]/u, { max: 24, min: 1 })
+      .min(3, atLeast(field, 3, "characters"))
+      .refine(
+        (str) => !str.startsWith("-") && !str.endsWith("-"),
+        message(
+          field,
+          ["Must not start or end with a hyphen."],
+          ISSUE.CHARACTERS_INVALID,
+        ),
+      )
+      .refine(
+        (str) => !str.includes("--"),
+        message(
+          field,
+          ["Must not contain consecutive hyphens."],
+          ISSUE.CHARACTERS_INVALID,
+        ),
       ),
   );
 };

package/src/util/error.js

@@ -32,14 +32,15 @@ const ArcError = class extends Error {
 
 // [function]
 
-// the code a failure reports: its own, api_error for a request the API
-// refused, or internal for anything else, which is a bug in the CLI.
+// the code a failure reports: its own, api_refused for a request the API
+// refused, or internal for a failure on Arcadible's side (a 5xx) and for
+// anything else, which is a bug in the CLI.
 const codeOf = function (ex) {
   if (ex instanceof ArcError) {
     return ex.code;
   }
-  if (ex instanceof HttpError) {
-    return cfgcode.API_ERROR;
+  if (ex instanceof HttpError && !(ex.status >= 500)) {
+    return cfgcode.API_REFUSED;
   }
   return cfgcode.INTERNAL;
 };

package/src/util/log.js

@@ -82,6 +82,14 @@ const hdo = function (message) {
 
 // [function]
 
+// a warning heading on stdout, for when the warnings are part of the result,
+// as with arc validate's.
+const hwo = function (message) {
+  log(console.log, message, { bold: true, color: "yellow" });
+};
+
+// [function]
+
 const pw = function (message) {
   log(console.warn, message, { color: "yellow" });
 };
@@ -122,6 +130,7 @@ module.exports = {
   hd,
   hdo,
   hs,
+  hwo,
   nlhd,
   nlp,
   nlpd,

package/src/util/output.js

@@ -11,6 +11,7 @@ const error = require("./error");
 const log = require("./log");
 const objs = require("./objs");
 const phrase = require("../phrase");
+const schema = require("./schema");
 const TOML = require("./toml");
 
 // [use]
@@ -65,7 +66,7 @@ const print = function (data, { key, nl, toml } = {}) {
 // release that failed. `nl` puts a blank line before the heading, after
 // output the command has already printed, such as arc login's link.
 // `code` is a failed release's reason, which the API may add to, so it isn't
-// checked, and its message already says it.
+// checked.
 const abort = function (
   heading,
   ex,
@@ -73,12 +74,15 @@ const abort = function (
 ) {
   const message = ex.message;
   const status = ex.status;
+  const shown = code ?? codeOf(ex);
+  const link = `${cfgurl.ERRORS}#${shown}`;
   if (json) {
     print({
       ...ex.data,
       ...data,
       error: {
-        code: code ?? codeOf(ex),
+        code: shown,
+        link,
         message,
         ...(status ? { status } : {}),
       },
@@ -96,16 +100,38 @@ const abort = function (
       log.hd(heading);
     }
     log.pd(message);
-    if (!code) {
-      log.nlpd([
-        phrase.errorCode(codeOf(ex)),
-        chalk.cyan.underline(`${cfgurl.ERRORS}#${codeOf(ex)}`),
-      ]);
-    }
+    log.nlpd([phrase.errorCode(shown), chalk.cyan.underline(link)]);
   }
   process.exit(1);
 };
 
+// [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.
+const warn = function (warnings, { json, quiet } = {}) {
+  if (json || quiet) {
+    return;
+  }
+  warnings.forEach((each) => log.pw(`⚠ ${schema.print(each)}`));
+};
+
+// [function]
+
+// a warning of the command's own, in an issue's shape, as --json lists it
+// under `warnings` beside arc validate's: its code, and the link to it on
+// the Errors page. `path` is the field it's about, if any.
+const warning = function (code, message, path = null) {
+  return {
+    code,
+    details: [],
+    link: `${cfgurl.ERRORS}#${code}`,
+    message,
+    path,
+  };
+};
+
 // [export]
 
-module.exports = { abort, print, printJson, printToml };
+module.exports = { abort, print, printJson, printToml, warn, warning };

package/src/util/request.js

@@ -53,7 +53,7 @@ const parse = function (resp) {
 
 // sends a request to a full URL. `headers` are added to the client's own, and
 // a form is sent as JSON. A request that gets no response, such as when
-// offline, rejects as network_error.
+// offline, rejects as api_unreachable.
 const send = function (method, url, form, headers = {}) {
   const all = {
     [`X-${CLIENT}-Client-Id`]: ID,
@@ -66,7 +66,7 @@ const send = function (method, url, form, headers = {}) {
     headers: all,
     method,
   }).then(parse, (ex) => {
-    throw new ArcError(cfgcode.NETWORK_ERROR, phrase.unableToReach(), {
+    throw new ArcError(cfgcode.API_UNREACHABLE, phrase.unableToReach(), {
       cause: ex,
     });
   });

package/src/util/s3.js

@@ -32,7 +32,7 @@ const requestOpts = function (size) {
 // [function]
 
 // puts the file to the upload link, and resolves once S3 accepts it. A
-// request that gets no response rejects as network_error; a file that can't
+// request that gets no response rejects as api_unreachable; a file that can't
 // be read rejects with its own error.
 const upload = function (url, { path, size }, onProgress) {
   return new Promise((resolve, reject) => {
@@ -49,7 +49,7 @@ const upload = function (url, { path, size }, onProgress) {
     req.on("error", (ex) => {
       reject(
         readError ??
-          new ArcError(cfgcode.NETWORK_ERROR, phrase.unableToReach(), {
+          new ArcError(cfgcode.API_UNREACHABLE, phrase.unableToReach(), {
             cause: ex,
           }),
       );

package/src/util/strs.js

@@ -2,6 +2,42 @@
 
 // [function]
 
+// the number of single-character edits between two strings (Levenshtein).
+const distance = function (a, b) {
+  let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    const next = [i];
+    for (let j = 1; j <= b.length; j += 1) {
+      next[j] = Math.min(
+        row[j] + 1,
+        next[j - 1] + 1,
+        row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    row = next;
+  }
+  return row[b.length];
+};
+
+// [function]
+
+// the candidate nearest `str`, for "Did you mean", or null when none is
+// within two edits.
+const closest = function (str, candidates) {
+  let best = null;
+  let min = 3;
+  for (const candidate of candidates) {
+    const d = distance(str, candidate);
+    if (d < min) {
+      best = candidate;
+      min = d;
+    }
+  }
+  return best;
+};
+
+// [function]
+
 const indentLines = function (strs, spaces = 2) {
   const pad = " ".repeat(spaces);
   return strs
@@ -28,4 +64,10 @@ const trimWhitespace = function (str) {
 
 // [export]
 
-module.exports = { indentLines, stripLeadingInvisible, trimWhitespace };
+module.exports = {
+  closest,
+  distance,
+  indentLines,
+  stripLeadingInvisible,
+  trimWhitespace,
+};