@joule-sh/code 0.19.0

package/README.md

@@ -0,0 +1,56 @@
+# @joule-sh/code
+
+An agentic coding terminal you can also drive from a web page.
+
+```sh
+npm i -g @joule-sh/code
+joule
+```
+
+The command is `joule`, not `code`: `code` is already VS Code's CLI on most
+machines, and this would silently shadow or lose to it depending on `PATH`
+order. `relay` is installed alongside it, the same pair
+[install.sh](https://github.com/joule-sh/code/blob/main/install.sh) puts on
+your `PATH`.
+
+## What this package is
+
+A wrapper. The binary itself lives in a per-platform package that npm installs
+as an optional dependency and skips everywhere it does not apply:
+
+| platform | package |
+| --- | --- |
+| `linux-x64` | `@joule-sh/code-linux-x64` |
+| `darwin-x64` | `@joule-sh/code-darwin-x64` |
+| `darwin-arm64` | `@joule-sh/code-darwin-arm64` |
+
+Every one of them carries the garbage collector it needs, so there is nothing
+to install alongside. The Linux binary is linked statically against musl and
+needs nothing at all from the machine it lands on.
+
+**There is no Windows build yet.** Installing here prints a message saying so
+and pointing at
+[#173](https://github.com/joule-sh/code/issues/173). Until that lands, joule
+runs on Windows inside WSL.
+
+## If npm skipped the binary
+
+npm has a [long-standing bug](https://github.com/npm/cli/issues/4828) where it
+fails to install the optional dependency it should have. The install step here
+falls back to fetching the platform package from the registry itself, so you
+should never see it. If you do, any of these fixes it:
+
+```sh
+npm install @joule-sh/code-linux-x64
+rm -rf node_modules package-lock.json && npm install
+JOULE_BINARY_PATH=/path/to/the/binaries joule
+```
+
+`JOULE_BINARY_PATH` takes a directory holding `joule`, `relay` and
+`joule-daemon`, or the path of one of them, and overrides resolution entirely.
+
+## Elsewhere
+
+- Source, issues and the shell installer:
+  <https://github.com/joule-sh/code>
+- The VS Code extension: `joule-sh.joule-editor`

package/bin/joule

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";
+require("../lib/shim.js").run("joule");

package/bin/relay

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";
+require("../lib/shim.js").run("relay");

package/lib/download.js

@@ -0,0 +1,84 @@
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+
+function registry() {
+  const configured = (process.env.npm_config_registry || "").trim();
+  const base = configured === "" ? DEFAULT_REGISTRY : configured;
+  return base.endsWith("/") ? base : base + "/";
+}
+
+function metadataUrl(pkg, version) {
+  return registry() + pkg.replace("/", "%2f") + "/" + version;
+}
+
+function checkIntegrity(bytes, integrity) {
+  if (typeof integrity !== "string" || integrity === "") { return ""; }
+  const at = integrity.indexOf("-");
+  const algorithm = integrity.slice(0, at);
+  const expected = integrity.slice(at + 1);
+  if (["sha512", "sha384", "sha256", "sha1"].indexOf(algorithm) < 0) {
+    return "the registry gave an integrity hash this cannot check: " + integrity;
+  }
+  const actual = crypto.createHash(algorithm).update(bytes).digest("base64");
+  if (actual !== expected) {
+    return "the downloaded tarball does not match the integrity hash the registry published for it";
+  }
+  return "";
+}
+
+function untar(tarball, into) {
+  const result = spawnSync("tar", ["-xzf", tarball, "-C", into], { encoding: "utf8" });
+  if (result.error) { return "could not run tar: " + result.error.message; }
+  if (result.status !== 0) { return "tar exited " + result.status + ": " + (result.stderr || "").trim(); }
+  return "";
+}
+
+async function fetchPackage(pkg, version, into) {
+  const url = metadataUrl(pkg, version);
+  let meta = null;
+  try {
+    const response = await fetch(url);
+    if (!response.ok) { return "the registry answered " + response.status + " for " + url; }
+    meta = await response.json();
+  } catch (e) {
+    return "could not reach " + url + ": " + e.message;
+  }
+  const tarball = meta && meta.dist && meta.dist.tarball;
+  if (typeof tarball !== "string" || tarball === "") {
+    return "the registry entry for " + pkg + "@" + version + " names no tarball";
+  }
+  let bytes = null;
+  try {
+    const response = await fetch(tarball);
+    if (!response.ok) { return "the registry answered " + response.status + " for " + tarball; }
+    bytes = Buffer.from(await response.arrayBuffer());
+  } catch (e) {
+    return "could not download " + tarball + ": " + e.message;
+  }
+  const mismatch = checkIntegrity(bytes, meta.dist.integrity);
+  if (mismatch !== "") { return mismatch; }
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "joule-npm-"));
+  try {
+    const file = path.join(work, "package.tgz");
+    fs.writeFileSync(file, bytes);
+    const failure = untar(file, work);
+    if (failure !== "") { return failure; }
+    const unpacked = path.join(work, "package", "bin");
+    if (!fs.existsSync(unpacked)) { return "the tarball for " + pkg + "@" + version + " carries no bin directory"; }
+    fs.rmSync(into, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(into), { recursive: true });
+    fs.cpSync(unpacked, into, { recursive: true });
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+  return "";
+}
+
+module.exports = { registry, metadataUrl, checkIntegrity, fetchPackage, DEFAULT_REGISTRY };

package/lib/platform.js

@@ -0,0 +1,87 @@
+"use strict";
+
+const REPO = "https://github.com/joule-sh/code";
+const SCOPE = "@joule-sh";
+const WRAPPER = SCOPE + "/code";
+const WINDOWS_ISSUE = REPO + "/issues/173";
+const NPM_BUG = "https://github.com/npm/cli/issues/4828";
+const OVERRIDE = "JOULE_BINARY_PATH";
+
+const BUILT = {
+  "linux-x64": SCOPE + "/code-linux-x64",
+  "darwin-x64": SCOPE + "/code-darwin-x64",
+  "darwin-arm64": SCOPE + "/code-darwin-arm64",
+};
+
+const BINARIES = ["joule", "relay", "joule-daemon"];
+const COMMANDS = ["joule", "relay"];
+
+function current() {
+  return process.platform + "-" + process.arch;
+}
+
+function packageFor(id) {
+  return BUILT[id] || "";
+}
+
+function supported() {
+  return Object.keys(BUILT);
+}
+
+function isWindows(id) {
+  return id.startsWith("win32-");
+}
+
+function windowsNotice() {
+  return [
+    "joule: there is no Windows build of joule yet, so there is no binary for this package to install here.",
+    "       " + WINDOWS_ISSUE + " is the ticket for the Windows binary; watch that rather than this package.",
+    "       Until it lands, joule runs on Windows through WSL: open a WSL shell and install it from inside there.",
+  ].join("\n");
+}
+
+function unsupportedNotice(id) {
+  return [
+    "joule: no binary is built for " + id + ".",
+    "       built platforms: " + supported().join(", ") + ".",
+    "       build from source instead: " + REPO + "#build-from-source",
+  ].join("\n");
+}
+
+function missingNotice(id, version) {
+  const pkg = packageFor(id);
+  const pinned = version === "" ? pkg : pkg + "@" + version;
+  return [
+    "joule: " + WRAPPER + " is installed but the binary for " + id + " is not.",
+    "       " + pkg + " should have been installed alongside it as an optional dependency.",
+    "       npm has a long-standing bug where it skips one (" + NPM_BUG + ").",
+    "       Any one of these fixes it:",
+    "         npm install " + pinned,
+    "         remove node_modules and the lockfile, then install again",
+    "         " + OVERRIDE + "=/path/to/the/binaries " + COMMANDS[0],
+  ].join("\n");
+}
+
+function notice(id, version) {
+  if (isWindows(id)) { return windowsNotice(); }
+  if (packageFor(id) === "") { return unsupportedNotice(id); }
+  return missingNotice(id, version);
+}
+
+module.exports = {
+  REPO,
+  SCOPE,
+  WRAPPER,
+  WINDOWS_ISSUE,
+  OVERRIDE,
+  BINARIES,
+  COMMANDS,
+  current,
+  packageFor,
+  supported,
+  isWindows,
+  windowsNotice,
+  unsupportedNotice,
+  missingNotice,
+  notice,
+};

package/lib/postinstall.js

@@ -0,0 +1,154 @@
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const platform = require("./platform.js");
+const resolve = require("./resolve.js");
+const shim = require("./shim.js");
+const download = require("./download.js");
+
+const ROOT = path.join(__dirname, "..");
+const BIN = path.join(ROOT, "bin");
+
+function say(message) {
+  console.log(message);
+}
+
+function warn(message) {
+  console.error(message);
+}
+
+function makeExecutable(dir) {
+  const changed = [];
+  for (const name of platform.BINARIES) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) { continue; }
+    const mode = fs.statSync(file).mode & 0o777;
+    const wanted = mode | 0o111;
+    if (mode === wanted) { continue; }
+    fs.chmodSync(file, wanted);
+    changed.push(name);
+  }
+  return changed;
+}
+
+function signed(file) {
+  const result = spawnSync("codesign", ["--verify", "--strict", file], { encoding: "utf8" });
+  return !result.error && result.status === 0;
+}
+
+function adHocSign(dir) {
+  const failures = [];
+  for (const name of platform.BINARIES) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file) || signed(file)) { continue; }
+    const result = spawnSync("codesign", ["--sign", "-", "--force", file], { encoding: "utf8" });
+    if (result.error) { failures.push(name + ": could not run codesign: " + result.error.message); continue; }
+    if (result.status !== 0) { failures.push(name + ": " + ((result.stderr || "").trim() || "codesign exited " + result.status)); }
+  }
+  return failures;
+}
+
+function writeCommand(command, target) {
+  const link = path.join(BIN, command);
+  let current = "";
+  try { current = fs.readlinkSync(link); } catch (e) { current = ""; }
+  if (target === "") {
+    if (current === "" && fs.existsSync(link) && fs.readFileSync(link, "utf8") === shim.source(command)) { return "shim"; }
+    fs.rmSync(link, { force: true });
+    fs.writeFileSync(link, shim.source(command));
+    fs.chmodSync(link, 0o755);
+    return "shim";
+  }
+  const relative = path.relative(BIN, target);
+  if (current === relative) { return "link"; }
+  fs.rmSync(link, { force: true });
+  fs.symlinkSync(relative, link);
+  return "link";
+}
+
+function restore() {
+  for (const command of platform.COMMANDS) { writeCommand(command, ""); }
+}
+
+function smoke(dir) {
+  const failures = [];
+  for (const name of platform.BINARIES) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) { failures.push(name + " is missing from " + dir); continue; }
+    const result = spawnSync(file, ["--version"], { encoding: "utf8" });
+    if (result.error) { failures.push(name + " will not run: " + result.error.message); continue; }
+    if (result.status === 0) { continue; }
+    const output = ((result.stdout || "") + (result.stderr || "")).trim();
+    const detail = output === "" ? "it exited " + result.status + " without printing anything" : output;
+    failures.push(name + " will not run: " + detail);
+    if (result.status === 137) {
+      failures.push(name + ": 137 is SIGKILL on exec, which on Apple Silicon means the kernel refused the code signature");
+    }
+  }
+  return failures;
+}
+
+async function obtain(id) {
+  const found = resolve.binaryDir(id);
+  if (found.dir !== "") { return found; }
+  const pkg = platform.packageFor(id);
+  const version = resolve.selfVersion();
+  if (version === "") { return found; }
+  say("joule: " + pkg + " was not installed, so it is being fetched from the registry directly.");
+  const failure = await download.fetchPackage(pkg, version, path.join(resolve.vendorDir(), "bin"));
+  if (failure !== "") {
+    warn("joule: fetching " + pkg + "@" + version + " failed: " + failure);
+    return { dir: "", source: "" };
+  }
+  return resolve.binaryDir(id);
+}
+
+async function main(id) {
+  if (platform.isWindows(id)) {
+    warn(platform.windowsNotice());
+    return 1;
+  }
+  if (platform.packageFor(id) === "") {
+    warn(platform.unsupportedNotice(id));
+    return 1;
+  }
+  const found = await obtain(id);
+  if (found.dir === "") {
+    restore();
+    warn(platform.notice(id, resolve.selfVersion()));
+    return 1;
+  }
+  const changed = makeExecutable(found.dir);
+  if (changed.length > 0) {
+    say("joule: restored the execute bit on " + changed.join(", ") + ", which an npm tarball does not carry reliably.");
+  }
+  if (id.startsWith("darwin-")) {
+    const unsigned = adHocSign(found.dir);
+    for (const failure of unsigned) { warn("joule: " + failure); }
+  }
+  const broken = smoke(found.dir);
+  if (broken.length > 0) {
+    restore();
+    for (const failure of broken) { warn("joule: " + failure); }
+    warn("joule: the binaries are installed at " + found.dir + " but will not run, so no command was linked.");
+    warn("joule: please report this at " + platform.REPO + "/issues with the lines above and the output of 'uname -a'.");
+    return 1;
+  }
+  for (const command of platform.COMMANDS) {
+    writeCommand(command, path.join(found.dir, command));
+  }
+  say("joule: " + found.source + " installed to " + found.dir + ", and " + platform.COMMANDS.join(" and ") + " point at it.");
+  return 0;
+}
+
+if (require.main === module) {
+  main(platform.current()).then((code) => { process.exitCode = code; }).catch((e) => {
+    warn("joule: the install step failed: " + e.message);
+    warn("joule: please report this at " + platform.REPO + "/issues with the line above.");
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { main, makeExecutable, writeCommand, restore, smoke, signed, adHocSign };

package/lib/resolve.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const platform = require("./platform.js");
+
+const ROOT = path.join(__dirname, "..");
+const VENDOR = path.join(ROOT, "vendor");
+
+function selfVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8")).version || "";
+  } catch (e) {
+    return "";
+  }
+}
+
+function overrideDir() {
+  const raw = (process.env[platform.OVERRIDE] || "").trim();
+  if (raw === "") { return ""; }
+  if (!fs.existsSync(raw)) {
+    throw new Error("joule: " + platform.OVERRIDE + " is set to " + raw + ", which does not exist.");
+  }
+  return fs.statSync(raw).isDirectory() ? raw : path.dirname(raw);
+}
+
+function packageDir(pkg) {
+  try {
+    return path.dirname(require.resolve(pkg + "/package.json", { paths: [ROOT] }));
+  } catch (e) {
+    return "";
+  }
+}
+
+function holdsBinaries(dir) {
+  if (dir === "") { return false; }
+  return platform.BINARIES.every((name) => fs.existsSync(path.join(dir, name)));
+}
+
+function vendorDir() {
+  return VENDOR;
+}
+
+function binaryDir(id) {
+  if (platform.isWindows(id)) { return { dir: "", source: "" }; }
+  const override = overrideDir();
+  if (override !== "") { return { dir: override, source: platform.OVERRIDE }; }
+  const pkg = platform.packageFor(id);
+  if (pkg !== "") {
+    const installed = path.join(packageDir(pkg), "bin");
+    if (holdsBinaries(installed)) { return { dir: installed, source: pkg }; }
+  }
+  const vendored = path.join(VENDOR, "bin");
+  if (holdsBinaries(vendored)) { return { dir: vendored, source: "vendor" }; }
+  return { dir: "", source: "" };
+}
+
+function binaryPath(name, id) {
+  const found = binaryDir(id);
+  if (found.dir === "") {
+    throw new Error(platform.notice(id, selfVersion()));
+  }
+  const file = path.join(found.dir, name);
+  if (!fs.existsSync(file)) {
+    throw new Error("joule: " + found.source + " has no " + name + " in " + found.dir + ".");
+  }
+  return file;
+}
+
+module.exports = { selfVersion, overrideDir, packageDir, holdsBinaries, vendorDir, binaryDir, binaryPath };

package/lib/shim.js

@@ -0,0 +1,64 @@
+"use strict";
+
+const { spawn } = require("node:child_process");
+const platform = require("./platform.js");
+const resolve = require("./resolve.js");
+
+const IGNORED = ["SIGINT", "SIGQUIT"];
+const FORWARDED = ["SIGTERM", "SIGHUP"];
+
+function listen(signal, handler) {
+  try {
+    process.on(signal, handler);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function run(name) {
+  let target = "";
+  try {
+    target = resolve.binaryPath(name, platform.current());
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+  const child = spawn(target, process.argv.slice(2), { stdio: "inherit" });
+  const attached = [];
+  for (const signal of IGNORED) {
+    const handler = () => {};
+    if (listen(signal, handler)) { attached.push([signal, handler]); }
+  }
+  for (const signal of FORWARDED) {
+    const handler = () => { try { child.kill(signal); } catch (e) { return; } };
+    if (listen(signal, handler)) { attached.push([signal, handler]); }
+  }
+  function release() {
+    for (const pair of attached) { process.removeListener(pair[0], pair[1]); }
+  }
+  child.on("error", (e) => {
+    release();
+    console.error("joule: could not run " + target + ": " + e.message);
+    process.exit(1);
+  });
+  child.on("exit", (code, signal) => {
+    release();
+    if (signal !== null) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code === null ? 1 : code);
+  });
+}
+
+function source(command) {
+  return [
+    "#!/usr/bin/env node",
+    "\"use strict\";",
+    "require(\"../lib/shim.js\").run(\"" + command + "\");",
+    "",
+  ].join("\n");
+}
+
+module.exports = { run, source, IGNORED, FORWARDED };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@joule-sh/code",
+  "version": "0.19.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joule-sh/code.git"
+  },
+  "homepage": "https://github.com/joule-sh/code#readme",
+  "bugs": {
+    "url": "https://github.com/joule-sh/code/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "An agentic coding terminal you can also drive from a web page.",
+  "keywords": [
+    "agent",
+    "cli",
+    "coding",
+    "terminal",
+    "joule"
+  ],
+  "bin": {
+    "joule": "bin/joule",
+    "relay": "bin/relay"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "postinstall": "node lib/postinstall.js"
+  },
+  "optionalDependencies": {
+    "@joule-sh/code-linux-x64": "0.19.0",
+    "@joule-sh/code-darwin-x64": "0.19.0",
+    "@joule-sh/code-darwin-arm64": "0.19.0"
+  }
+}