dslinter 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.0.7
+
+[compare changes](https://github.com/jrmybtlr/DSLint/compare/v0.0.6...v0.0.7)
+
+### 🚀 Enhancements
+
+- Implement postinstall script to download prebuilt dslint binaries ([dae3072](https://github.com/jrmybtlr/DSLint/commit/dae3072))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
 ## v0.0.6
 
 [compare changes](https://github.com/jrmybtlr/DSLint/compare/v0.0.5...v0.0.6)
@@ -11,6 +23,10 @@
 - **npm:** package renamed from `@dslinter/dashboard` to **`dslinter`**. Replace the dependency, imports (`dslinter`), and theme import (`dslinter/theme.css`).
 - **CLI:** add **`dslinter`** binary that forwards arguments to **`dslint`** on `PATH` (Rust scanner not bundled).
 
+### Enhancements
+
+- **`postinstall`** attempts to download a **prebuilt `dslint`** for the current platform from **GitHub Releases** (tag `v` + package version). CI: `.github/workflows/release-dslint-binaries.yml`. Opt out with `DSLINT_SKIP_DOWNLOAD=1`.
+
 ## v0.0.5
 
 [compare changes](https://github.com/jrmybtlr/DSLint/compare/v0.0.4...v0.0.5)

package/README.md

@@ -19,28 +19,48 @@ This package is **source-first**: entry points resolve to TypeScript/TSX under `
 
 ## CLI (`npx dslinter`)
 
-This package exposes a **`dslinter` binary** that **forwards every argument to `dslint` on your PATH** (same flags as the Rust CLI: `--json`, `-o`, `--serve`, etc.). It does **not** bundle the Rust scanner.
+The **`dslinter` binary** runs the **`dslint`** scanner with the same flags as the Rust CLI (`--json`, `-o`, `--serve`, etc.).
+
+### Without installing Rust
+
+On **`npm install dslinter`**, a **`postinstall`** script tries to download a **prebuilt `dslint`** for your OS/arch from this repo’s **GitHub Releases**, using the **same tag as the npm version** (for example npm `dslinter@0.0.6` → release **`v0.0.6`** and assets like `dslint-x86_64-unknown-linux-gnu`). The binary is stored under `node_modules/dslinter/vendor/` and `dslinter` / `npx dslinter` prefer it over `PATH`.
+
+**Release workflow:** push git tag `v*` (after bumping the npm version) so [.github/workflows/release-dslint-binaries.yml](https://github.com/jrmybtlr/DSLint/blob/main/.github/workflows/release-dslint-binaries.yml) uploads the platform binaries, **then** publish `dslinter` to npm (or publish after the workflow finishes so installs resolve the assets).
+
+Environment variables:
+
+| Variable | Purpose |
+|----------|---------|
+| `DSLINT_SKIP_DOWNLOAD=1` | Skip postinstall download (air-gapped / you only use `PATH`). |
+| `DSLINT_RELEASE_TAG` | Override release tag (default `v` + `dslinter` version from `package.json`). |
+| `DSLINT_GITHUB_REPO` | Override `owner/repo` for downloads (default `jrmybtlr/DSLint`). |
+
+### How this differs from `oxlint`
+
+**`oxlint`** on npm ships **Node native addons** as **`optionalDependencies`** (`@oxlint/binding-darwin-arm64`, …) built with **napi-rs** — each package is a small prebuilt library loaded by Node.
+
+**`dslint`** is a **standalone executable**. The practical pattern here is **download on install** from **GitHub Releases** (similar in spirit to tools that pull a platform binary once), instead of publishing dozens of `@dslinter/binding-*` packages.
+
+### If there is no matching release asset yet
+
+You’ll see a **warning** during install (install still succeeds) and **`dslinter`** falls back to **`dslint` on your PATH**, or prints install hints if missing:
 
 ```bash
 npx dslinter /path/to/repo --json -o dslint-report.json
 ```
 
-If `dslint` is not installed, you’ll get a short error with install hints (`cargo install dslint` once published, or build from this repo).
-
 | Distribution | How users get `dslint` |
 |--------------|-------------------------|
-| **GitHub Releases** | Attach `dslint` (or `dslint.exe`) per OS/arch to each release; document download + `PATH`. |
-| **crates.io** | Publish the crate as `dslint`; users run `cargo install dslint` (Rust toolchain required). |
-| **npm** | `npx dslinter …` after `dslint` is on `PATH`, or a future dedicated wrapper with prebuilds. |
-
-**Suggested path for this repo:** ship official binaries via **GitHub Releases** (CI builds with `cargo build --release` on `ubuntu`, `macos`, `windows`).
+| **npm + GitHub Releases** | Default: postinstall download when release `vX.Y.Z` includes your platform asset. |
+| **GitHub Releases** | Manual download of `dslint-*` from the release; add to `PATH`. |
+| **crates.io** | `cargo install dslint` once published. |
 
-Typical usage after the CLI is on `PATH`:
+Typical usage:
 
 ```bash
 dslint /path/to/repo --json -o dslint-report.json
 # or --serve for live reload while developing a dashboard
-# or equivalently:
+# or equivalently (vendored or PATH):
 dslinter /path/to/repo --json -o dslint-report.json
 ```
 

package/bin/dslinter.mjs

@@ -1,26 +1,36 @@
 #!/usr/bin/env node
 /**
- * Forwards to the `dslint` Rust CLI on PATH. The published `dslinter` package is
- * primarily the React dashboard; report generation stays in `dslint`.
+ * Runs the `dslint` scanner: prefers a vendored binary from postinstall, else `dslint` on PATH.
  */
 import { spawnSync } from "node:child_process";
-import process from "node:process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { vendorBinaryPath } from "../scripts/resolve-dslint-binary.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, "..");
 
 const args = process.argv.slice(2);
-const child = spawnSync("dslint", args, { stdio: "inherit" });
+
+const vendored = vendorBinaryPath(packageRoot);
+const cmd = vendored && existsSync(vendored) ? vendored : "dslint";
+const child = spawnSync(cmd, args, { stdio: "inherit" });
 
 if (child.error && "code" in child.error && child.error.code === "ENOENT") {
   process.stderr.write(`dslint: command not found.
 
-The dslinter package ships the dashboard UI. JSON reports and scans are produced by the dslint CLI (Rust).
+The dslinter package can download a prebuilt dslint on npm install when a matching
+GitHub release exists (same tag as this package version, e.g. v0.0.6). See:
+https://github.com/jrmybtlr/DSLint/releases
 
-Install dslint, then run dslinter again (this command forwards to dslint):
+Otherwise install dslint on PATH:
 
   cargo install dslint
-  # or build from the DSLint repo:
+  # or from this repo:
   cargo install --path .
 
-More: https://github.com/jrmybtlr/DSLint
+Skip auto-download (air-gapped): DSLINT_SKIP_DOWNLOAD=1
 `);
   process.exit(127);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dslinter",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "DSLinter dashboard UI: playground shell, token wall, and governance panels (consumes dslint-report.json).",
   "license": "Apache-2.0",
   "type": "module",
@@ -46,6 +46,7 @@
   "types": "./src/index.ts",
   "files": [
     "bin",
+    "scripts",
     "src",
     "components.json",
     "README.md",
@@ -85,6 +86,7 @@
     "vitest": "^3.2.4"
   },
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "postinstall": "node ./scripts/ensure-dslint.mjs"
   }
 }

package/scripts/ensure-dslint.mjs

@@ -0,0 +1,96 @@
+/**
+ * Best-effort download of the prebuilt `dslint` CLI for this platform.
+ * Runs on `npm install dslinter` (postinstall). Exits 0 even when the binary
+ * is missing (no release yet / offline) so installs never fail.
+ */
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmod, mkdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { releaseAssetBaseName, vendorBinaryPath } from "./resolve-dslint-binary.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, "..");
+
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readPackageVersion() {
+  const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+function releaseTag(version) {
+  const o = process.env.DSLINT_RELEASE_TAG?.trim();
+  if (o) return o.startsWith("v") ? o : `v${o}`;
+  return `v${version}`;
+}
+
+async function main() {
+  if (process.env.DSLINT_SKIP_DOWNLOAD === "1") return;
+
+  const dest = vendorBinaryPath(packageRoot);
+  if (await pathExists(dest)) return;
+
+  const asset = releaseAssetBaseName();
+  if (!asset) {
+    console.warn(
+      `[dslinter] No prebuilt dslint for ${process.platform}-${process.arch}. Install Rust and put dslint on PATH, or set DSLINT_SKIP_DOWNLOAD=1.`,
+    );
+    return;
+  }
+
+  const version = readPackageVersion();
+  const tag = releaseTag(version);
+  const repo = process.env.DSLINT_GITHUB_REPO?.trim() || "jrmybtlr/DSLint";
+  const url = `https://github.com/${repo}/releases/download/${tag}/${asset}`;
+
+  const vendorDir = join(packageRoot, "vendor");
+  await mkdir(vendorDir, { recursive: true });
+
+  const tmp = `${dest}.part`;
+
+  try {
+    const res = await fetch(url, { redirect: "follow" });
+    if (res.status === 404) {
+      console.warn(
+        `[dslinter] No GitHub release asset at ${url}\n` +
+          `  Create release ${tag} with ${asset} (see .github/workflows/release-dslint-binaries.yml), or install dslint via cargo / PATH.`,
+      );
+      return;
+    }
+    if (!res.ok) {
+      console.warn(`[dslinter] Download failed (${res.status}): ${url}`);
+      return;
+    }
+
+    const buf = Buffer.from(await res.arrayBuffer());
+    writeFileSync(tmp, buf);
+
+    try {
+      if (await pathExists(dest)) unlinkSync(dest);
+    } catch {
+      /* ignore */
+    }
+    renameSync(tmp, dest);
+
+    if (process.platform !== "win32") {
+      await chmod(dest, 0o755);
+    }
+  } catch (err) {
+    console.warn(`[dslinter] Could not download dslint: ${err instanceof Error ? err.message : err}`);
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+await main();

package/scripts/resolve-dslint-binary.mjs

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+
+/**
+ * Maps the current OS/arch to the GitHub release asset basename (must match CI upload names).
+ * @param {NodeJS.Process} [proc]
+ * @returns {string | null}
+ */
+export function releaseAssetBaseName(proc = process) {
+  const { platform, arch } = proc;
+  if (platform === "darwin" && arch === "arm64") return "dslint-aarch64-apple-darwin";
+  if (platform === "darwin" && arch === "x64") return "dslint-x86_64-apple-darwin";
+  if (platform === "linux" && arch === "x64") return "dslint-x86_64-unknown-linux-gnu";
+  if (platform === "linux" && arch === "arm64") return "dslint-aarch64-unknown-linux-gnu";
+  if (platform === "win32" && arch === "x64") return "dslint-x86_64-pc-windows-msvc.exe";
+  return null;
+}
+
+/**
+ * @param {string} packageRoot — directory containing package.json
+ * @param {NodeJS.Process} [proc]
+ */
+export function vendorBinaryPath(packageRoot, proc = process) {
+  const name = proc.platform === "win32" ? "dslint.exe" : "dslint";
+  return join(packageRoot, "vendor", name);
+}

package/src/resolve-dslint-binary.test.ts

@@ -0,0 +1,48 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  releaseAssetBaseName,
+  vendorBinaryPath,
+} from "../scripts/resolve-dslint-binary.mjs";
+
+function proc(platform: string, arch: string): NodeJS.Process {
+  return { platform, arch } as NodeJS.Process;
+}
+
+describe("releaseAssetBaseName", () => {
+  it("maps darwin arm64", () => {
+    expect(releaseAssetBaseName(proc("darwin", "arm64"))).toBe(
+      "dslint-aarch64-apple-darwin",
+    );
+  });
+
+  it("maps linux x64", () => {
+    expect(releaseAssetBaseName(proc("linux", "x64"))).toBe(
+      "dslint-x86_64-unknown-linux-gnu",
+    );
+  });
+
+  it("maps win32 x64", () => {
+    expect(releaseAssetBaseName(proc("win32", "x64"))).toBe(
+      "dslint-x86_64-pc-windows-msvc.exe",
+    );
+  });
+
+  it("returns null for unknown", () => {
+    expect(releaseAssetBaseName(proc("freebsd", "x64"))).toBeNull();
+  });
+});
+
+describe("vendorBinaryPath", () => {
+  it("uses dslint.exe on Windows", () => {
+    expect(vendorBinaryPath(join("/", "pkg"), proc("win32", "x64"))).toBe(
+      join("/", "pkg", "vendor", "dslint.exe"),
+    );
+  });
+
+  it("uses dslint on Unix", () => {
+    expect(vendorBinaryPath(join("/", "pkg"), proc("linux", "x64"))).toBe(
+      join("/", "pkg", "vendor", "dslint"),
+    );
+  });
+});