arcadible 0.1.29 → 0.1.31

package/README.md

@@ -1,3 +1,67 @@
-# Arcadible CLI
+<p align="center">
+  <a href="https://arcadible.com">
+    <img src="https://adn-arcadible.imgix.net/images/i18n/core/www/appicon-512.png?w=256" alt="Arcadible" height="96">
+  </a>
+</p>
 
-The Arcadible command-line interface.
+<h1 align="center">Arcadible CLI</h1>
+
+<p align="center">
+  Create, play, and share games with the world.
+</p>
+
+<p align="center">
+  <a href="https://developer.arcadible.com/references/arcadible-cli">Docs</a> ·
+  <a href="https://developer.arcadible.com/guides/games/getting-started">Getting Started</a> ·
+  <a href="https://arcadible.com">Arcadible</a> ·
+  <a href="https://studio.arcadible.com">Studio</a>
+</p>
+
+<br>
+
+`arc` creates, validates, packages, and publishes games on [Arcadible](https://arcadible.com). Bring a game built with any web technology: if it outputs an `index.html`, it ships.
+
+## Install
+
+```sh
+npm install -g arcadible   # requires Node.js 24+
+```
+
+## Quick start
+
+```sh
+arc login
+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.
+
+## Commands
+
+| Command        | What it does                                                                   |
+| -------------- | ------------------------------------------------------------------------------ |
+| `arc init`     | Creates a project from a template, or prepares an existing game                |
+| `arc validate` | Checks your project locally, with the same rules Arcadible uses                |
+| `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 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                                                      |
+| `arc login`    | Logs in to Arcadible with a device code                                        |
+| `arc logout`   | Logs out                                                                       |
+| `arc whoami`   | Shows the account you're logged in to                                          |
+
+Run `arc <command> --help` for its options, or see the [CLI reference](https://developer.arcadible.com/references/arcadible-cli).
+
+## Learn more
+
+- [Getting Started](https://developer.arcadible.com/guides/games/getting-started): from an empty directory to a public game.
+- [The manifest](https://developer.arcadible.com/references/arcadible-manifest): every field in `arcadible.toml`.
+- [Deploying from GitHub](https://developer.arcadible.com/guides/publishing/deploying-from-github): release with a tag, built by GitHub Actions.
+- [Releases](https://developer.arcadible.com/guides/publishing/releases): where a release's result shows, and how to fix a failed one.
+
+## License
+
+Apache-2.0

package/bin/arc-build.js

@@ -12,6 +12,7 @@ const yargs = require("yargs/yargs");
 
 // [import]
 
+const args = require("../src/util/argv");
 const build = require("../src/cli/build");
 const cfgpackage = require("../src/config/package");
 const cfgproduct = require("../src/config/product");
@@ -24,8 +25,10 @@ const validate = require("../src/cli/validate");
 
 // [use]
 
+const abort = output.abort;
 const findRc = rc.findRc;
 const print = output.print;
+const relative = path.relative;
 const resolve = path.resolve;
 const SpinnerWheel = spinner.SpinnerWheel;
 
@@ -40,7 +43,7 @@ const VERSION = cfgpackage.version;
 const conf = {
   json: false,
   quiet: false,
-  ...findRc(TOOL, COMMAND, process.argv, ["--cwd", "-C"]),
+  ...findRc(TOOL, COMMAND, process.argv),
 };
 
 // [function]
@@ -50,13 +53,14 @@ const start = function (argv) {
   const quiet = argv.quiet;
   const root = resolve(process.cwd(), argv.cwd);
   let sw = new SpinnerWheel("Validating... %s");
+  sw.start(json || quiet);
   return validate({ root })
     .then((issues) => {
       const count = issues.length;
       if (count) {
         throw new Error(phrase.issuesFound(count));
       }
-      sw.stop();
+      sw.stop(true);
       sw = new SpinnerWheel("Building... %s");
       sw.start(json || quiet);
       return build({ root });
@@ -68,32 +72,26 @@ const start = function (argv) {
       }
       if (!quiet) {
         sw.stop(true);
-        log.hs("Done.");
-        if (artifact) {
-          print(artifact, { toml: true });
+        log.hs("Built.");
+        if (artifact?.path) {
+          print(artifact, { nl: true, toml: true });
           return;
         }
-        log.p("Nothing to do.");
+        if (artifact?.missing) {
+          log.nlpw(phrase.buildOutputMissing(relative(root, artifact.missing)));
+          return;
+        }
+        log.nlp("Nothing to do.");
       }
     })
-    .catch((ex) => {
-      const message = ex.message;
-      if (json) {
-        print({ error: { message } });
-      } else {
-        sw.stop(true);
-        log.hd("Build aborted.");
-        log.p(message);
-      }
-      process.exit(1);
-    });
+    .catch((ex) => abort("Build aborted.", ex, { json, sw }));
 };
 
 // [function]
 
 const main = function (argv) {
   return start(
-    yargs(hideBin(argv))
+    yargs(args.normalize(hideBin(argv)))
       .scriptName(`${TOOL} ${COMMAND}`)
       .usage("$0 [options]")
       .option("json", {
@@ -108,12 +106,7 @@ const main = function (argv) {
         describe: "Output only errors",
         type: "boolean",
       })
-      .option("cwd", {
-        alias: "C",
-        default: ".",
-        describe: "Set the working directory",
-        type: "string",
-      })
+      .option("cwd", args.CWD)
       .help("help")
       .alias("help", "h")
       .version(VERSION)
@@ -123,7 +116,7 @@ const main = function (argv) {
   );
 };
 
-// [main]
+// [start]
 
 if (require.main === module) {
   main(process.argv);

package/bin/arc-default.js

@@ -8,6 +8,7 @@ const yargs = require("yargs/yargs");
 
 // [import]
 
+const args = require("../src/util/argv");
 const cfgpackage = require("../src/config/package");
 const cfgproduct = require("../src/config/product");
 
@@ -30,7 +31,7 @@ const parse = function (cli) {
 
 const main = function (argv) {
   return parse(
-    yargs(hideBin(argv))
+    yargs(args.normalize(hideBin(argv)))
       .scriptName(TOOL)
       .usage("$0 <command> [options]")
       .command("init", "Initialize project")
@@ -52,7 +53,7 @@ const main = function (argv) {
   );
 };
 
-// [main]
+// [start]
 
 if (require.main === module) {
   main(process.argv);

package/bin/arc-deploy.js

@@ -12,6 +12,7 @@ const yargs = require("yargs/yargs");
 
 // [import]
 
+const args = require("../src/util/argv");
 const build = require("../src/cli/build");
 const cfgpackage = require("../src/config/package");
 const cfgproduct = require("../src/config/product");
@@ -25,10 +26,12 @@ const progress = require("../src/util/progress");
 const rc = require("../src/util/rc");
 const spinner = require("../src/util/spinner");
 const validate = require("../src/cli/validate");
+const wait = require("../src/action/deploy/wait");
 const whoami = require("../src/cli/whoami");
 
 // [use]
 
+const abort = output.abort;
 const findRc = rc.findRc;
 const print = output.print;
 const ProgressBar = progress.ProgressBar;
@@ -39,7 +42,11 @@ const SpinnerWheel = spinner.SpinnerWheel;
 
 const COMMAND = "deploy";
 const TOOL = cfgproduct.tool;
+const SUBMITTING = `Submitting ${progress.FORMAT}`;
 const VERSION = cfgpackage.version;
+// how long `--wait` waits, in seconds. A git release waits on its GitHub
+// workflow first.
+const TIMEOUT = { direct: 300, git: 900 };
 
 // [define]
 
@@ -47,7 +54,8 @@ const conf = {
   json: false,
   method: "direct",
   quiet: false,
-  ...findRc(TOOL, COMMAND, process.argv, ["--cwd", "-C"]),
+  wait: true,
+  ...findRc(TOOL, COMMAND, process.argv),
 };
 
 // [function]
@@ -59,11 +67,8 @@ const handler = function ({ json, pb, quiet, sw }) {
       return refresh(true);
     },
     onDeployBegin() {
-      if (!json && !quiet) {
-        log.p("Submitting...");
-        if (pb) {
-          pb.start();
-        }
+      if (!json && !quiet && pb) {
+        pb.start();
       }
     },
     onLogInfo({ level, message }) {
@@ -98,28 +103,153 @@ const handler = function ({ json, pb, quiet, sw }) {
 
 // [function]
 
+// what was deployed, whether workflow.build ran, where it will be once it's
+// published (the store only shows production), and what happens next. Once
+// waited on, it's published, so it says so. `note` is a last block.
+const report = function (
+  { built, channel, store, tag, url, version },
+  { git, note, published },
+) {
+  let heading = git
+    ? phrase.tagPushed(tag)
+    : phrase.buildSubmitted(version.to, channel, built);
+  let next = git
+    ? phrase.buildPublishingGit(channel)
+    : phrase.buildPublishing();
+  if (published) {
+    heading = phrase.releasePublished(version.to, channel, built);
+    next = null;
+  }
+  log.result(heading, [
+    store ? ["Store:", store] : null,
+    ["Play:", url],
+    next,
+    note ?? null,
+  ]);
+};
+
+// [function]
+
+// the account, or null when there's none or it can't be refreshed: for a git
+// deploy, which only needs one to wait.
+const whoamiIfAny = function (opts) {
+  return whoami(opts).catch(() => null);
+};
+
+// [function]
+
+// the release, as `--json` prints it.
+const releaseJson = function (row) {
+  if (!row) {
+    return null;
+  }
+  return {
+    build: row.build,
+    channel: row.channel,
+    id: row.id,
+    message: row.message,
+    reason: row.reason,
+    status: row.status,
+    version: row.version,
+  };
+};
+
+// [function]
+
+// waits on the release, then reports it: published, or failed or timed out,
+// which exit 1. `result` is what the deploy prints.
+const waitAndReport = async function (
+  current,
+  deployed,
+  result,
+  { git, json, quiet, root, since, timeout },
+) {
+  let sw = new SpinnerWheel(phrase.releaseWaiting(git));
+  sw.start(json || quiet);
+  let building = git;
+  let waited = null;
+  try {
+    waited = await wait(
+      current,
+      deployed,
+      { git, root, since, timeout },
+      {
+        onRelease() {
+          // found: GitHub Actions is done, and Arcadible publishes it now.
+          if (building) {
+            building = false;
+            sw.stop(true);
+            sw = new SpinnerWheel(phrase.releaseWaiting(false));
+            sw.start(json || quiet);
+          }
+        },
+      },
+    );
+  } catch (ex) {
+    sw.stop(true);
+    throw ex;
+  }
+  const { actions, release, studio, timedOut } = waited;
+  const data = { ...result, release: releaseJson(release) };
+  if (timedOut) {
+    const found = Boolean(release);
+    const reason = phrase.releaseTimedOut(result.version.to, timeout, {
+      actions,
+      found,
+      git,
+      studio,
+    });
+    abort("Wait timed out.", new Error(reason), { data, json, sw });
+    return;
+  }
+  if (release.status === "failed") {
+    const reason = phrase.releaseFailed(release, studio);
+    abort("Release failed.", new Error(reason), { data, json, sw });
+    return;
+  }
+  sw.stop(true);
+  if (json) {
+    print(data);
+  } else if (!quiet) {
+    report(result, { git, published: true });
+  }
+};
+
+// [function]
+
 const start = function (argv) {
   const git = argv.method === "git";
   const json = argv.json;
   const quiet = argv.quiet;
+  const timeout = argv.timeout ?? TIMEOUT[git ? "git" : "direct"];
   const root = resolve(process.cwd(), argv.cwd);
   let pb = null;
   let sw = new SpinnerWheel("Validating... %s");
+  sw.start(json || quiet);
   return validate({ root })
     .then((issues) => {
       const count = issues.length;
       if (count) {
         throw new Error(phrase.issuesFound(count));
       }
-      sw.stop();
+      sw.stop(true);
       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. Waiting
+      // reads the release, which needs the game's owner, so a git deploy
+      // that isn't logged in just doesn't wait.
+      if (git) {
+        return argv.wait
+          ? whoamiIfAny({ handler: handler({ json, pb, quiet, sw }) })
+          : null;
+      }
       return whoami({ handler: handler({ json, pb, quiet, sw }) });
     })
     .then((current) => {
-      if (!current) {
+      if (!current && !git) {
         throw new Error(phrase.notLoggedIn());
       }
-      sw.stop();
+      sw.stop(true);
       sw = new SpinnerWheel("Preparing... %s");
       return Promise.all([
         // whoami
@@ -134,7 +264,7 @@ const start = function (argv) {
       ]);
     })
     .then(([current]) => {
-      sw.stop();
+      sw.stop(true);
       sw = new SpinnerWheel("Building... %s");
       sw.start(git || json || quiet);
       return Promise.all([
@@ -145,7 +275,7 @@ const start = function (argv) {
       ]);
     })
     .then(([current, artifact]) => {
-      sw.stop();
+      sw.stop(true);
       sw = new SpinnerWheel("Packing... %s");
       sw.start(git || json || quiet);
       return Promise.all([
@@ -153,64 +283,69 @@ const start = function (argv) {
         current,
         // pack
         git ? null : pack({ input: artifact?.path, root }),
+        // build: whether workflow.build ran
+        Boolean(artifact),
       ]);
     })
-    .then(([current, artifact]) => {
+    .then(([current, artifact, built]) => {
       sw.stop(true);
       if (!json && !quiet && !git) {
-        pb = new ProgressBar(artifact.size);
+        pb = new ProgressBar(artifact.size, SUBMITTING);
       }
-      return deploy({
-        artifact,
+      return Promise.all([
+        // whoami
         current,
-        git,
-        handler: handler({ json, pb, quiet, sw }),
-        root,
-      });
+        // deploy
+        deploy({
+          artifact,
+          current,
+          git,
+          handler: handler({ json, pb, quiet, sw }),
+          root,
+        }),
+        built,
+        // when the release started, to find a git one by
+        Date.now(),
+      ]);
     })
-    .then((version) => {
-      if (json) {
-        print({ version });
-        return;
+    .then(([current, deployed, built, since]) => {
+      if (pb) {
+        pb.stop();
       }
-      if (!quiet) {
-        if (pb) {
-          sw.stop();
-          pb.stop();
-        } else {
-          sw.stop(true);
-        }
-        log.hs("Done.");
-        if (version) {
-          log.p(`Build v${version.to} submitted.`);
-          return;
-        }
-        log.p("Nothing to do.");
+      // the game and release are for waiting, not printing.
+      const shown = { ...deployed };
+      delete shown.game;
+      delete shown.release;
+      const result = git ? shown : { built, ...shown };
+      sw.stop(true);
+      if (argv.wait && current) {
+        return waitAndReport(current, deployed, result, {
+          git,
+          json,
+          quiet,
+          root,
+          since,
+          timeout,
+        });
       }
-    })
-    .catch((ex) => {
-      const message = ex.message;
       if (json) {
-        print({ error: { message } });
-      } else {
-        if (pb) {
-          sw.stop();
-          pb.stop();
-        } else {
-          sw.stop(true);
-        }
-        log.hd("Deploy aborted.");
-        log.p(message);
+        print(result);
+      } else if (!quiet) {
+        report(result, {
+          git,
+          note: argv.wait ? phrase.releaseNotWaited() : null,
+        });
       }
-      process.exit(1);
-    });
+      return null;
+    })
+    .catch((ex) => abort("Deploy aborted.", ex, { json, pb, sw }));
 };
 
 // [function]
 
 const main = function (argv) {
   return start(
-    yargs(hideBin(argv))
+    yargs(args.normalize(hideBin(argv)))
       .scriptName(`${TOOL} ${COMMAND}`)
       .usage("$0 [method] [options]")
       .command("$0 [method]", false, (cli) =>
@@ -233,12 +368,17 @@ const main = function (argv) {
         describe: "Output only errors",
         type: "boolean",
       })
-      .option("cwd", {
-        alias: "C",
-        default: ".",
-        describe: "Set the working directory",
-        type: "string",
+      .option("wait", {
+        alias: "w",
+        default: conf.wait,
+        describe: "Wait until it's published or fails",
+        type: "boolean",
+      })
+      .option("timeout", {
+        describe: "Seconds to wait [default: 300, or 900 for git]",
+        type: "number",
       })
+      .option("cwd", args.CWD)
       .help("help")
       .alias("help", "h")
       .version(VERSION)
@@ -248,7 +388,7 @@ const main = function (argv) {
   );
 };
 
-// [main]
+// [start]
 
 if (require.main === module) {
   main(process.argv);