@ejklock/living-docs 0.0.0-stage → 0.26.1

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# living-docs
 
-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.
+npm wrapper, published as `@ejklock/living-docs` (the installed command stays `living-docs`), for the [`living-docs`](https://github.com/ejklock/living-docs-skill) CLI, the
+deterministic layer of Living Docs authoring (`new`, `set`, `supersede`, `index`, `check`, `fmt`, `read`).
+
+The package has no dependencies. It downloads the release binary for your platform from the
+GitHub release matching the package version and verifies its sha256 before using it.
+
+## Install
+
+```bash
+npm install -g @ejklock/living-docs
+living-docs --version
+
+npx @ejklock/living-docs check --plain docs
+```
+
+Supported platforms: macOS and Linux on x64 and arm64 (the four release targets
+`aarch64-apple-darwin`, `x86_64-apple-darwin`, `x86_64-unknown-linux-gnu`,
+`aarch64-unknown-linux-gnu`).
+
+With `--ignore-scripts`, the binary is downloaded and verified on the first run instead.
+
+## Environment
+
+- `LIVING_DOCS_DOWNLOAD_BASE`: replaces `https://github.com/ejklock/living-docs-skill/releases/download/`
+  (a mirror holding `v<version>/living-docs-<target>` and its `.sha256`).
+
+## Fallback
+
+If the download or the checksum fails, install the binary with the script instead:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ejklock/living-docs-skill/main/install.sh | bash
+```

package/bin/living-docs.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { FALLBACK_HINT, ensureBinary } = require('../lib/asset');
+
+async function main() {
+  const binary = await ensureBinary();
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  if (result.signal) process.kill(process.pid, result.signal);
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+main().catch((error) => {
+  process.stderr.write(`living-docs: ${error.message}\n${FALLBACK_HINT}\n`);
+  process.exit(1);
+});

package/lib/asset.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const VENDOR_DIR = path.join(PACKAGE_ROOT, 'vendor');
+const BINARY_PATH = path.join(VENDOR_DIR, 'living-docs');
+const DEFAULT_DOWNLOAD_BASE = 'https://github.com/ejklock/living-docs-skill/releases/download/';
+
+const TARGETS = {
+  'darwin-arm64': 'aarch64-apple-darwin',
+  'darwin-x64': 'x86_64-apple-darwin',
+  'linux-x64': 'x86_64-unknown-linux-gnu',
+  'linux-arm64': 'aarch64-unknown-linux-gnu',
+};
+
+const FALLBACK_HINT =
+  'Install the binary another way instead: curl -fsSL https://raw.githubusercontent.com/ejklock/living-docs-skill/main/install.sh | bash (or run ./install.sh from a checkout).';
+
+/**
+ * The "<platform>-<arch>" key of the running host; LIVING_DOCS_PLATFORM overrides it.
+ * @returns {string}
+ */
+function platformKey() {
+  return process.env.LIVING_DOCS_PLATFORM || `${process.platform}-${process.arch}`;
+}
+
+/**
+ * The release target triple for the running host.
+ * @returns {string} the target triple
+ * @throws {Error} naming the four supported targets when the host is not one of them
+ */
+function resolveTarget() {
+  const key = platformKey();
+  const target = TARGETS[key];
+  if (target) return target;
+  throw new Error(
+    `Unsupported platform ${key}. Supported targets: ${Object.values(TARGETS).join(', ')}. ${FALLBACK_HINT}`,
+  );
+}
+
+/** @returns {string} the package version, which is the release tag without its "v" */
+function packageVersion() {
+  return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+}
+
+/**
+ * The URL directory holding this version's release assets.
+ * LIVING_DOCS_DOWNLOAD_BASE replaces the GitHub releases location.
+ * @returns {string} ends with a slash
+ */
+function releaseUrl() {
+  const base = process.env.LIVING_DOCS_DOWNLOAD_BASE || DEFAULT_DOWNLOAD_BASE;
+  return `${base.replace(/\/*$/, '/')}v${packageVersion()}/`;
+}
+
+async function fetchBytes(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`GET ${url} failed with HTTP ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/**
+ * Throws unless the bytes hash to the digest in a `sha256sum`-style line ("<hex>  <name>").
+ * @param {Buffer} bytes
+ * @param {string} checksumText
+ * @param {string} assetName
+ */
+function verifySha256(bytes, checksumText, assetName) {
+  const expected = checksumText.trim().split(/\s+/)[0].toLowerCase();
+  const actual = crypto.createHash('sha256').update(bytes).digest('hex');
+  if (expected !== actual) {
+    throw new Error(`Checksum mismatch for ${assetName}: expected ${expected}, got ${actual}.`);
+  }
+}
+
+function writeExecutableAtomically(bytes) {
+  fs.mkdirSync(VENDOR_DIR, { recursive: true });
+  const partial = path.join(VENDOR_DIR, `.living-docs.${process.pid}.partial`);
+  try {
+    fs.writeFileSync(partial, bytes, { mode: 0o755 });
+    fs.chmodSync(partial, 0o755);
+    fs.renameSync(partial, BINARY_PATH);
+  } finally {
+    fs.rmSync(partial, { force: true });
+  }
+}
+
+/**
+ * Downloads the host's release asset, verifies its sha256 and moves it into place.
+ * Nothing is left on disk when any step fails.
+ * @returns {Promise<string>} the binary path
+ */
+async function download() {
+  const assetName = `living-docs-${resolveTarget()}`;
+  const url = `${releaseUrl()}${assetName}`;
+  const [bytes, checksum] = await Promise.all([
+    fetchBytes(url),
+    fetchBytes(`${url}.sha256`).then((buffer) => buffer.toString('utf8')),
+  ]);
+  verifySha256(bytes, checksum, assetName);
+  writeExecutableAtomically(bytes);
+  return BINARY_PATH;
+}
+
+/**
+ * The binary path, downloading it first when it is missing.
+ * @returns {Promise<string>}
+ */
+async function ensureBinary() {
+  if (fs.existsSync(BINARY_PATH)) return BINARY_PATH;
+  return download();
+}
+
+module.exports = { FALLBACK_HINT, TARGETS, BINARY_PATH, resolveTarget, releaseUrl, download, ensureBinary };

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@ejklock/living-docs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.26.1",
+  "description": "Deterministic CLI for living-docs authoring: ADRs, issues, research, indexes and checks.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ejklock/living-docs-skill.git"
+  },
+  "homepage": "https://github.com/ejklock/living-docs-skill#readme",
+  "bin": {
+    "living-docs": "bin/living-docs.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts",
+    "README.md"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+
+const { FALLBACK_HINT, download } = require('../lib/asset');
+
+download().catch((error) => {
+  process.stderr.write(`living-docs: could not install the binary.\n${error.message}\n${FALLBACK_HINT}\n`);
+  process.exit(1);
+});