codemuster 0.0.1 → 0.1.0

package/README.md

@@ -1,11 +1,37 @@
-# codemuster
-
-Full-coverage codebase audits with a real coverage number. The CLI iterates every entry point
-and every file, calls your coding agent (Claude Code, Codex, Gemini CLI, OpenCode) once per unit
-of work in a fresh context, checks it off in a local ledger, and verifies findings before
-reporting them.
-
-This package name is reserved. The first release will install the platform binary so that
-`npx codemuster` works wherever your coding agent is installed.
-
-Source and progress: https://github.com/TSCarterJr/CodeMuster
+# codemuster
+
+Audit every file and every entry point of a codebase with your coding agent (Claude Code, Codex,
+Gemini CLI, or OpenCode), and get a coverage number you can check. CodeMuster maps the code,
+hands your agent one unit of work at a time in a fresh context, tracks every unit in a local
+ledger, and tries to refute each finding before it reaches the report.
+
+## Install
+
+You need Node.js 22 or later.
+
+```sh
+npm install -g codemuster
+```
+
+npm installs a self-contained build for your platform, about 45 MB. Mapping C# also needs the
+.NET SDK, and mapping TypeScript needs the repository's own `typescript` package installed.
+
+## Get started
+
+```sh
+cd your-repo
+codemuster init --yes
+codemuster doctor
+codemuster skill install --for claude
+```
+
+Then ask your agent to audit the repository with CodeMuster. `codemuster` with no arguments lists
+every command.
+
+## Updates
+
+`codemuster` checks npm for a newer version at most once a day, downloads it in the background,
+checks its integrity, and uses it from the next run on. It never updates when the `CI` or
+`CODEMUSTER_NO_UPDATE` environment variable is set.
+
+Website: https://codemuster.com

package/bin/codemuster.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+'use strict';
+
+const launcher = require('../lib/launcher');
+
+launcher.main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(`codemuster: ${error.message}\n`);
+    process.exit(1);
+  });

package/lib/launcher.js

@@ -0,0 +1,256 @@
+'use strict';
+
+const childProcess = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REGISTRY = 'https://registry.npmjs.org';
+const DAY = 24 * 60 * 60 * 1000;
+const KEEP_VERSIONS = 2;
+const PLATFORMS = new Set(['win32-x64', 'win32-arm64', 'darwin-x64', 'darwin-arm64', 'linux-x64', 'linux-arm64']);
+const VERSION = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+
+function platformPackage(platform, arch) {
+  const name = `${platform}-${arch}`;
+  if (!PLATFORMS.has(name)) {
+    throw new Error(`there is no CodeMuster build for ${name}`);
+  }
+
+  return `@codemuster/${name}`;
+}
+
+function binaryName(platform) {
+  return platform === 'win32' ? 'codemuster.exe' : 'codemuster';
+}
+
+function compareVersions(a, b) {
+  const [coreA, preA] = splitVersion(a);
+  const [coreB, preB] = splitVersion(b);
+  for (let i = 0; i < 3; i++) {
+    const difference = Number(coreA[i]) - Number(coreB[i]);
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+
+  if (preA === null || preB === null) {
+    return preA === preB ? 0 : preA === null ? 1 : -1;
+  }
+
+  const partsA = preA.split('.');
+  const partsB = preB.split('.');
+  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+    if (partsA[i] === undefined || partsB[i] === undefined) {
+      return partsA[i] === undefined ? -1 : 1;
+    }
+
+    const numericA = /^\d+$/.test(partsA[i]);
+    const numericB = /^\d+$/.test(partsB[i]);
+    if (numericA && numericB && Number(partsA[i]) !== Number(partsB[i])) {
+      return Number(partsA[i]) - Number(partsB[i]);
+    }
+
+    if (numericA !== numericB) {
+      return numericA ? -1 : 1;
+    }
+
+    if (partsA[i] !== partsB[i]) {
+      return partsA[i] < partsB[i] ? -1 : 1;
+    }
+  }
+
+  return 0;
+}
+
+function splitVersion(version) {
+  const dash = version.indexOf('-');
+  const core = dash < 0 ? version : version.slice(0, dash);
+  return [core.split('.'), dash < 0 ? null : version.slice(dash + 1)];
+}
+
+function newestBuild({ versionsDir, bundled, platform }) {
+  const candidates = bundled ? [{ version: bundled.version, binary: path.join(bundled.dir, 'bin', binaryName(platform)) }] : [];
+  for (const version of installedVersions(versionsDir)) {
+    candidates.push({ version, binary: path.join(versionsDir, version, 'bin', binaryName(platform)) });
+  }
+
+  const complete = candidates.filter((candidate) => fs.existsSync(candidate.binary));
+  complete.sort((x, y) => compareVersions(y.version, x.version));
+  return complete[0] ?? null;
+}
+
+function installedVersions(versionsDir) {
+  try {
+    return fs.readdirSync(versionsDir).filter((entry) => VERSION.test(entry));
+  } catch {
+    return [];
+  }
+}
+
+function shouldCheckForUpdate({ env, now, lastCheck }) {
+  return !env.CI && !env.CODEMUSTER_NO_UPDATE && (lastCheck === null || now - lastCheck >= DAY);
+}
+
+function readLastCheck(stateDir) {
+  try {
+    const value = Number(fs.readFileSync(path.join(stateDir, 'last-update-check'), 'utf8'));
+    return Number.isFinite(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function tar(args) {
+  // Git for Windows puts GNU tar first on PATH, and GNU tar reads "C:" in a path as a remote host.
+  const command = process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe') : 'tar';
+  childProcess.execFileSync(command, args, { stdio: 'pipe' });
+}
+
+async function getJson(url) {
+  const response = await fetch(url, { headers: { accept: 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8' } });
+  if (!response.ok) {
+    throw new Error(`GET ${url} returned ${response.status}`);
+  }
+
+  return response.json();
+}
+
+async function installVersion({ registry, version, versionsDir, platform, arch }) {
+  const pkg = platformPackage(platform, arch);
+  fs.mkdirSync(versionsDir, { recursive: true });
+  const packument = await getJson(`${registry}/${pkg.replace('/', '%2f')}`);
+  const dist = packument.versions && packument.versions[version] && packument.versions[version].dist;
+  if (!dist) {
+    throw new Error(`${pkg}@${version} is not in the registry`);
+  }
+
+  const response = await fetch(dist.tarball);
+  if (!response.ok) {
+    throw new Error(`GET ${dist.tarball} returned ${response.status}`);
+  }
+
+  const tarball = Buffer.from(await response.arrayBuffer());
+  const expected = /sha512-([A-Za-z0-9+\/=]+)/.exec(dist.integrity || '');
+  if (!expected || crypto.createHash('sha512').update(tarball).digest('base64') !== expected[1]) {
+    throw new Error(`integrity check failed for ${pkg}@${version}`);
+  }
+
+  const target = path.join(versionsDir, version);
+  const staging = fs.mkdtempSync(path.join(versionsDir, `.staging-${version}-`));
+  try {
+    const file = path.join(staging, 'build.tgz');
+    fs.writeFileSync(file, tarball);
+    tar(['-xzf', file, '-C', staging]);
+    const binary = path.join(staging, 'package', 'bin', binaryName(platform));
+    if (!fs.existsSync(binary)) {
+      throw new Error(`${pkg}@${version} has no bin/${binaryName(platform)}`);
+    }
+
+    if (platform !== 'win32') {
+      fs.chmodSync(binary, 0o755);
+    }
+
+    try {
+      fs.renameSync(path.join(staging, 'package'), target);
+    } catch (error) {
+      if (!fs.existsSync(target)) {
+        throw error;
+      }
+    }
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+
+  return target;
+}
+
+function pruneVersions(versionsDir) {
+  const versions = installedVersions(versionsDir).sort((x, y) => compareVersions(y, x));
+  for (const version of versions.slice(KEEP_VERSIONS)) {
+    try {
+      fs.rmSync(path.join(versionsDir, version), { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+
+async function update({ registry, stateDir, platform, arch, currentVersion, now }) {
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'last-update-check'), String(now));
+  const packument = await getJson(`${registry}/codemuster`);
+  const latest = (packument['dist-tags'] && packument['dist-tags'].latest) || null;
+  if (latest === null || compareVersions(latest, currentVersion) <= 0) {
+    return { latest, installed: null };
+  }
+
+  const versionsDir = path.join(stateDir, 'versions');
+  await installVersion({ registry, version: latest, versionsDir, platform, arch });
+  pruneVersions(versionsDir);
+  return { latest, installed: latest };
+}
+
+function runBuild(binary, args) {
+  return new Promise((resolve, reject) => {
+    const child = childProcess.spawn(binary, args, { stdio: 'inherit' });
+    // The terminal already delivers Ctrl+C to the build, which cancels cleanly; the launcher only has to outlive it.
+    const handlers = ['SIGINT', 'SIGTERM', 'SIGHUP'].map((signal) => [signal, () => signal !== 'SIGINT' && child.kill(signal)]);
+    handlers.forEach(([signal, handler]) => process.on(signal, handler));
+    const done = () => handlers.forEach(([signal, handler]) => process.off(signal, handler));
+    child.on('error', (error) => {
+      done();
+      reject(error);
+    });
+    child.on('exit', (code) => {
+      done();
+      resolve(code ?? 1);
+    });
+  });
+}
+
+function bundledBuild(pkg) {
+  try {
+    const manifest = require.resolve(`${pkg}/package.json`);
+    return { version: JSON.parse(fs.readFileSync(manifest, 'utf8')).version, dir: path.dirname(manifest) };
+  } catch {
+    return null;
+  }
+}
+
+async function main(args, env = process.env) {
+  const platform = process.platform;
+  const arch = process.arch;
+  const stateDir = path.join(os.homedir(), '.codemuster');
+  const versionsDir = path.join(stateDir, 'versions');
+  let build = newestBuild({ versionsDir, bundled: bundledBuild(platformPackage(platform, arch)), platform });
+  if (build === null) {
+    const version = require('../package.json').version;
+    process.stderr.write(`codemuster: downloading CodeMuster ${version} for ${platform}-${arch}\n`);
+    await installVersion({ registry: REGISTRY, version, versionsDir, platform, arch });
+    build = newestBuild({ versionsDir, bundled: null, platform });
+  }
+
+  if (shouldCheckForUpdate({ env, now: Date.now(), lastCheck: readLastCheck(stateDir) })) {
+    childProcess
+      .spawn(process.execPath, [path.join(__dirname, 'update.js'), stateDir, build.version], { detached: true, stdio: 'ignore', windowsHide: true })
+      .unref();
+  }
+
+  return runBuild(build.binary, args);
+}
+
+module.exports = {
+  REGISTRY,
+  binaryName,
+  compareVersions,
+  installVersion,
+  main,
+  newestBuild,
+  platformPackage,
+  readLastCheck,
+  runBuild,
+  shouldCheckForUpdate,
+  tar,
+  update,
+};

package/lib/update.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const launcher = require('./launcher');
+
+const [stateDir, currentVersion] = process.argv.slice(2);
+
+launcher
+  .update({ registry: launcher.REGISTRY, stateDir, platform: process.platform, arch: process.arch, currentVersion, now: Date.now() })
+  .catch((error) => {
+    try {
+      fs.writeFileSync(path.join(stateDir, 'last-update-error'), String((error && error.stack) || error));
+    } catch {
+    }
+  });

package/package.json

@@ -1,14 +1,46 @@
 {
   "name": "codemuster",
-  "version": "0.0.1",
-  "description": "CodeMuster: full-coverage codebase audits with a coverage number. Every file answers present. Placeholder release; the CLI ships soon.",
+  "version": "0.1.0",
+  "description": "CodeMuster: full-coverage codebase audits with a coverage number, driven by your coding agent through one skill.",
   "license": "MIT",
   "author": "Tim Carter",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TSCarterJr/CodeMuster.git"
   },
-  "homepage": "https://github.com/TSCarterJr/CodeMuster",
-  "keywords": ["code-audit", "code-review", "security", "coverage", "ai", "agent-skill", "claude-code", "codex", "gemini-cli", "opencode"],
-  "files": ["README.md"]
+  "homepage": "https://codemuster.com",
+  "keywords": [
+    "code-audit",
+    "code-review",
+    "security",
+    "coverage",
+    "ai",
+    "agent-skill",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "opencode"
+  ],
+  "bin": {
+    "codemuster": "bin/codemuster.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/launcher.test.js"
+  },
+  "optionalDependencies": {
+    "@codemuster/darwin-arm64": "0.1.0",
+    "@codemuster/darwin-x64": "0.1.0",
+    "@codemuster/linux-arm64": "0.1.0",
+    "@codemuster/linux-x64": "0.1.0",
+    "@codemuster/win32-arm64": "0.1.0",
+    "@codemuster/win32-x64": "0.1.0"
+  }
 }