voidmachine 0.0.0 → 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VoidCorp / Florent Pellegrin
+
+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,5 +1,124 @@
-# voidmachine
+# `voidmachine`
 
-This name is reserved for [Void Machine](https://github.com/voidcorp-core/void-machine).
-Version 0.0.0 installs nothing. The first real release, 4.0.0, is published from CI with
-npm provenance.
+CLI for the [void-machine](https://github.com/voidcorp-core/void-machine): register the marketplace, enable the `harness` core plugin plus the stack packs a project needs, and health-check the setup.
+
+## Quick start
+
+```bash
+# In any project: register the marketplace, enable core + the packs you pick,
+# scaffold .void/config.json, and patch CLAUDE.md / AGENTS.md.
+cd my-project
+npx voidmachine init                          # core only
+npx voidmachine init --pack pack-nextjs --pack pack-monorepo
+
+# Verify the setup (offline-friendly)
+npx voidmachine doctor
+```
+
+Pack names accept any form: `pack-nextjs`, `harness-nextjs`, or `nextjs`.
+
+## Commands
+
+### `cheatsheet`
+
+Discover shipped skills, hooks, agents, specialist contracts and CLI commands,
+with local installation evidence and invocation details.
+
+```bash
+void-machine cheatsheet > cheatsheet.html
+void-machine cheatsheet --format markdown > cheatsheet.md
+void-machine cheatsheet --format json
+```
+
+HTML is a self-contained offline document with catalogue, availability and intent
+views, composable filters, selectable/copyable invocations and print styling.
+The catalogue remains readable without JavaScript. No server, browser launch,
+installation, status refresh or network request is performed by the command.
+
+JSON schema version 1 contains `installation` and stable, sorted `entries` with
+canonical `id`, `type`, `name`, `description`, `pack`, `runtimes`, `invocations`,
+`triggers`, `relatedIds` and per-runtime `availability`. Specialist roles link to
+their agent implementations; they are not two independent capabilities.
+Availability distinguishes `installed`, `absent`, `disabled`, `inactive-pack`,
+`unsupported` and `unknown`, always with a reason. Installed means a receipt-owned
+asset matches, not that runtime execution was verified. No consumer content,
+absolute machine paths or journals are exported. User-global settings and
+marketplace caches are outside the snapshot; missing proof stays unknown.
+
+Project Claude `skillOverrides: { "void-tdd": "off" }` is explicit disabled
+evidence; local settings override project settings. Manual-only visibility is
+not disabled. No Codex home configuration is read. Missing hook wiring is
+reported as undeclared rather than inferred from the hook name.
+
+Exit codes: `0` exported, `1` invalid/unavailable bundled catalogue, `2` invalid
+arguments. Diagnostics go to stderr; a corrupt local install still exports the
+global catalogue with unknown local availability.
+
+### `init`
+
+Sets up the current project:
+
+- Creates `.void/config.json` (pinned plugin versions, stack, paths, TDD modes)
+- Registers the marketplace in `.claude/settings.json` and enables `harness` plus the chosen packs
+- Patches `CLAUDE.md` / `AGENTS.md` (sister docs, cross-referenced)
+
+```
+npx voidmachine init [--pack <name>...] [--all-packs] [--force]
+```
+
+After `init`, restart Claude Code; skills appear as `/harness:<name>` and `/void-<pack>:<name>`.
+
+### `add` / `remove`
+
+Enable or disable a pack on an already-initialized project (updates `.claude/settings.json` and `.void/config.json`).
+
+```
+npx voidmachine add pack-nextjs
+npx voidmachine remove pack-nextjs
+```
+
+### `doctor`
+
+Health-check: `.void/config.json` validity, marketplace + plugins registered in `.claude/settings.json`, the CLAUDE.md block, `jq` (required by the hooks), and version drift against the marketplace HEAD. `--no-remote` runs fully offline. Exit `0` if all checks pass, `1` otherwise.
+
+```
+npx voidmachine doctor [--no-remote]
+```
+
+### `list` / `check` / `update`
+
+`list` shows packs and their detection status; `check` reports version drift; `update` refreshes pinned versions.
+
+### `decisions`
+
+Creates, validates and projects ADRs without a shared counter or generated
+index. Existing decision directories are preserved; new projects default to
+`docs/decisions/`.
+
+```bash
+npx voidmachine decisions new --title "Use X" --slug use-x
+npx voidmachine decisions check [--base <git-ref>]
+npx voidmachine decisions render --format markdown|json
+```
+
+Accepted decision content is immutable. Reverse it with a new record and
+`--supersedes <adr:id>`. A proven repository-local path substitution is the
+only in-place exception; the new target must exist and the surrounding record
+must remain unchanged. Rendered views expose both declared and effective status
+and identify the records that supersede an older decision.
+
+### `install --global`
+
+Escape hatch (rare): installs the `harness` plugin at the user-global level (`~/.claude-plugin/plugins/harness/`) instead of per-project. The recommended flow is `init`.
+
+```
+npx voidmachine install --global [--dry-run]
+```
+
+### `help`
+
+Print the command reference.
+
+## License
+
+MIT.

package/bin/void-harness.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Entry point for the CLI. Every installed command is one of these files, named after the command
+// it serves, so the CLI learns how it was invoked from the file name. The typed name never reaches
+// the process: Node resolves the npm bin symlink to this file, and a Windows shim calls it directly.
+import { basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { run } from '../dist/main.js';
+
+run(basename(fileURLToPath(import.meta.url), '.mjs'), process.argv.slice(2)).catch((err) => {
+  console.error(err?.message ?? err);
+  process.exit(1);
+});

package/bin/void-machine.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Entry point for the CLI. Every installed command is one of these files, named after the command
+// it serves, so the CLI learns how it was invoked from the file name. The typed name never reaches
+// the process: Node resolves the npm bin symlink to this file, and a Windows shim calls it directly.
+import { basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { run } from '../dist/main.js';
+
+run(basename(fileURLToPath(import.meta.url), '.mjs'), process.argv.slice(2)).catch((err) => {
+  console.error(err?.message ?? err);
+  process.exit(1);
+});

package/core-assets/.claude-plugin/plugin.json

@@ -0,0 +1,285 @@
+{
+  "name": "harness",
+  "version": "5.0.0",
+  "description": "VoidCorp universal craftsman skills (void-tdd, void-typescript-strict, void-hexagonal-architecture, void-domain-driven-design, void-functional, void-code-review, void-api-and-interface-design, void-source-driven-development, void-context, void-learn, void-decide, void-claude-md, void-observability, void-security-guidance, ...) plus 12 PreToolUse enforcement hooks (tdd-guard, no-any, protect-sensitive-files, block-dangerous-bash, no-ai-design-slop, ...) and PostToolUse/SessionStart lifecycle hooks (incl. trim-large-output token frugality), five read-only critics including doctrine-critic, native architecture/security/QA specialists, and the void-graph, void-doctor and void-audit gestures, which are skills like everything else.",
+  "author": {
+    "name": "VoidCorp",
+    "email": "florent.pellegrin@voidcorp.io"
+  },
+  "homepage": "https://github.com/voidcorp-core/void-machine",
+  "license": "MIT",
+  "keywords": [
+    "voidcorp",
+    "craftsman",
+    "tdd",
+    "tigerstyle",
+    "harness"
+  ],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce tdd-order claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce no-any claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce no-as-cast claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce no-console claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce no-null claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce control-character claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce no-focused-test claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce boundary-direction claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce test-name claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce protected-file claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce dangerous-command claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce design-slop claude"
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" activation claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" enforce secret-content claude"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle context-continuity claude"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle format claude"
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle trim claude"
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" outcome claude"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle context-continuity claude"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle context-continuity claude"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle herdr-metadata claude"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle context-continuity claude"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle checkpoint-reminder claude"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle checkpoint-audit claude"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle herdr-metadata claude"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" stop claude"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle typecheck claude"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle delegation-result claude"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/_void-hook.mjs\" lifecycle herdr-metadata claude"
+          }
+        ]
+      }
+    ]
+  }
+}