moshcode 0.24.0

package/src/release-install.mjs

@@ -0,0 +1,191 @@
+// Installer for the workflow CLIs that ship ONLY as GitHub release binaries.
+//
+// gh, supabase, and doctl have no official cross-platform `curl … | sh`
+// installer: each publishes per-platform static binaries on every release, and
+// Supabase explicitly does not support a global npm install ("there is no global
+// `supabase` command with this method"). Rather than guess which of
+// brew/apt/dnf/snap/scoop exists on the box — and rather than ask for sudo — we
+// do what moshcode's own install.sh does: resolve the latest release, download
+// the asset for this OS/arch, and drop the binary in the user's bin dir.
+//
+// `moshcode install gh` runs this file directly; see the install specs in
+// tools.mjs. The descriptors and URL builders are pure so the asset-naming
+// rules (which differ per vendor, in annoying ways) are unit-tested offline.
+import { spawnSync } from "node:child_process";
+import {
+  chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, realpathSync,
+  rmSync, writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * How each vendor names its release assets, and where the binary sits inside
+ * the archive. Verified against real releases — every field here is a fact
+ * about someone else's naming scheme, not a preference:
+ *   - gh spells darwin "macOS", ships darwin as .zip and linux as .tar.gz, and
+ *     nests the binary under a versioned dir + bin/.
+ *   - supabase also publishes version-less asset aliases, so `latest/download`
+ *     resolves without asking the API for a tag first.
+ *   - doctl separates its asset fields with "-" instead of "_".
+ */
+export const RELEASES = {
+  gh: {
+    repo: "cli/cli",
+    binary: "gh",
+    asset: ({ version, platform, arch }) =>
+      platform === "darwin"
+        ? `gh_${version}_macOS_${arch}.zip`
+        : `gh_${version}_linux_${arch}.tar.gz`,
+    binPath: ({ version, platform, arch }) =>
+      `gh_${version}_${platform === "darwin" ? "macOS" : "linux"}_${arch}/bin/gh`,
+  },
+  supabase: {
+    repo: "supabase/cli",
+    binary: "supabase",
+    unversioned: true,
+    asset: ({ platform, arch }) => `supabase_${platform}_${arch}.tar.gz`,
+    binPath: () => "supabase",
+  },
+  doctl: {
+    repo: "digitalocean/doctl",
+    binary: "doctl",
+    asset: ({ version, platform, arch }) => `doctl-${version}-${platform}-${arch}.tar.gz`,
+    binPath: () => "doctl",
+  },
+};
+
+// Node's process.arch names differ from the ones release assets use.
+const ARCHES = { x64: "amd64", arm64: "arm64" };
+
+/**
+ * This machine's release-asset platform/arch, or a thrown error naming the
+ * escape hatch. Windows is deliberately out of scope: moshcode installs itself
+ * with a POSIX shell script, and every one of these vendors ships a Windows
+ * package manager (scoop/winget) that does the job better than we would.
+ */
+export function targetTriple(platform = process.platform, arch = process.arch) {
+  if (platform !== "linux" && platform !== "darwin") {
+    throw new Error(
+      `${platform} isn't supported by this installer — install the CLI with your system package manager (brew/scoop/winget)`,
+    );
+  }
+  const mapped = ARCHES[arch];
+  if (!mapped) {
+    throw new Error(`unsupported architecture ${arch} — expected one of ${Object.keys(ARCHES).join(", ")}`);
+  }
+  return { platform, arch: mapped };
+}
+
+/** Resolve a tool name to its release descriptor, or throw. Own properties only. */
+export function resolveRelease(tool) {
+  const key = String(tool ?? "").trim().toLowerCase();
+  if (!Object.hasOwn(RELEASES, key)) {
+    throw new Error(
+      `unknown release tool ${JSON.stringify(tool)} — expected one of ${Object.keys(RELEASES).join(", ")}`,
+    );
+  }
+  return [key, RELEASES[key]];
+}
+
+/** The newest release tag for `repo`, with any leading "v" stripped. */
+export async function latestVersion(repo, fetchImpl = fetch) {
+  const res = await fetchImpl(`https://api.github.com/repos/${repo}/releases/latest`, {
+    headers: { accept: "application/vnd.github+json", "user-agent": "moshcode" },
+  });
+  if (!res.ok) throw new Error(`could not read the latest ${repo} release (HTTP ${res.status})`);
+  const tag = (await res.json())?.tag_name;
+  if (!tag) throw new Error(`the latest ${repo} release has no tag_name`);
+  return String(tag).replace(/^v/, "");
+}
+
+/**
+ * The download URL for a release asset. Version-less vendors go through
+ * GitHub's `/releases/latest/download/` redirect; the rest need the real tag.
+ */
+export function assetUrl(spec, target) {
+  const asset = spec.asset(target);
+  return spec.unversioned
+    ? `https://github.com/${spec.repo}/releases/latest/download/${asset}`
+    : `https://github.com/${spec.repo}/releases/download/v${target.version}/${asset}`;
+}
+
+/** Where binaries land — the same default install.sh uses for the moshcode wrapper. */
+export function installDir() {
+  return process.env.MOSHCODE_BIN || path.join(homedir(), ".local", "bin");
+}
+
+/** Unpack a .tar.gz or .zip into `dir` using the system tar/unzip. */
+function extract(archive, dir) {
+  const [cmd, args] = archive.endsWith(".zip")
+    ? ["unzip", ["-q", archive, "-d", dir]]
+    : ["tar", ["-xzf", archive, "-C", dir]];
+  const r = spawnSync(cmd, args, { stdio: "inherit" });
+  if (r.error || r.status !== 0) {
+    const why = r.error ? ` (${r.error.message})` : ` (exit ${r.status})`;
+    throw new Error(`${cmd} could not unpack ${path.basename(archive)}${why}`);
+  }
+}
+
+/** A PATH warning is the difference between "installed" and "command not found". */
+function warnIfNotOnPath(dir) {
+  const parts = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  if (parts.includes(dir)) return;
+  console.log(`! ${dir} is not on your PATH — add it:\n    export PATH="${dir}:$PATH"`);
+}
+
+/** Download, unpack, and install one release binary. Returns its final path. */
+export async function installRelease(tool, { fetchImpl = fetch } = {}) {
+  const [key, spec] = resolveRelease(tool);
+  const { platform, arch } = targetTriple();
+  const version = spec.unversioned ? "" : await latestVersion(spec.repo, fetchImpl);
+  const target = { version, platform, arch };
+  const url = assetUrl(spec, target);
+
+  console.log(`↓ ${url}`);
+  const res = await fetchImpl(url, { headers: { "user-agent": "moshcode" } });
+  if (!res.ok) throw new Error(`download failed (HTTP ${res.status}) — ${url}`);
+
+  const work = mkdtempSync(path.join(tmpdir(), `moshcode-${key}-`));
+  try {
+    const archive = path.join(work, path.posix.basename(new URL(url).pathname));
+    writeFileSync(archive, Buffer.from(await res.arrayBuffer()));
+    const unpacked = path.join(work, "unpacked");
+    mkdirSync(unpacked);
+    extract(archive, unpacked);
+
+    const relative = spec.binPath(target);
+    const from = path.join(unpacked, relative);
+    if (!existsSync(from)) {
+      throw new Error(`${spec.binary} was not at ${relative} inside ${path.basename(archive)} — the vendor's archive layout changed`);
+    }
+
+    const dir = installDir();
+    mkdirSync(dir, { recursive: true });
+    const to = path.join(dir, spec.binary);
+    copyFileSync(from, to);
+    chmodSync(to, 0o755);
+    console.log(`✓ ${spec.binary}${version ? ` ${version}` : ""} → ${to}`);
+    warnIfNotOnPath(dir);
+    return to;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** True when this file was executed directly rather than imported. */
+function invokedDirectly() {
+  try {
+    return realpathSync(process.argv[1] || "") === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  installRelease(process.argv[2]).catch((e) => {
+    console.error(`install failed: ${e.message}`);
+    process.exit(1);
+  });
+}

package/src/runtime.mjs

@@ -0,0 +1,161 @@
+// moshscript runtime — runs a .mosh file as JavaScript with the moshcode command
+// vocabulary injected as globals. "secretly all js is legal."
+//
+// How it works:
+//   - The script source is executed inside `with (scope) { … }` in an async
+//     function. `scope` is a Proxy that resolves the command vocabulary
+//     (mosh(), notify(), … — see registry.mjs) and the live `alive` flag.
+//     Everything the proxy doesn't own (const/let locals, console, Math, real
+//     JS) falls through to normal scoping, so full JavaScript works.
+//   - `alive` is a getter. Each read counts one iteration against the --max
+//     budget, so an unbounded `while (alive) { … }` loop terminates on its own;
+//     `stop()` ends it early by flipping the flag. Straight-line scripts and
+//     non-`alive` loops (a plain `for`) are not bounded by --max.
+//
+// This replaces the old custom-DSL interpreter as the execution path. The old
+// grammar (`while (alive) { code(); … }`) is a strict subset of JS, so those
+// scripts run unchanged.
+
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+
+// Shared default iteration budget for both entrypoints (CLI `run` + TUI /run).
+export const DEFAULT_MAX = 3;
+
+/** Strip a leading `#!…` shebang line so `#!/usr/bin/env moshscript` files parse. */
+export function stripShebang(src) {
+  return src.replace(/^\uFEFF?#![^\r\n]*(?:\r?\n|$)/, "");
+}
+
+// The loop governor: owns `alive` truthiness and the iteration budget.
+function makeControl(max, out) {
+  return {
+    ticks: 0,
+    stopped: false,
+    warned: false,
+    // Called on every read of `alive`. Returns whether the loop may continue.
+    tick() {
+      if (this.stopped) return false;
+      if (this.ticks >= max) {
+        if (!this.warned) {
+          this.warned = true;
+          out(`     ⏹  hit --max ${max} — stopping the pit (pass --max to go longer)`);
+        }
+        return false;
+      }
+      this.ticks++;
+      return true;
+    },
+    stop() {
+      this.stopped = true;
+    },
+  };
+}
+
+// The `with` target: a Proxy that owns exactly the vocabulary + a few specials,
+// and lets every other identifier resolve through normal JS scoping.
+//
+// `pending` collects promises returned by async verbs the script did NOT await
+// (e.g. a bare `notify("done")`), so runScript can drain them before returning —
+// otherwise the process could exit before a fire-and-forget notification lands.
+// Blocking verbs (the CLI verbs via spawnSync, sleep) return synchronously and
+// need no draining, which is what keeps the simple no-`await` style correct.
+//
+// What gets queued is `Promise.allSettled([result])`, not the bare `result`. The
+// settled wrapper subscribes immediately, so a fire-and-forget verb that rejects
+// is never seen as an unhandled rejection while the script runs on — queueing the
+// bare promise let Node kill the process at the next tick, before the drain below
+// could ever observe it. The script still gets the original promise back, so an
+// `await`ed call fails exactly as before.
+function makeScope(registry, ctx, control, pending) {
+  const bound = new Map();
+  for (const cmd of registry.all()) {
+    bound.set(cmd.name, (...args) => {
+      const result = cmd.run(ctx, ...args);
+      if (result && typeof result.then === "function") pending.push(Promise.allSettled([result]));
+      return result;
+    });
+  }
+  const owns = (key) =>
+    key === "alive" || key === "argv" || key === "env" || bound.has(key);
+
+  return new Proxy(Object.create(null), {
+    has(_t, key) {
+      // Symbols (incl. Symbol.unscopables) must fall through, or `with` breaks.
+      if (typeof key === "symbol") return false;
+      return owns(key);
+    },
+    get(_t, key) {
+      if (key === "alive") return control.tick();
+      if (key === "argv") return ctx.argv;
+      if (key === "env") return ctx.env;
+      return bound.get(key);
+    },
+    set(_t, key, value) {
+      // Allow `alive = false` as an alias for stop(); protect the vocabulary.
+      if (key === "alive") {
+        control.stopped = !value;
+        return true;
+      }
+      return false;
+    },
+  });
+}
+
+/**
+ * Execute moshscript `source` as JavaScript.
+ *
+ * opts:
+ *   commands  a registry (createRegistry) supplying the vocabulary  [required]
+ *   max       iteration budget for `alive` loops (default DEFAULT_MAX)
+ *   dryRun    narrate side effects instead of performing them
+ *   argv      positional args exposed to the script as `argv`
+ *   env       env exposed as `env` (defaults to process.env)
+ *   out       sink for command output (defaults to console.log)
+ *
+ * Returns { iterations, stopped }.
+ */
+export async function runScript(source, opts = {}) {
+  const registry = opts.commands;
+  if (!registry || typeof registry.all !== "function") {
+    throw new Error("moshscript: runScript needs a { commands } registry");
+  }
+  const out = opts.out || ((s) => console.log(s));
+  const max = Number.isFinite(opts.max) ? opts.max : DEFAULT_MAX;
+  if (!Number.isInteger(max) || max < 1) {
+    throw new Error(`moshscript: max must be a positive integer, got ${JSON.stringify(opts.max)}`);
+  }
+  const control = makeControl(max, out);
+
+  const ctx = {
+    out,
+    dryRun: Boolean(opts.dryRun),
+    argv: opts.argv || [],
+    env: opts.env || process.env,
+    control,
+    get iter() {
+      return control.ticks;
+    },
+    stop() {
+      control.stop();
+    },
+  };
+
+  const pending = [];
+  const scope = makeScope(registry, ctx, control, pending);
+  const body = `with (__scope__) {\n${stripShebang(source)}\n}`;
+  const fn = new AsyncFunction("__scope__", body);
+  try {
+    await fn(scope);
+  } finally {
+    // Let any un-awaited async verbs (fire-and-forget notify) finish delivering.
+    //
+    // Drained in `finally`, not after the call: a script that throws has already
+    // queued its notify(), and the CLI's catch calls process.exit(1) — which kills
+    // the in-flight POST. Draining only on the success path silently dropped the
+    // failure ping, i.e. exactly the notification the operator most wants.
+    // allSettled never rejects, so this cannot mask the script's own error.
+    if (pending.length) await Promise.allSettled(pending);
+  }
+
+  return { iterations: control.ticks, stopped: control.stopped };
+}

package/src/selfupdate.mjs

@@ -0,0 +1,215 @@
+// Keeping moshcode current without reinstalling it every time.
+//
+// `moshcode update` re-fetches Node, bun and the release tarball on every run,
+// which is fine as a thing you type and wrong as a thing a timer runs every
+// fifteen minutes: it is minutes of network and disk to discover that nothing
+// changed. So the version is checked first and the install only happens when
+// the answer is yes.
+//
+// Automatic updates carry a real cost that is worth stating where the code
+// lives rather than only in a changelog: they propagate a bad release with no
+// one in the loop. A release that breaks DNS reaches every machine on the
+// timer within the interval. That is the trade for not having to think about
+// upgrading, and it is why the timer logs what it did and why `--check` exists
+// as a way to look before leaping.
+
+import { moshcodeVersion } from "./ui.mjs";
+
+export const DEFAULT_INTERVAL = "15min";
+const RELEASE_API = "https://api.github.com/repos/moshcoder/moshcode/releases/latest";
+
+/** The time units systemd.time(7) accepts, longest spelling first so `sec` wins over `s`. */
+const TIME_UNITS = "usec|us|msec|ms|seconds|second|sec|s|minutes|minute|min|m"
+  + "|hours|hour|hr|h|days|day|d|weeks|week|w|months|month|M|years|year|y";
+const TIME_SPAN = new RegExp(`^(\\d+(\\.\\d+)?\\s*(${TIME_UNITS})?\\s*)+$`);
+
+/**
+ * Would systemd accept this as a timer interval?
+ *
+ * Checked here because the value is written into a unit file, and systemd's
+ * reaction to one it cannot parse is to ignore the setting and refuse the whole
+ * timer — leaving it enabled but dead. Case matters: `M` is months and `m` is
+ * minutes.
+ */
+export function validInterval(value) {
+  const text = String(value ?? "").trim();
+  return text === "infinity" || TIME_SPAN.test(text);
+}
+
+/** Strip the `v` and anything after the patch, so `v1.2.3` and `1.2.3` compare. */
+export function normalizeVersion(input) {
+  const match = String(input ?? "").trim().match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? match.slice(1, 4).map(Number) : null;
+}
+
+/**
+ * Is `candidate` newer than `installed`?
+ *
+ * Ordered comparison rather than string inequality, so a rolled-back release
+ * does not read as an upgrade — 0.16.4 against a published 0.16.3 means the
+ * machine is ahead, not behind, and reinstalling would be a downgrade nobody
+ * asked for.
+ */
+export function isNewer(candidate, installed) {
+  const a = normalizeVersion(candidate);
+  const b = normalizeVersion(installed);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return true;
+    if (a[i] < b[i]) return false;
+  }
+  return false;
+}
+
+/** The published version, or null when the question cannot be answered. */
+export async function latestRelease({ fetchImpl = fetch, timeoutMs = 8000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(RELEASE_API, {
+      signal: controller.signal,
+      headers: { accept: "application/vnd.github+json" },
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    return typeof json?.tag_name === "string" ? json.tag_name : null;
+  } catch {
+    // Unreachable registry, rate limit, offline. All the same answer: we do not
+    // know, so we do nothing. A timer that reinstalls on every failed check
+    // would hammer a machine that is merely offline.
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** What an update run should do, without doing any of it. */
+export async function updatePlan({ installed = moshcodeVersion(), fetchImpl = fetch } = {}) {
+  const latest = await latestRelease({ fetchImpl });
+  if (!latest) return { act: false, installed, latest: null, why: "could not reach the release feed" };
+  if (!isNewer(latest, installed)) {
+    return { act: false, installed, latest, why: `already on ${installed}` };
+  }
+  return { act: true, installed, latest, why: `${installed} → ${latest}` };
+}
+
+/**
+ * A systemd timer that checks on an interval.
+ *
+ * `Persistent=true` so a laptop that was asleep at the scheduled moment checks
+ * once when it wakes, rather than skipping until the next one. The service is
+ * oneshot and the timer owns the schedule, which is what makes the interval
+ * editable without touching the command.
+ */
+export function timerUnits({ interval = DEFAULT_INTERVAL, bin = "moshcode" } = {}) {
+  return {
+    "moshcode-update.service": [
+      "[Unit]",
+      "Description=Check for a newer moshcode and install it if there is one",
+      "After=network-online.target",
+      "Wants=network-online.target",
+      "",
+      "[Service]",
+      "Type=oneshot",
+      `ExecStart=/usr/bin/env ${bin} update --if-newer`,
+      "",
+    ].join("\n"),
+    "moshcode-update.timer": [
+      "[Unit]",
+      "Description=Check for a newer moshcode on a schedule",
+      "",
+      "[Timer]",
+      `OnBootSec=${interval}`,
+      `OnUnitActiveSec=${interval}`,
+      // A machine asleep at the scheduled moment checks once on waking rather
+      // than waiting for the next interval.
+      "Persistent=true",
+      "",
+      "[Install]",
+      "WantedBy=timers.target",
+      "",
+    ].join("\n"),
+  };
+}
+
+const USAGE = `moshcode update --if-newer — install only when a newer release exists
+
+  moshcode update --check              say what would happen; change nothing
+  moshcode update --if-newer           install only if the published version is newer
+  moshcode update --timer              print the systemd units for a scheduled check
+  moshcode update --timer --install    write and enable them (needs root)
+  moshcode update --timer --interval 1h
+
+Automatic updates hand a bad release to every machine on the timer within the
+interval, with nobody in the loop. That is the trade.`;
+
+/** The `--check` / `--if-newer` / `--timer` half of `moshcode update`. */
+export async function selfUpdateCommand(args = [], out = console.log, deps = {}) {
+  const { plan = updatePlan, upgrade = null, write = null, runner = null } = deps;
+
+  if (args.includes("--help")) {
+    out(USAGE);
+    return 0;
+  }
+
+  if (args.includes("--timer")) {
+    const at = args.indexOf("--interval");
+    let interval = DEFAULT_INTERVAL;
+    if (at >= 0) {
+      const value = args[at + 1];
+      // `--interval` took whatever followed it, including the next flag. With
+      // `--timer --interval --install` that is the word `--install`, which does
+      // not stop the install — `args.includes("--install")` is still true — so
+      // the units get written with `OnBootSec=--install`, systemd refuses the
+      // timer, and the command still says it is checking on a schedule.
+      if (value === undefined || value.startsWith("-")) {
+        out(`moshcode update: --interval needs a time span, not ${value === undefined ? "nothing" : JSON.stringify(value)} — try --interval 1h`);
+        return 1;
+      }
+      if (!validInterval(value)) {
+        out(`moshcode update: --interval ${JSON.stringify(value)} is not a systemd time span — try 15min, 1h, 2d or 1h30min`);
+        return 1;
+      }
+      interval = value;
+    }
+    const units = timerUnits({ interval });
+    if (!args.includes("--install")) {
+      for (const [name, body] of Object.entries(units)) {
+        out(`--- /etc/systemd/system/${name} ---`);
+        out(body);
+      }
+      out("nothing written. re-run with --install (as root).");
+      return 0;
+    }
+    if (!write || !runner) {
+      out("moshcode update: cannot write units here");
+      return 1;
+    }
+    for (const [name, body] of Object.entries(units)) {
+      await write(`/etc/systemd/system/${name}`, body);
+      out(`  wrote /etc/systemd/system/${name}`);
+    }
+    const reload = await runner("systemctl", ["daemon-reload"]);
+    const enable = await runner("systemctl", ["enable", "--now", "moshcode-update.timer"]);
+    // The units are on disk, but they only run if systemd actually took them.
+    // On a host without systemd (a container, WSL, macOS) or without root, the
+    // enable fails — and saying "checking on a schedule now" then would promise
+    // an auto-update that will never fire. Report the failure instead.
+    if (reload?.ok === false || enable?.ok === false) {
+      out("moshcode update: wrote the units but systemctl could not start the timer — it is not checking on a schedule yet. run `systemctl enable --now moshcode-update.timer` as root.");
+      return 1;
+    }
+    out("checking on a schedule now. `systemctl list-timers moshcode-update` to see when.");
+    return 0;
+  }
+
+  const decision = await plan();
+  out(decision.act
+    ? `update available: ${decision.why}`
+    : `no update: ${decision.why}`);
+
+  // --check reports and stops. Without it, acting is the point.
+  if (args.includes("--check") || !decision.act) return 0;
+  if (!upgrade) return 0;
+  return (await upgrade()) ?? 0;
+}