@specpin/cli 0.0.1

package/README.md

@@ -0,0 +1,54 @@
+# @specpin/cli
+
+The Specpin sidecar CLI, distributed via npm. Installing this package downloads
+the prebuilt Go binary matching your OS and CPU from the matching GitHub Release
+and exposes it as the `specpin` command.
+
+Specpin pins business specifications onto the elements of a running web UI. The
+sidecar serves your repo's `.specs/` over localhost so the Specpin browser
+extension can match and render them. See the
+[project README](https://github.com/lamngockhuong/specpin).
+
+## Install
+
+Global:
+
+```bash
+npm install -g @specpin/cli
+# or
+pnpm add -g @specpin/cli
+```
+
+One-off, no install:
+
+```bash
+npx @specpin/cli serve
+```
+
+## Usage
+
+```bash
+specpin init      # scaffold .specs/ in the current repo
+specpin serve     # serve .specs/ over localhost (prints the bearer token)
+specpin validate  # lint the spec corpus (CI-friendly)
+specpin --help
+```
+
+## How it works
+
+- The npm package version matches the CLI release version. Postinstall fetches
+  `specpin-<os>-<arch>` from `cli-v<version>` on GitHub Releases and verifies its
+  SHA-256 against the published `checksums.txt`.
+- If postinstall is skipped (`--ignore-scripts`) or offline, the binary is
+  fetched and verified the first time you run `specpin`.
+
+### Supported platforms
+
+| OS      | Architectures  |
+| ------- | -------------- |
+| Linux   | amd64, arm64   |
+| macOS   | amd64, arm64   |
+| Windows | amd64          |
+
+On other platforms, build from source: see
+[`apps/cli`](https://github.com/lamngockhuong/specpin/tree/main/apps/cli).

package/bin/specpin.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Launcher for the `specpin` command. Execs the platform-matched Go binary,
+// forwarding args, stdio, and exit code. If the binary is missing (e.g. install
+// ran with --ignore-scripts, or postinstall hit a network error), it is fetched
+// and verified on first use.
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { binaryPath, ensureBinary } from "../scripts/download.mjs";
+
+async function resolveBinary() {
+  const path = binaryPath();
+  if (existsSync(path)) return path;
+  console.error("specpin: downloading binary (first run)...");
+  return ensureBinary();
+}
+
+let bin;
+try {
+  bin = await resolveBinary();
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+const child = spawn(bin, process.argv.slice(2), { stdio: "inherit" });
+child.on("error", (err) => {
+  console.error(`specpin: failed to launch binary (${err.message})`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@specpin/cli",
+  "version": "0.0.1",
+  "description": "Specpin sidecar CLI: init + serve the .specs/ knowledge layer for the Specpin browser extension. Installs the matching prebuilt Go binary.",
+  "keywords": [
+    "specpin",
+    "cli",
+    "sidecar",
+    "specs",
+    "documentation"
+  ],
+  "homepage": "https://github.com/lamngockhuong/specpin/tree/main/apps/cli",
+  "bugs": "https://github.com/lamngockhuong/specpin/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lamngockhuong/specpin.git",
+    "directory": "apps/cli/npm"
+  },
+  "type": "module",
+  "bin": {
+    "specpin": "bin/specpin.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/scripts/download.mjs

@@ -0,0 +1,94 @@
+// Resolves the platform-matched specpin binary and downloads it from the GitHub
+// Release that matches this package's version (tag `cli-v<version>`), verifying
+// the published SHA-256 checksum before it is trusted. Shared by the postinstall
+// step and the bin launcher's lazy fallback (so `--ignore-scripts` installs still
+// self-heal on first run).
+
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = "lamngockhuong/specpin";
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(here, "..");
+
+// process.platform / process.arch -> Go release naming used by release-cli.yml.
+const GOOS = { linux: "linux", darwin: "darwin", win32: "windows" };
+const GOARCH = { x64: "amd64", arm64: "arm64" };
+
+// Combos actually published by the release matrix.
+const SUPPORTED = new Set([
+  "linux-amd64",
+  "linux-arm64",
+  "darwin-amd64",
+  "darwin-arm64",
+  "windows-amd64",
+]);
+
+export function getTarget() {
+  const goos = GOOS[process.platform];
+  const goarch = GOARCH[process.arch];
+  if (!goos || !goarch || !SUPPORTED.has(`${goos}-${goarch}`)) {
+    throw new Error(
+      `specpin: unsupported platform ${process.platform}/${process.arch}. ` +
+        "Prebuilt binaries cover linux/darwin (amd64, arm64) and windows (amd64). " +
+        `Build from source instead: https://github.com/${REPO}/tree/main/apps/cli`,
+    );
+  }
+  const ext = goos === "windows" ? ".exe" : "";
+  return { goos, goarch, asset: `specpin-${goos}-${goarch}${ext}`, ext };
+}
+
+export function binaryPath() {
+  const { ext } = getTarget();
+  return join(pkgRoot, "binary", `specpin${ext}`);
+}
+
+function version() {
+  return JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8")).version;
+}
+
+async function fetchBuffer(url) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) {
+    throw new Error(`specpin: download failed (${res.status} ${res.statusText}) for ${url}`);
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+// Parse a `sha256␠␠filename` line out of checksums.txt for the wanted asset.
+function expectedSha(checksums, asset) {
+  for (const line of checksums.split("\n")) {
+    const [sha, name] = line.trim().split(/\s+/);
+    if (name === asset) return sha;
+  }
+  throw new Error(`specpin: ${asset} not listed in checksums.txt`);
+}
+
+// Download the matched binary into binary/ and verify its checksum. No-op if a
+// verified binary is already present (unless force).
+export async function ensureBinary({ force = false } = {}) {
+  const out = binaryPath();
+  if (!force && existsSync(out)) return out;
+
+  const { asset } = getTarget();
+  const v = version();
+  const base = `https://github.com/${REPO}/releases/download/cli-v${v}`;
+
+  const [bin, checksums] = await Promise.all([
+    fetchBuffer(`${base}/${asset}`),
+    fetchBuffer(`${base}/checksums.txt`).then((b) => b.toString("utf8")),
+  ]);
+
+  const want = expectedSha(checksums, asset);
+  const got = createHash("sha256").update(bin).digest("hex");
+  if (got !== want) {
+    throw new Error(`specpin: checksum mismatch for ${asset}\n  expected ${want}\n  got      ${got}`);
+  }
+
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, bin);
+  chmodSync(out, 0o755);
+  return out;
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,14 @@
+// Runs after `npm install`: fetches the platform-matched specpin binary so the
+// `specpin` command works immediately. Failures here are non-fatal, the bin
+// launcher retries the download on first run, so installs under restricted
+// networks (or `--ignore-scripts`) still self-heal later.
+
+import { ensureBinary } from "./download.mjs";
+
+try {
+  const out = await ensureBinary();
+  console.log(`specpin: installed binary at ${out}`);
+} catch (err) {
+  console.warn(`specpin: postinstall could not fetch the binary (${err.message}).`);
+  console.warn("specpin: it will be downloaded automatically the first time you run `specpin`.");
+}