@clemensschartmueller/jev-guard 0.0.0-stage → 0.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jev-guard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# jev-guard installer
 
-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.
+Run `npx --yes @clemensschartmueller/jev-guard@latest` from the project you want to protect. The launcher downloads the jev-guard GitHub Release matching its npm package version, checks the binary against that release's SHA256 manifest, installs it under `~/.jevguard/bin`, and runs `jev-guard init`.
+
+Options after the package name go to `jev-guard init`. For example:
+
+```sh
+npx --yes @clemensschartmueller/jev-guard@latest --agent codex --scope project
+```
+
+See the [project README](https://github.com/ClemensSchartmueller/jev-guard#readme) for supported agents and other installation methods.
+
+## Releasing
+
+The `release.yml` workflow publishes this package only after the matching GitHub Release and its checksum file are uploaded. The npm package version must equal the Git tag without its leading `v`. The package configuration and workflow are ready for public publishing, but npm account setup remains with the owner:
+
+1. Confirm that the npm user or organization scope `@clemensschartmueller` exists and that you can publish within it.
+2. Before merging a version bump, bootstrap `@clemensschartmueller/jev-guard@0.2.0` from `npm/jev-guard` in an owner-authenticated environment with `npm publish --access public`. First review it with `npm pack --dry-run`. The first npm publication must use a version whose GitHub Release already contains `checksums.txt` and matching binaries; `v0.2.0` has those assets. Otherwise the launcher installs but cannot download its binary.
+3. In the new package's npm settings, configure a [GitHub Actions trusted publisher](https://docs.npmjs.com/trusted-publishers/) with organization/user `ClemensSchartmueller`, repository `jev-guard`, workflow filename `release.yml`, and permission to run `npm publish`. Configure it just before the next release: npm requires its first successful trusted publish within two days.
+4. After the other release changes and version bump are merged, tag the next version (for example, `v0.3.0`) and let `release.yml` publish it via OIDC. Verify the npm package is public and installable. A published name/version cannot be reused, so bump the version for each later release.

package/bin/jev-guard.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { spawn } = require('node:child_process');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { version } = require('../package.json');
+
+const RELEASES = 'https://github.com/ClemensSchartmueller/jev-guard/releases/download';
+const MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
+
+function assetName(platform = process.platform, arch = process.arch) {
+  const osName = { linux: 'linux', darwin: 'darwin', win32: 'windows' }[platform];
+  const cpu = { x64: 'amd64', arm64: 'arm64' }[arch];
+  if (!osName || !cpu || (platform === 'win32' && arch !== 'x64')) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}. Use a source build for this platform.`);
+  }
+  return `jev-guard-${osName}-${cpu}${platform === 'win32' ? '.exe' : ''}`;
+}
+
+function expectedDigest(checksums, filename) {
+  const line = checksums.split(/\r?\n/).find((entry) => entry.endsWith(`  ${filename}`) || entry.endsWith(` *${filename}`));
+  const digest = line && /^([a-fA-F0-9]{64})\s+[*]?\S+$/.exec(line)?.[1];
+  if (!digest) throw new Error(`No SHA256 checksum for ${filename} in release checksums.txt`);
+  return digest.toLowerCase();
+}
+
+async function download(url, fetchImpl = fetch) {
+  const response = await fetchImpl(url, { signal: AbortSignal.timeout(60000) });
+  if (!response.ok) throw new Error(`Download failed (${response.status}): ${url}`);
+  if (!response.body) throw new Error(`Empty response: ${url}`);
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of response.body) {
+    bytes += chunk.length;
+    if (bytes > MAX_DOWNLOAD_BYTES) throw new Error(`Download exceeds ${MAX_DOWNLOAD_BYTES} bytes: ${url}`);
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+async function install({ platform = process.platform, arch = process.arch, home = os.homedir(), fetchImpl = fetch } = {}) {
+  const filename = assetName(platform, arch);
+  const base = `${RELEASES}/v${version}`;
+  const checksums = (await download(`${base}/checksums.txt`, fetchImpl)).toString('utf8');
+  const expected = expectedDigest(checksums, filename);
+  const installDir = path.join(home, '.jevguard', 'bin');
+  const target = path.join(installDir, platform === 'win32' ? 'jev-guard.exe' : 'jev-guard');
+
+  // A repeat invocation checks the release checksum, but avoids a binary download.
+  try {
+    const existing = await fs.readFile(target);
+    if (createHash('sha256').update(existing).digest('hex') === expected) return target;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  const binary = await download(`${base}/${filename}`, fetchImpl);
+  if (createHash('sha256').update(binary).digest('hex') !== expected) {
+    throw new Error(`SHA256 mismatch for ${filename}; existing installation was kept`);
+  }
+
+  await fs.mkdir(installDir, { recursive: true });
+  const staged = path.join(installDir, `.${path.basename(target)}-${process.pid}-${Date.now()}.tmp`);
+  try {
+    await fs.writeFile(staged, binary, { mode: 0o755, flag: 'wx' });
+    if (platform !== 'win32') await fs.chmod(staged, 0o755);
+    await fs.rename(staged, target);
+  } finally {
+    await fs.rm(staged, { force: true });
+  }
+  return target;
+}
+
+async function main(args = process.argv.slice(2)) {
+  const binary = await install();
+  const child = spawn(binary, ['init', ...args], { stdio: 'inherit' });
+  child.on('error', (error) => {
+    console.error(`jev-guard: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.on('exit', (code, signal) => {
+    process.exitCode = code ?? (signal ? 1 : 0);
+  });
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(`jev-guard: ${error.message}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { assetName, expectedDigest, install };

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@clemensschartmueller/jev-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Install and initialize jev-guard for your coding agents",
+  "bin": {
+    "jev-guard": "bin/jev-guard.js"
+  },
+  "files": [
+    "bin/jev-guard.js",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClemensSchartmueller/jev-guard.git",
+    "directory": "npm/jev-guard"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test"
+  }
+}