coordigent 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# Coordigent npm launcher
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs Coordigent's `coord` CLI from npm:
+
+```sh
+npx coordigent connect        # once, or:
+npm i -g coordigent && coordigent connect
+```
+
+(Not on npm yet: `package.json` stays `"private": true` until the trusted publisher is set up;
+see [Publishing](#publishing).)
+
+The package holds one Node file and no binaries. On first run it downloads `coord` and
+`coord-mcp` for this machine from the server's `/install/<artifact>`, checks each against the
+SHA-256 published in `/install/version`, and puts them where the installers do. After that, and on
+every later run, it runs `coord` with the same arguments and exits with its exit code. Because the
+binaries live where `install.sh` puts them, `coord update` and every MCP config keep working
+unchanged.
+
+- **Platforms:** macOS arm64 and x64 (an x64 Node under Rosetta gets the arm64 build), glibc Linux
+  x64 and arm64, Windows x64. Anything else, and Alpine/musl, exits 1 before downloading.
+- **Where:** `~/.tower/bin`, or `%LOCALAPPDATA%\Coordigent\bin` on Windows (as `install.ps1`).
+  `TOWER_BIN_DIR` overrides both. The directory is not added to `PATH`; `coordigent <command>` is.
+- **Which server:** `COORDIGENT_SERVER_URL`, then `TOWER_SERVER_URL`, then the `serverUrl` saved in
+  `~/.tower/config.json`, then `https://coordigent.com`: the order `coord` itself uses. A machine
+  with no config yet gets one naming that server, with no token, as `install.sh` writes.
+- **Checks:** both binaries are downloaded and checked before either is written, so a refusal leaves
+  nothing installed. A digest mismatch, a `429` from the per-address download limit ("Try again in
+  N minute(s)") and an unreachable server each exit 1 with one message. A server that publishes no
+  checksum installs with an "installing unverified" warning, as `install.sh` does. What the
+  checksums do and do not protect against is in
+  [docs/operations.md](../../docs/operations.md#installer).
+- **No install scripts.** Nothing runs at `npm install`; `--ignore-scripts` changes nothing.
+
+## Maintaining it
+
+Tests: `bun test packaging/npm` from the repo root (a local fake server stands in for
+`/install`). CI runs `npm pack --dry-run` on it (`.github/workflows/ci.yml`, job `npm-package`)
+and fails if the tarball holds anything but `bin/coordigent.js`, `README.md` and `package.json`,
+or gains an install-time script. Both that check and the release checks are
+`scripts/release-checks.js`, which is not shipped.
+
+## Publishing
+
+`.github/workflows/publish-npm.yml` publishes on a tag `npm-v<version>` (the `v*` tags publish the
+container image and never touch npm), or by hand from Actions with an existing tag. It uses npm
+trusted publishing: no `NPM_TOKEN`; npm trades the job's GitHub OIDC token for a one-time
+credential, and `npm publish --access public` publishes it (no provenance: npm only attests public source repos, and this repo is private). Before
+publishing, `scripts/release-checks.js release <tag>` refuses, with the reason, when:
+
+- the tag is not exactly `npm-v` plus `package.json`'s `version`;
+- the name is not `coordigent`;
+- `package.json` still has `"private": true`. It stays until the steps below are done, so
+  until then every run of the workflow fails at that check and publishes nothing.
+
+### Turning it on (Ali, once)
+
+1. On npmjs.com, sign in as the account that will own `coordigent`, with two-factor
+   authentication on. (`npm view coordigent` returned 404 on 2026-10-17: the name was free.)
+2. npmjs.com sets a trusted publisher on the package's own settings page, so the package must
+   exist first. If **coordigent** is not yet on npm, publish the current version once by hand:
+   in a clean checkout of `main`, `cd packaging/npm`, delete the `"private": true` line locally
+   (do not commit it), run `npm publish --access public` and approve with 2FA, then
+   `git checkout package.json`. That one version has no provenance; every later one does.
+3. Open **npmjs.com → coordigent → Settings → Trusted Publisher**, choose **GitHub Actions**, and
+   enter: organization or user `startupproj`, repository `coordigent`, workflow filename
+   `publish-npm.yml`, environment empty. Save.
+4. On the same page, under **Publishing access**, choose **Require two-factor authentication and
+   disallow tokens**. Trusted publishing still works; a leaked token cannot publish.
+5. Open a PR that removes `"private": true` from `packaging/npm/package.json`, and bumps
+   `version` if step 2 published the current one. Merge it.
+6. Tag the merge commit and push the tag:
+   `git tag npm-v<version> <commit> && git push origin npm-v<version>`. The workflow publishes;
+   the version page on npmjs.com then shows its provenance, linked to that run.
+
+Each later release: bump `version` in a PR, merge, push `npm-v<version>`.

package/bin/coordigent.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// The npm launcher: `npx coordigent <args>` or `npm i -g` and `coordigent <args>`.
+//
+// It ships no binaries. On first run it downloads coord and coord-mcp for this
+// machine from the server's /install/<artifact>, checks each against the SHA-256
+// in /install/version the way scripts/install.sh does, and puts them where the
+// installers do (~/.tower/bin, or %LOCALAPPDATA%\Coordigent\bin on Windows). Then,
+// and on every later run, it runs `coord <args>`. Because the binaries live where
+// the installers put them, `coord update` and every MCP config keep working.
+//
+// Plain Node with no dependencies and no install scripts: the download happens at
+// run time, so `npm i --ignore-scripts` installs a working launcher.
+"use strict";
+
+const { spawn, execFileSync } = require("node:child_process");
+const { createHash } = require("node:crypto");
+const { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } = require("node:fs");
+const { homedir } = require("node:os");
+const { join } = require("node:path");
+
+const HOSTED_SERVER_URL = "https://coordigent.com";
+const BINARIES = ["coord", "coord-mcp"];
+
+/** A failure the person can act on: printed as one message, exit 1, no stack. */
+class LauncherError extends Error {}
+
+function firstNonEmpty(...values) {
+  return values.find((value) => typeof value === "string" && value.trim() !== "");
+}
+
+function towerDir(env) {
+  return firstNonEmpty(env.TOWER_DIR) ?? join(homedir(), ".tower");
+}
+
+function savedServer(env) {
+  try {
+    return JSON.parse(readFileSync(join(towerDir(env), "config.json"), "utf8")).serverUrl;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The server coord itself would use: COORDIGENT_SERVER_URL, TOWER_SERVER_URL, the saved config, the hosted one. */
+function resolveServer(env = process.env) {
+  const url = firstNonEmpty(env.COORDIGENT_SERVER_URL, env.TOWER_SERVER_URL, savedServer(env)) ?? HOSTED_SERVER_URL;
+  return url.trim().replace(/\/+$/, "");
+}
+
+/** Where the installers put the binaries: TOWER_BIN_DIR, else ~/.tower/bin (install.sh) or %LOCALAPPDATA%\Coordigent\bin (install.ps1). */
+function resolveBinDir(env = process.env, platform = process.platform) {
+  const override = firstNonEmpty(env.TOWER_BIN_DIR);
+  if (override) return override;
+  if (platform === "win32") {
+    return join(firstNonEmpty(env.LOCALAPPDATA) ?? join(homedir(), "AppData", "Local"), "Coordigent", "bin");
+  }
+  return join(homedir(), ".tower", "bin");
+}
+
+function underRosetta() {
+  try {
+    return execFileSync("sysctl", ["-n", "sysctl.proc_translated"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() === "1";
+  } catch {
+    return false;
+  }
+}
+
+function hasGlibc() {
+  return Boolean(process.report?.getReport?.().header?.glibcVersionRuntime);
+}
+
+/** The published artifact suffix for this machine; the same choices install.sh and install.ps1 make. */
+function resolvePlatform({ platform = process.platform, arch = process.arch, rosetta = underRosetta, glibc = hasGlibc } = {}) {
+  const key = `${platform}-${arch}`;
+  switch (key) {
+    case "darwin-arm64":
+      return "darwin-arm64";
+    // An x64 Node under Rosetta on an Apple Silicon Mac: the native build is the right one.
+    case "darwin-x64":
+      return rosetta() ? "darwin-arm64" : "darwin-x64";
+    case "linux-x64":
+    case "linux-arm64":
+      if (!glibc()) {
+        throw new LauncherError(
+          "prebuilt Linux binaries require glibc; Alpine/musl is not supported.\n" +
+            "Use a glibc-based Linux distribution, or run Coordigent from source with Bun."
+        );
+      }
+      return key;
+    case "win32-x64":
+      return "windows-x64";
+    default:
+      throw new LauncherError(
+        `no prebuilt binary for ${key}.\n` +
+          "Supported: macOS arm64 and x64, Linux x64 and arm64 (glibc), Windows x64. Build from source with 'bun run build:cli'."
+      );
+  }
+}
+
+function exeSuffix(platform) {
+  return platform.startsWith("windows-") ? ".exe" : "";
+}
+
+async function request(fetchImpl, url, server) {
+  try {
+    return await fetchImpl(url);
+  } catch (error) {
+    throw new LauncherError(
+      `could not reach ${server} (${error?.cause?.code ?? error?.message ?? error}).\n` +
+        "Check the network, or point at another server with COORDIGENT_SERVER_URL. Nothing was installed."
+    );
+  }
+}
+
+/** The published digests, or {} when the server publishes none (an older server, or one without binaries). */
+async function fetchChecksums(fetchImpl, server) {
+  try {
+    const response = await fetchImpl(`${server}/install/version`);
+    if (!response.ok) return {};
+    const checksums = (await response.json())?.checksums;
+    return checksums && typeof checksums === "object" ? checksums : {};
+  } catch {
+    return {};
+  }
+}
+
+function downloadFailure(response, url, platform) {
+  if (response.status === 429) {
+    const seconds = Number.parseInt(response.headers.get("retry-after") ?? "", 10);
+    const when = Number.isFinite(seconds) ? `in ${Math.max(1, Math.ceil(seconds / 60))} minute(s)` : "later";
+    return new LauncherError(`could not download ${url}\nToo many downloads from this address. Try again ${when}.`);
+  }
+  if (response.status === 404 && platform.startsWith("windows-")) {
+    return new LauncherError(`could not download ${url}\nWindows build not available yet.`);
+  }
+  return new LauncherError(
+    `could not download ${url} (HTTP ${response.status})\nThe server may not be publishing binaries. See docs/operations.md.`
+  );
+}
+
+/**
+ * Downloads and checks every binary before writing any of them, so a refusal
+ * halfway leaves nothing behind. Nothing unverified is ever made executable.
+ */
+async function install({ server, binDir, platform, fetchImpl, log }) {
+  const checksums = await fetchChecksums(fetchImpl, server);
+  const downloads = [];
+  for (const name of BINARIES) {
+    const artifact = `${name}-${platform}${exeSuffix(platform)}`;
+    const url = `${server}/install/${artifact}`;
+    log(`Downloading ${name} (${platform})`);
+    const response = await request(fetchImpl, url, server);
+    if (!response.ok) throw downloadFailure(response, url, platform);
+    const bytes = Buffer.from(await response.arrayBuffer());
+
+    const expected = checksums[artifact];
+    if (typeof expected === "string" && expected !== "") {
+      const actual = createHash("sha256").update(bytes).digest("hex");
+      if (actual !== expected.toLowerCase()) {
+        throw new LauncherError(
+          `${artifact} does not match the checksum the server published.\n` +
+            `  expected ${expected}\n  got      ${actual}\n` +
+            "Nothing was installed. This is what a tampered or truncated download looks like."
+        );
+      }
+    } else {
+      log(`coordigent: the server published no checksum for ${artifact}; installing unverified.`);
+    }
+    downloads.push({ name, bytes });
+  }
+
+  mkdirSync(binDir, { recursive: true });
+  for (const { name, bytes } of downloads) {
+    const target = join(binDir, `${name}${exeSuffix(platform)}`);
+    const tmp = `${target}.download`;
+    writeFileSync(tmp, bytes, { mode: 0o755 });
+    chmodSync(tmp, 0o755);
+    renameSync(tmp, target);
+  }
+  log(`Installed coord and coord-mcp to ${binDir}`);
+}
+
+/** Like install.sh: a machine with no config yet records the server the binaries came from, with no token. */
+function rememberServer(env, server) {
+  const config = join(towerDir(env), "config.json");
+  if (existsSync(config)) return;
+  mkdirSync(towerDir(env), { recursive: true });
+  writeFileSync(config, `{\n  "serverUrl": "${server}"\n}\n`, { mode: 0o600, flag: "wx" });
+}
+
+function run(coord, args) {
+  const child = spawn(coord, args, { stdio: "inherit" });
+  // Ctrl-C reaches coord from the terminal already; stay alive until it exits.
+  process.on("SIGINT", () => {});
+  for (const signal of ["SIGTERM", "SIGHUP"]) process.on(signal, () => child.kill(signal));
+  child.on("error", (error) => {
+    process.stderr.write(`coordigent: could not run ${coord}: ${error.message}\n`);
+    process.exit(1);
+  });
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+async function main(args = process.argv.slice(2), env = process.env) {
+  const log = (line) => process.stderr.write(`${line}\n`);
+  try {
+    const binDir = resolveBinDir(env);
+    // The platform is resolved before anything is fetched or written, like install.sh.
+    const platform = resolvePlatform();
+    const suffix = exeSuffix(platform);
+    const coord = join(binDir, `coord${suffix}`);
+    if (!BINARIES.every((name) => existsSync(join(binDir, `${name}${suffix}`)))) {
+      const server = resolveServer(env);
+      await install({ server, binDir, platform, fetchImpl: fetch, log });
+      try {
+        rememberServer(env, server);
+      } catch {
+        // Optional, as in install.sh: coord login records the server too.
+      }
+    }
+    run(coord, args);
+  } catch (error) {
+    if (!(error instanceof LauncherError)) throw error;
+    log(`coordigent: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { resolvePlatform, resolveServer, resolveBinDir };
+
+if (require.main === module) main();

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "coordigent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Runs Coordigent's coord CLI: downloads the coord and coord-mcp binaries for this machine on first run, checks their SHA-256, and runs coord.",
+  "homepage": "https://coordigent.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/startupproj/coordigent.git",
+    "directory": "packaging/npm"
+  },
+  "bin": {
+    "coordigent": "bin/coordigent.js"
+  },
+  "files": [
+    "bin/coordigent.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}