codemuster 0.1.0 → 0.2.8

package/LICENSE

@@ -0,0 +1,74 @@
+CodeMuster Personal and Internal Business Use License
+Version 1.0 - September 14, 2026
+
+Copyright (c) 2026 Tim Carter. All rights reserved.
+
+1. Scope
+
+"Software" means CodeMuster's source code, binaries, launcher, skill files,
+and associated documentation supplied under this license. "You" means the
+individual or legal entity exercising the permissions below.
+
+2. Permitted use
+
+Subject to these terms, you may download, install, run, and copy the Software
+free of charge for your own personal use or your organization's internal
+business use. You may inspect and modify the Software solely for those uses.
+Employees and contractors may use it on your behalf subject to these terms.
+Keep this license and the copyright notice with all copies and modifications.
+
+You may use the Software to analyze and improve code that you or your
+organization owns or is authorized to work on, including code for commercial
+products and client projects. You may sell that code and those products and
+use the resulting reports and fixes in your work. Merely using the Software
+does not subject your code, products, reports, or fixes to this license.
+These permissions do not authorize including the Software itself in a
+product or providing its functionality to third parties.
+
+3. Restrictions
+
+Without separate written permission from Tim Carter, you may not:
+
+(a) Sell, resell, rent, lease, sublicense, or charge for the Software or any
+    modified version, in whole or in part.
+(b) Modify, rebrand, bundle, or incorporate the Software into a product or
+    service for sale or other commercial distribution.
+(c) Offer the Software or a modified version as a hosted service, API,
+    subscription, paid auditing service, or other offering that sells access
+    to or the functionality of the Software, including through bundled fees.
+(d) Distribute the Software or modified versions outside your organization,
+    except to contractors solely for the permitted use on your behalf.
+    You may share links to the copyright holder's official distributions.
+(e) Market or offer for sale any of the Software's code, skill files, or
+    documentation as your own product or implementation.
+
+4. Ownership and limits
+
+The Software is licensed, not sold. All rights not expressly granted are
+reserved. This license grants no right to use CodeMuster's name or branding
+to imply ownership, endorsement, or affiliation.
+
+This license restricts use of the Software and its modified versions. It
+does not claim ownership of abstract ideas, concepts, or methods, or impose
+restrictions on independently developed software that does not copy protected
+material from the Software. Rights provided by applicable law that cannot
+be restricted by a license remain unaffected.
+
+Third-party components remain subject to their own licenses. This license
+does not replace those licenses or revoke rights already granted for copies
+previously distributed under another license.
+
+5. Termination
+
+Your permissions under this license terminate automatically if you violate
+its terms. Upon termination, stop using and distributing the Software and
+delete your copies, except where retention is required by applicable law.
+
+6. Disclaimer
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SOFTWARE IS PROVIDED
+"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NONINFRINGEMENT. THE AUTHORS AND COPYRIGHT HOLDERS SHALL NOT BE LIABLE FOR
+ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH
+THE SOFTWARE OR ITS USE, WHETHER IN CONTRACT, TORT, OR OTHERWISE.

package/README.md

@@ -1,37 +1,164 @@
-# 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.
+Audit a codebase with Claude Code, Codex, or the standalone CLI, and see exactly which work
+has been completed.
 
-## Install
+CodeMuster maps C# with Roslyn and TypeScript with the TypeScript compiler, groups code into
+work units, and tracks each unit in a local SQLite ledger. Your agent analyzes each unit in a
+fresh context. A verification pass tries to refute reported findings. Fix mode groups confirmed
+findings by file, runs independent file workers, and creates local commits.
 
-You need Node.js 22 or later.
+Coverage tells you what was analyzed. It does not prove that every defect was found or that a
+fix passes your tests.
+
+## Install and set up
+
+### Use through your coding agent (recommended)
+
+Install the CodeMuster plugin from this repository's marketplace. It bundles the same skill
+for Claude Code and Codex. Run the commands for your agent:
+
+**Claude Code**
 
 ```sh
-npm install -g codemuster
+claude plugin marketplace add TSCarterJr/CodeMuster
+claude plugin install codemuster@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.
+**Codex**
+
+```sh
+codex plugin marketplace add TSCarterJr/CodeMuster
+codex plugin add codemuster@codemuster
+```
+
+Start a new agent session in your repository. The plugin directs the agent to use CodeMuster
+during coding according to `automation` in `.codemuster/config.json`: `off`, `update`
+(default), `review`, or `review_and_fix`. You can also ask for a full audit:
+
+> Audit this repository with CodeMuster.
 
-## Get started
+The skill checks for the CLI, attempts `npm i -g codemuster` if missing, and verifies the
+result. This skill requires stable CLI 0.2.7 or later, checks recovery/validation capabilities, and attempts an explicit update once for an older installation. A version pin is respected. If installation is blocked or fails, it explains the problem and gives the manual
+command. Plugin use runs `init --yes --no-skills` without `--for` to avoid duplicate project skills; this also
+skips project hooks. The plugin supplies its own session/edit context hooks. Review and fix
+mode authorizes scoped repairs and local commits; configure `test_command` for validation.
+See [automatic use](https://github.com/TSCarterJr/CodeMuster/blob/main/docs/usage.md#automatic-use-during-coding)
+for settings, scope, and how existing work is preserved.
+
+This is a repository marketplace; installation does not depend on an official directory
+listing. For local-checkout installation, updates, standalone skill downloads, and publication
+status, see the [distribution guide](https://github.com/TSCarterJr/CodeMuster/blob/main/docs/distribution.md).
+
+### Use the standalone CLI
+
+You need Node.js 22 or later and Git. The CLI ships as a self-contained platform build.
+C# mapping also needs a suitable .NET SDK; TypeScript mapping needs the target repository's
+`typescript` dependency installed. These requirements also apply to plugin use, which needs
+terminal access to your repository. Install and authenticate your chosen coding agent separately.
 
 ```sh
+npm install -g codemuster
 cd your-repo
-codemuster init --yes
+codemuster init --for codex --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.
+Commit `.codemuster/config.json`. Keep `.codemuster/ledger.db` local and ignored.
+`doctor` checks the mappers and suggests setup commands; it does not install dependencies.
+`init` installs project skills and change hooks for your selected agents. Choose a comma-separated
+`--for claude,codex,gemini`, or choose interactively with plain `init`. `--yes` selects all unless
+`--for` or `--no-skills` is given. Use `--no-gitignore`, `--no-hooks`, or `--no-skills` to opt out.
+Reload the agent and approve its hook trust prompt when needed. Hooks track changes without
+running an audit. Standalone `skill install` also supports `opencode` and global installation.
+
+### Use the skill without a plugin
+
+With the CLI installed, run `codemuster skill install --for codex`. The installer supports
+`claude`, `codex`, `gemini`, and `opencode`; add `--global` for all repositories. Use either
+the plugin or a standalone skill copy in a given agent scope to avoid duplicate entries.
+
+## Drive an audit yourself
+
+```sh
+codemuster scan
+codemuster estimate
+codemuster run --agent codex -j 4
+codemuster status
+codemuster report --out audit.md
+```
+
+`scan` maps entry-point call paths and unreached code by default. Use `scan --mode file` for one
+unit per included file. `estimate` approximates pending input tokens. `run` analyzes pending
+units and processes verification work when enabled. Repeat `run` to resume unfinished work.
+
+Use `--path src` with `next`, `estimate`, `run`, `verify`, or `fix` to work on one part of a repository.
+A lens's globs select where its instructions apply; `exclude` removes files from the scan.
+The report includes verification verdicts and recorded fix outcomes. Refuted findings are
+hidden unless you use `--include-refuted`.
+
+## Fix confirmed findings
+
+First configure the repository's validation command. For example, add this property to the
+existing `.codemuster/config.json`:
+
+```json
+"test_command": ["dotnet", "test", "YourSolution.sln"]
+```
+
+Then run:
+
+```sh
+codemuster fix --agent codex -j 4
+```
+
+`-j` is an upper limit, with a default of one. Four files with `-j 10` use at most four workers.
+Each file's confirmed findings go to one worker. All workers, including the default single worker, use isolated Git worktrees;
+the coordinator applies their completed patches, runs the configured tests, commits each changed
+file, and records outcomes in sequence. CodeMuster never pushes the commits.
+
+If tracked files have local edits, the terminal offers to stash them and restore them afterward,
+including their staging state. Use `--stash` for unattended consent. Untracked files stay in
+place, and recovery stashes are retained. Avoid editing the checkout during a fix run.
+
+A failed attempt is retried up to `--attempts N` times in total (default three). Extra file edits
+are rejected and reported with a retained worker path. The untracked Impeccable hook cache is
+excluded from the patch and does not block it. Without `test_command`, CodeMuster warns that
+it is accepting fixes without running your tests.
+
+Retry declines through `fix --retry-declined`. For a repair spanning related files, select an
+exact primary `--path` and `--include-related path/to/caller,path/to/catalog -j 1`; all paths
+must be existing tracked files. The worker stays inside that explicit scope.
+
+After repairs, run `codemuster verify --agent codex --force` to recheck the known findings against
+current code. A `resolved` verdict records the fixed outcome and evidence; a confirmed regression
+reopens it. Then run `codemuster validate` to execute your configured build/test command against
+the final state, even when no fixes remain. Missing validation configuration is a failure.
+Use `scan` and `run` afterward when you need a refreshed audit of all changed code.
+
+## Help and documentation
+
+```sh
+codemuster --help
+codemuster fix --help
+codemuster --version
+```
+
+- [User guide and command reference](https://github.com/TSCarterJr/CodeMuster/blob/main/docs/usage.md): configuration, scope, parallelism, retries, and recovery.
+- [Contributor guide](https://github.com/TSCarterJr/CodeMuster/blob/main/docs/development.md): build, test, and project layout.
+- [Decisions](https://github.com/TSCarterJr/CodeMuster/blob/main/DECISIONS.md) and [implementation checklist](https://github.com/TSCarterJr/CodeMuster/blob/main/MVP-Checklist.md).
 
-## Updates
+These documents describe the repository source; an older installed release may have fewer
+options. The npm launcher checks for updates at most once a day and uses a downloaded update on
+a later invocation. Set `CI` or `CODEMUSTER_NO_UPDATE` to disable automatic checks.
+`codemuster update --check` checks availability without installing; `codemuster update` installs
+an available update. The 0.2.7 launcher supports `CODEMUSTER_VERSION=0.2.0` to select that exact binary, including when a newer build is cached. Unset the variable to resume normal selection; explicit updates are refused while pinned. Install the current launcher first to obtain pin support. Run `skill install` again to refresh an installed skill copy. See the user guide for rollback and ledger precautions.
 
-`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.
+## License
 
-Website: https://codemuster.com
+CodeMuster uses the [Personal and Internal Business Use License](LICENSE).
+You may use and privately modify it for personal work and internal company work,
+including work on commercial products and client code. You may sell your own
+products; you may not sell CodeMuster, commercialize a modified version, or offer
+its functionality as a paid service. Redistribution requires written permission.
+This is a source-available license with use restrictions. See LICENSE for the full terms.

package/lib/launcher.js

@@ -12,6 +12,10 @@ 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 versionsDirectory(stateDir, platform, arch) {
+  return path.join(stateDir, `${platform}-${arch}`, 'versions');
+}
+
 function platformPackage(platform, arch) {
   const name = `${platform}-${arch}`;
   if (!PLATFORMS.has(name)) {
@@ -70,13 +74,13 @@ function splitVersion(version) {
   return [core.split('.'), dash < 0 ? null : version.slice(dash + 1)];
 }
 
-function newestBuild({ versionsDir, bundled, platform }) {
+function newestBuild({ versionsDir, bundled, platform, pinnedVersion }) {
   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));
+  const complete = candidates.filter((candidate) => (!pinnedVersion || candidate.version === pinnedVersion) && fs.existsSync(candidate.binary));
   complete.sort((x, y) => compareVersions(y.version, x.version));
   return complete[0] ?? null;
 }
@@ -90,7 +94,7 @@ function installedVersions(versionsDir) {
 }
 
 function shouldCheckForUpdate({ env, now, lastCheck }) {
-  return !env.CI && !env.CODEMUSTER_NO_UPDATE && (lastCheck === null || now - lastCheck >= DAY);
+  return !env.CI && !env.CODEMUSTER_NO_UPDATE && !env.CODEMUSTER_VERSION && (lastCheck === null || now - lastCheck >= DAY);
 }
 
 function readLastCheck(stateDir) {
@@ -109,7 +113,7 @@ function tar(args) {
 }
 
 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' } });
+  const response = await fetch(url, { signal: AbortSignal.timeout(60000), 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}`);
   }
@@ -118,6 +122,7 @@ async function getJson(url) {
 }
 
 async function installVersion({ registry, version, versionsDir, platform, arch }) {
+  if (!VERSION.test(version)) throw new Error(`invalid version: ${version}`);
   const pkg = platformPackage(platform, arch);
   fs.mkdirSync(versionsDir, { recursive: true });
   const packument = await getJson(`${registry}/${pkg.replace('/', '%2f')}`);
@@ -126,7 +131,7 @@ async function installVersion({ registry, version, versionsDir, platform, arch }
     throw new Error(`${pkg}@${version} is not in the registry`);
   }
 
-  const response = await fetch(dist.tarball);
+  const response = await fetch(dist.tarball, { signal: AbortSignal.timeout(60000) });
   if (!response.ok) {
     throw new Error(`GET ${dist.tarball} returned ${response.status}`);
   }
@@ -185,7 +190,7 @@ async function update({ registry, stateDir, platform, arch, currentVersion, now
     return { latest, installed: null };
   }
 
-  const versionsDir = path.join(stateDir, 'versions');
+  const versionsDir = versionsDirectory(stateDir, platform, arch);
   await installVersion({ registry, version: latest, versionsDir, platform, arch });
   pruneVersions(versionsDir);
   return { latest, installed: latest };
@@ -218,17 +223,73 @@ function bundledBuild(pkg) {
   }
 }
 
+async function updateNow({ args, stateDir, platform, arch, currentVersion, registry = REGISTRY, out = process.stdout }) {
+  const checkOnly = args.includes('--check');
+  let packument;
+  try {
+    packument = await getJson(`${registry}/codemuster`);
+  } catch (error) {
+    out.write(`codemuster: could not reach the npm registry: ${error.message}\n`);
+    return 1;
+  }
+  const latest = (packument['dist-tags'] && packument['dist-tags'].latest) || null;
+  if (latest === null) {
+    out.write('codemuster: the registry named no latest version\n');
+    return 1;
+  }
+
+  if (compareVersions(latest, currentVersion) <= 0) {
+    out.write(`codemuster ${currentVersion} is already the newest\n`);
+    return 0;
+  }
+
+  if (checkOnly) {
+    out.write(`codemuster ${latest} is available; you are on ${currentVersion}. Run codemuster update to install it.\n`);
+    return 0;
+  }
+
+  out.write(`updating codemuster ${currentVersion} to ${latest}\n`);
+  const versionsDir = versionsDirectory(stateDir, platform, arch);
+  try {
+    await installVersion({ registry, version: latest, versionsDir, platform, arch });
+  } catch (error) {
+    out.write(`codemuster: ${latest} could not be installed: ${error.message}\n`);
+    return 1;
+  }
+  pruneVersions(versionsDir);
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'last-update-check'), String(Date.now()));
+  out.write(`codemuster ${latest} is ready; the next command uses it\n`);
+  return 0;
+}
+
 async function main(args, env = process.env) {
+  if ((args[0] === 'update' && args.slice(1).some((arg) => arg === '--help' || arg === '-h'))
+      || (args.length === 2 && args[0] === 'help' && args[1] === 'update')) {
+    process.stdout.write('usage: codemuster update [--check]\n\nUpdate CodeMuster itself through the npm launcher.\n  --check   Show the available version without installing it\n\nAutomatic background checks can be disabled with CI or CODEMUSTER_NO_UPDATE.\n');
+    return 0;
+  }
+
   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 });
+  const versionsDir = versionsDirectory(stateDir, platform, arch);
+  const pinnedVersion = env.CODEMUSTER_VERSION;
+  if (pinnedVersion && !VERSION.test(pinnedVersion)) throw new Error(`invalid version pin: ${pinnedVersion}`);
+  let build = newestBuild({ versionsDir, pinnedVersion, bundled: bundledBuild(platformPackage(platform, arch)), platform });
   if (build === null) {
-    const version = require('../package.json').version;
+    const version = pinnedVersion || 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 });
+    build = newestBuild({ versionsDir, pinnedVersion, bundled: null, platform });
+  }
+
+  if (args[0] === 'update') {
+    if (pinnedVersion) {
+      process.stderr.write(`codemuster is pinned to ${pinnedVersion}; unset CODEMUSTER_VERSION before updating\n`);
+      return 1;
+    }
+    return updateNow({ args: args.slice(1), stateDir, platform, arch, currentVersion: build.version });
   }
 
   if (shouldCheckForUpdate({ env, now: Date.now(), lastCheck: readLastCheck(stateDir) })) {
@@ -242,6 +303,7 @@ async function main(args, env = process.env) {
 
 module.exports = {
   REGISTRY,
+  versionsDirectory,
   binaryName,
   compareVersions,
   installVersion,
@@ -253,4 +315,5 @@ module.exports = {
   shouldCheckForUpdate,
   tar,
   update,
+  updateNow,
 };

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "codemuster",
-  "version": "0.1.0",
+  "version": "0.2.8",
   "description": "CodeMuster: full-coverage codebase audits with a coverage number, driven by your coding agent through one skill.",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "author": "Tim Carter",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TSCarterJr/CodeMuster.git"
   },
-  "homepage": "https://codemuster.com",
+  "homepage": "https://github.com/TSCarterJr/CodeMuster",
   "keywords": [
     "code-audit",
     "code-review",
@@ -33,14 +33,14 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test test/launcher.test.js"
+    "test": "node --test test/launcher.test.js test/plugin.test.js test/release.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"
+    "@codemuster/darwin-arm64": "0.2.8",
+    "@codemuster/darwin-x64": "0.2.8",
+    "@codemuster/linux-arm64": "0.2.8",
+    "@codemuster/linux-x64": "0.2.8",
+    "@codemuster/win32-arm64": "0.2.8",
+    "@codemuster/win32-x64": "0.2.8"
   }
 }