@cerebral-work/lizard 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @cerebral-work/lizard
+
+Installs [lizard](https://github.com/unsigned-gg/lizard), the estate onboarding
+and control TUI, from its GitHub releases.
+
+```sh
+npx @cerebral-work/lizard                       # the latest release, into ~/.local/bin
+npx @cerebral-work/lizard --release v0.5.0      # a specific release
+npx @cerebral-work/lizard --bin-dir ~/bin       # somewhere else
+npx @cerebral-work/lizard --dry-run             # show what would happen
+npx @cerebral-work/lizard status                # installed vs latest; exit 1 if they differ
+```
+
+Then run `lizard`.
+
+## From code
+
+The `@cerebral-work/install` wizard imports this package rather than running
+it. `install()` and `status()` return the same `{ lines, conflicts }` report as
+`@cerebral-work/skills`. Both are async, so a caller can keep its UI moving
+during a download, and both reject with `InstallError`, whose message is meant
+to be shown as is.
+
+```js
+import { install, status } from "@cerebral-work/lizard";
+
+await status({ home });                 // conflicts: 1 if missing or out of date
+await install({ home, dryRun: true });  // { lines: ["would install lizard v0.5.0 ..."], conflicts: 0 }
+await install({ home });                // also takes release and binDir
+```
+
+Types ship in `lib/lizard-install.d.ts`.
+
+## Who can install it
+
+This package is public, but lizard is not. The installer downloads the release
+with your own `gh` login, so it works only if that login can read
+`unsigned-gg/lizard`. Without access, nothing is installed.
+
+## What it does
+
+1. Picks the build for this machine: Linux x86_64, macOS Intel or macOS Apple
+   Silicon. On native Windows, run it from WSL. aarch64 Linux has no build yet.
+2. Checks that `gh` is logged in, then reads the release.
+3. Downloads the tarball and checks its SHA-256 against the digest GitHub
+   publishes for that file. A mismatch, or a release with no digest, stops the
+   install before anything is written.
+4. Installs `lizard` into the bin directory, replacing an older copy, and runs
+   `lizard --version` from there.
+
+`LIZARD_VERSION` and `LIZARD_BIN_DIR` work the same as `--release` and
+`--bin-dir`, and match `scripts/install-lizard.sh`.
+
+## Requirements
+
+Node 22 or later, [`gh`](https://cli.github.com), and `tar`.
+
+## Publishing
+
+Not automated yet. This package is versioned separately from lizard:
+release-please skips commits that touch only `npm/`. A PR that also touches
+other files is counted by its merge commit, so give it a title that doesn't
+bump the version, such as `build(npm): ...`. To ship a change, bump `version` in
+`package.json`, check the file list with `npm pack --dry-run`, then run
+`npm publish` from `npm/`.

package/bin/lizard-install.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { InstallError, main } from "../lib/lizard-install.mjs";
+
+try {
+  process.exitCode = await main();
+} catch (e) {
+  if (!(e instanceof InstallError)) throw e;
+  console.error(`lizard-install: ${e.message}`);
+  process.exitCode = 1;
+}

package/lib/lizard-install.d.ts

@@ -0,0 +1,36 @@
+/** The same report shape as @cerebral-work/skills. */
+export interface Report {
+  lines: string[];
+  conflicts: number;
+}
+
+export interface InstallOptions {
+  /** Default: the current user's home directory. */
+  home?: string;
+  /** Resolve the release and report what would change, writing nothing. */
+  dryRun?: boolean;
+  /** A release tag such as "v0.5.0". Default: the latest release. */
+  release?: string;
+  /** Default: `<home>/.local/bin`. */
+  binDir?: string;
+}
+
+export type StatusOptions = Omit<InstallOptions, "dryRun">;
+
+/** Thrown for every expected failure. The message is meant for the user. */
+export class InstallError extends Error {}
+
+export const REPO: string;
+export const USAGE: string;
+
+/** The release asset's Rust target triple for a Node platform and arch. */
+export function targetFor(platform: string, arch: string): string;
+
+/** Installs lizard; conflicts is always 0. Rejects with InstallError. */
+export function install(opts?: InstallOptions): Promise<Report>;
+
+/** conflicts is 1 when lizard is missing or not the release's version. */
+export function status(opts?: StatusOptions): Promise<Report>;
+
+/** The CLI. Resolves to the process exit code. */
+export function main(argv?: string[], env?: Record<string, string | undefined>): Promise<number>;

package/lib/lizard-install.mjs

@@ -0,0 +1,266 @@
+// lizard-install: puts the unsigned-gg/lizard binary on this machine.
+//
+// The lizard repo is private, so this package holds no binary. The release
+// tarball is downloaded with the user's own `gh` login and checked against the
+// SHA-256 digest GitHub publishes for it before anything is installed.
+//
+// install() and status() return the same { lines, conflicts } report as
+// @cerebral-work/skills, so the @cerebral-work/install wizard can treat every
+// component alike. They are async, so a caller can keep animating while a
+// download runs. Failures reject with InstallError, whose message is meant to
+// be shown to the user as is.
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { chmod, copyFile, mkdir, mkdtemp, readFile, rename, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+export const REPO = "unsigned-gg/lizard";
+
+export const USAGE = `usage: npx @cerebral-work/lizard [status] [options]
+
+Installs lizard from the ${REPO} GitHub releases.
+With status, reports the installed and latest versions; exits 1 if they differ.
+
+  --release <tag>    install this release (default: the latest), e.g. v0.5.0
+  --bin-dir <dir>    install into <dir> (default: ~/.local/bin)
+  --dry-run          resolve the release and print what would change
+  -h, --help         show this help
+
+Env: LIZARD_VERSION (same as --release), LIZARD_BIN_DIR (same as --bin-dir).
+Needs gh, logged in with read access to ${REPO}.`;
+
+// process.platform-process.arch -> Rust target triple of the release asset.
+const TARGETS = {
+  "linux-x64": "x86_64-unknown-linux-gnu",
+  "darwin-x64": "x86_64-apple-darwin",
+  "darwin-arm64": "aarch64-apple-darwin",
+};
+
+export class InstallError extends Error {}
+
+export function targetFor(platform, arch) {
+  const target = TARGETS[`${platform}-${arch}`];
+  if (target) return target;
+  if (platform === "win32") {
+    throw new InstallError("lizard has no native Windows build. Run this from WSL instead.");
+  }
+  if (platform === "linux" && arch === "arm64") {
+    throw new InstallError(
+      "lizard has no aarch64 Linux build yet. Build it from a checkout of unsigned-gg/lizard: cargo install --path .",
+    );
+  }
+  throw new InstallError(`lizard has no build for ${platform}-${arch}.`);
+}
+
+// Resolves { status, stdout, stderr, error }. status is the exit code, or null
+// when the process never ran (error is then set) or was killed by a signal.
+function run(cmd, args) {
+  return new Promise((done) => {
+    execFile(cmd, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err && typeof err.code !== "number") {
+        done({ status: null, stdout, stderr, error: err });
+      } else {
+        done({ status: err ? err.code : 0, stdout, stderr, error: null });
+      }
+    });
+  });
+}
+
+async function gh(args) {
+  const r = await run("gh", args);
+  if (r.error?.code === "ENOENT") {
+    throw new InstallError("the GitHub CLI (gh) is required: https://cli.github.com");
+  }
+  if (r.error) throw r.error;
+  return r;
+}
+
+async function requireGhLogin() {
+  if ((await gh(["auth", "status"])).status !== 0) {
+    throw new InstallError("gh is not logged in. Run: gh auth login");
+  }
+}
+
+// Reads the release once, for both its tag and the asset's digest. A release
+// without a digest for the asset is refused rather than installed unverified.
+async function resolveRelease(tag, assetName) {
+  const r = await gh(["release", "view", ...(tag ? [tag] : []), "--repo", REPO, "--json", "tagName,assets"]);
+  if (r.status !== 0) {
+    throw new InstallError(
+      `could not read ${tag ? `release ${tag}` : "the latest release"} of ${REPO}: ${r.stderr.trim()}\n` +
+        `If the release exists, your gh login needs read access to ${REPO}.`,
+    );
+  }
+  const release = JSON.parse(r.stdout);
+  const asset = release.assets.find((a) => a.name === assetName);
+  if (!asset) {
+    throw new InstallError(`release ${release.tagName} has no ${assetName}.`);
+  }
+  const digest = /^sha256:([0-9a-f]{64})$/.exec(asset.digest ?? "");
+  if (!digest) {
+    throw new InstallError(
+      `release ${release.tagName} publishes no SHA-256 digest for ${assetName}, so it can't be verified. Not installing.`,
+    );
+  }
+  return { tag: release.tagName, sha256: digest[1] };
+}
+
+function locate({ home = homedir(), binDir } = {}) {
+  const dir = resolve(binDir || join(home, ".local", "bin"));
+  return { binDir: dir, dest: join(dir, "lizard") };
+}
+
+// Runs the binary by absolute path, never by name: by name, PATH could
+// resolve to some other lizard than the one at `dest`.
+async function installedVersion(dest) {
+  if (!existsSync(dest)) return null;
+  const v = await run(dest, ["--version"]);
+  if (v.status !== 0) return null;
+  return v.stdout.trim();
+}
+
+const sameVersion = (installed, tag) => installed?.split(/\s+/).pop() === tag.replace(/^v/, "");
+
+/**
+ * Installs lizard into `binDir` (default: `<home>/.local/bin`), replacing an
+ * older copy. `release` pins a tag; the default is the latest release.
+ */
+export async function install({ home, dryRun = false, release, binDir } = {}) {
+  const report = { lines: [], conflicts: 0 };
+  const target = targetFor(process.platform, process.arch);
+  const assetName = `lizard-${target}.tar.gz`;
+  const loc = locate({ home, binDir });
+
+  await requireGhLogin();
+  const rel = await resolveRelease(release, assetName);
+
+  if (dryRun) {
+    report.lines.push(`would install lizard ${rel.tag} (${target}) to ${loc.dest}`);
+    return report;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), "lizard-install-"));
+  try {
+    const dl = await gh(["release", "download", rel.tag, "--repo", REPO, "--pattern", assetName, "--dir", tmp]);
+    if (dl.status !== 0) {
+      throw new InstallError(`could not download ${assetName}:\n${dl.stderr.trim()}`);
+    }
+    const tarball = join(tmp, assetName);
+    const actual = createHash("sha256").update(await readFile(tarball)).digest("hex");
+    if (actual !== rel.sha256) {
+      throw new InstallError(
+        `checksum mismatch for ${assetName}: expected ${rel.sha256}, got ${actual}. Not installing.`,
+      );
+    }
+
+    const tar = await run("tar", ["-xzf", tarball, "-C", tmp]);
+    if (tar.status !== 0) {
+      throw new InstallError(`could not unpack ${assetName}: ${tar.error?.message ?? tar.stderr.trim()}`);
+    }
+    const extracted = join(tmp, "lizard");
+    if (!existsSync(extracted)) {
+      throw new InstallError(`${assetName} has no lizard binary in it.`);
+    }
+
+    // Stage next to the target, then rename over it: a running lizard keeps
+    // its old inode instead of the copy failing with "text file busy".
+    await mkdir(loc.binDir, { recursive: true });
+    const staged = `${loc.dest}.${process.pid}.tmp`;
+    try {
+      await copyFile(extracted, staged);
+      await chmod(staged, 0o755);
+      await rename(staged, loc.dest);
+    } catch (e) {
+      await rm(staged, { force: true });
+      throw e;
+    }
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+
+  const version = await installedVersion(loc.dest);
+  if (!version) {
+    throw new InstallError(`installed ${loc.dest}, but it did not run.`);
+  }
+  report.lines.push(`installed ${version} (${rel.tag}, ${target}) to ${loc.dest}`);
+
+  if (process.platform === "darwin") {
+    report.lines.push(`note: the binary is unsigned. If Gatekeeper blocks it: xattr -d com.apple.quarantine ${loc.dest}`);
+  }
+  const onPath = (process.env.PATH ?? "")
+    .split(delimiter)
+    .filter(Boolean)
+    .some((p) => resolve(p) === loc.binDir);
+  if (!onPath) {
+    report.lines.push(`note: ${loc.binDir} is not on your PATH`);
+  }
+  return report;
+}
+
+/**
+ * Compares the lizard in `binDir` with the latest release (or `release`).
+ * conflicts is 1 when lizard is missing or a different version, else 0.
+ */
+export async function status({ home, release, binDir } = {}) {
+  const report = { lines: [], conflicts: 0 };
+  const target = targetFor(process.platform, process.arch);
+  const loc = locate({ home, binDir });
+
+  await requireGhLogin();
+  const rel = await resolveRelease(release, `lizard-${target}.tar.gz`);
+  const version = await installedVersion(loc.dest);
+
+  if (!version) {
+    report.lines.push(`lizard is not installed at ${loc.dest} (${rel.tag} is available)`);
+    report.conflicts = 1;
+  } else if (!sameVersion(version, rel.tag)) {
+    report.lines.push(`${version} at ${loc.dest}; ${rel.tag} is available`);
+    report.conflicts = 1;
+  } else {
+    report.lines.push(`${version} at ${loc.dest} is current`);
+  }
+  return report;
+}
+
+/** The CLI. Resolves to the process exit code. */
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  // `npx @cerebral-work/lizard -- --dry-run` forwards the `--` itself.
+  const args = argv[0] === "--" ? argv.slice(1) : argv;
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        release: { type: "string" },
+        "bin-dir": { type: "string" },
+        "dry-run": { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+      },
+    });
+  } catch (e) {
+    throw new InstallError(`${e.message}\n\n${USAGE}`);
+  }
+  const { values: opts, positionals } = parsed;
+  if (opts.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (positionals.length > 1 || (positionals.length === 1 && positionals[0] !== "status")) {
+    throw new InstallError(`unknown command: ${positionals.join(" ")}\n\n${USAGE}`);
+  }
+
+  const common = {
+    release: opts.release || env.LIZARD_VERSION || undefined,
+    binDir: opts["bin-dir"] || env.LIZARD_BIN_DIR || undefined,
+  };
+  const report =
+    positionals[0] === "status"
+      ? await status(common)
+      : await install({ ...common, dryRun: Boolean(opts["dry-run"]) });
+  for (const line of report.lines) console.log(line);
+  return report.conflicts > 0 ? 1 : 0;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@cerebral-work/lizard",
+  "version": "0.1.0",
+  "description": "Installer for lizard, the estate onboarding and control TUI. Downloads the release binary with your own gh login and verifies its SHA-256.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unsigned-gg/lizard.git",
+    "directory": "npm"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/lizard-install.d.ts",
+      "default": "./lib/lizard-install.mjs"
+    }
+  },
+  "types": "./lib/lizard-install.d.ts",
+  "bin": {
+    "lizard-install": "bin/lizard-install.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}