@tenphi/harnesspm 0.0.0-snapshot.376310a

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+The first release: a proof of concept that covers every scenario of the [specification](docs/spec/README.md) (version 0.7 draft).
+
+- **Team harness:** `init`, `sync`, `sync --check`, `status`, `why` and `check`. Discovery from dependencies, `extends`, one version per package, `exclude`, `replace` and `patch`, the managed block in `AGENTS.md`, skill and rule links, a docs index and `harnesspm.lock.json`.
+- **Added harnesses:** `add`, `remove` and `update`, for a team's or a person's own harness on top of a repository, with user and local scope, project entries and a `SessionStart` hook.
+- **Executables and trust:** scripts, hooks, MCP servers, permissions and sub-agents for Claude Code and Codex; `trust` with `true` or `"pin"`; `run`, `mcp` and `approve`. Nothing that widens an agent's permissions is written when the agent's model runs harnesspm.
+- **Monorepos, `fetch` and `new`:** a block per workspace; downloading the locked harness packages for jobs without an install; templates for every unit kind and for patches.
+- **Package:** published as `@tenphi/harnesspm`; the command is `harnesspm`. Commands that may run without an install use `npx -y @tenphi/harnesspm`, and allow rules for an added harness's scripts match those commands.
+- **Docs index:** built from `.md` and `.mdx` pages, titled by frontmatter `title`, else the first heading. Found by the first pilot, `@tenphi/glaze`.
+- **`check`:** `files` may list entries inside the docs folder, such as `docs/components` or `docs/*.md`, so a package can leave contributor docs out. Found by the `@cube-dev/ui-kit` pilot.
+
+Known limits: `npm install <pkg>` and `pnpm add` do not run the install hook, so run `npx harnesspm sync` after them; Codex outputs are checked against its source and docs only; Yarn Plug'n'Play and Windows are not tested.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tenphi
+
+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

@@ -0,0 +1,88 @@
+# harnesspm — the harness package manager
+
+> **Status: 0.1.0, a working proof of concept of the [specification](docs/spec/README.md) (0.7 draft).** It covers every scenario. Expect changes before 1.0.
+
+harnesspm moves an **AI harness** between projects through npm packages. A harness is everything an AI coding agent needs to work well with a codebase: rules, docs, skills, sub-agents, scripts, hooks, MCP servers and permissions.
+
+## How it works
+
+| Flow | Who | What they do |
+| --- | --- | --- |
+| 📤 **Share** | A library | Adds a `harness/` folder to its npm package. It can pass on the harness of the libraries it builds on (`extends`). |
+| 📥 **Use** | A project | `npm i -D @tenphi/harnesspm` and `npx harnesspm init`. After every install, Claude Code and Codex see the harness of the installed versions. |
+| ➕ **Add on top** | A person | `npx harnesspm add github:me/harness`. A team's or their own workflow, context and tools apply on top, without changing the project's repository. |
+| 🛠️ **Improve** | An agent | `npx harnesspm why <unit>` finds the source. The agent edits it and saves the change the way the owner's rules say, by default with a pull request. |
+
+```
+dependencies (harness/ in node_modules, through extends)
+      ▼
+project      (harnesspm.json, the project's own harness/)          → AGENTS.md block + harnesspm.lock.json, committed
+      ▼
+added        (harnesses you add: your team's, your own)       → per-machine files, never committed
+```
+
+## Quick start
+
+In a project:
+
+```bash
+npm i -D @tenphi/harnesspm
+npx harnesspm init
+```
+
+`init` creates `harnesspm.json` and runs `harnesspm sync` after every full install. Commit `AGENTS.md`, `CLAUDE.md`, `harnesspm.json` and `harnesspm.lock.json`.
+
+In a library, to share its harness:
+
+```bash
+npx harnesspm new rule usage
+npx harnesspm check
+```
+
+Add `"harness"` to the `files` field of `package.json`. To add your own or your team's harness on top of every repository on your machine:
+
+```bash
+npx harnesspm add github:<owner>/<repo>
+```
+
+Node.js 20 or later. `npx harnesspm help` lists every command. [CHANGELOG.md](CHANGELOG.md) lists the changes.
+
+## First targets
+
+- **Agents:** Claude Code and Codex. Other agents that read `AGENTS.md` and `.agents/skills` get the portable parts.
+- **Package managers:** npm, pnpm, Yarn 1 and Yarn 4 (node-modules linker).
+
+## Proof of concept
+
+| Milestone | Scenarios | Status |
+| --- | --- | --- |
+| 1. Team harness: `init`, `sync`, `sync --check`, `status`, `why`, `check` | S1–S6 | ✅ |
+| 2. Added harnesses: `add`, `remove`, `update`, project entries, the `SessionStart` hook | S9, S10, S12 | ✅ |
+| 3. Executables and trust: `run`, hooks, MCP servers, permissions, `approve` | S8 | ✅ |
+| 4. Agents and the rest: Claude Code reading the outputs, monorepos, `fetch`, `new` | S7, S11, S13 | ✅ |
+
+## Read the specification
+
+Start with [docs/spec/README.md](docs/spec/README.md). Every chapter opens with a short summary.
+
+| Chapter | What it covers |
+| --- | --- |
+| [1. Overview](docs/spec/01-overview.md) | How it works, goals, terms, base scenarios |
+| [2. Package format](docs/spec/02-package-format.md) | The `harness/` folder: an Agent Plugins plugin plus the harnesspm extension |
+| [3. Resolution](docs/spec/03-resolution.md) | Layers, `extends`, overrides, versions, monorepos |
+| [4. Outputs](docs/spec/04-outputs.md) | What harnesspm writes for Claude Code and Codex |
+| [5. Executables](docs/spec/05-executables.md) | Scripts, hooks, MCP servers, permissions |
+| [6. Trust and lock](docs/spec/06-trust.md) | What may run, and how changes are reviewed |
+| [7. Added harnesses](docs/spec/07-added.md) | A team's or a person's workflow, context and tools, added on top of a repository |
+| [8. Improving a harness](docs/spec/08-improving.md) | How agents change any harness under its owner's rules |
+| [9. Cloud sessions](docs/spec/09-cloud.md) | Claude Code cloud environments (Codex Cloud is not in v1) |
+| [10. CLI](docs/spec/10-cli.md) | Commands |
+| [11. Standards](docs/spec/11-standards.md) | Which open standards harnesspm uses and where it goes beyond them |
+| [12. Dogfooding](docs/spec/12-dogfooding.md) | How this repository uses and publishes its own harness |
+| [13. Open questions](docs/spec/13-open-questions.md) | Undecided points, and options removed in review |
+
+Background research lives in [docs/research/](docs/research/).
+
+## Name
+
+**harnesspm** stands for *harness package manager*, in the line of npm and pnpm. It is written in lowercase. The npm package and the command are both `harnesspm`, and the extension namespace is `dev.harnesspm`, based on the domain `harnesspm.dev`.

package/dist/added.js

@@ -0,0 +1,189 @@
+// Added harnesses: sources, scopes and project entries (spec chapter 7).
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadHarnessPackage, NS, parseExtension } from './manifest.js';
+import { HarnessError, NPX_ANY, ensureDir, isDir, isFile, isRecord, readJson, readJsonIfExists } from './util.js';
+export const LOCAL_FILE = 'harnesspm.local.json';
+/** harnesspm's own folder for working copies, caches and state. */
+export function harnesspmHome() {
+    return process.env['HARNESSPM_HOME'] ?? path.join(os.homedir(), '.harnesspm');
+}
+export function userConfigFile() {
+    return path.join(harnesspmHome(), 'config.json');
+}
+export function configFileFor(scope, projectDir) {
+    return scope === 'user' ? userConfigFile() : path.join(projectDir, LOCAL_FILE);
+}
+export function readList(file) {
+    const raw = readJsonIfExists(file);
+    if (raw === undefined)
+        return [];
+    if (!isRecord(raw) || (raw['harnesses'] !== undefined && !Array.isArray(raw['harnesses']))) {
+        throw new HarnessError(`${file}: "harnesses" must be an array of sources`);
+    }
+    return (raw['harnesses'] ?? []).filter((s) => typeof s === 'string');
+}
+export function writeList(file, list) {
+    const raw = readJsonIfExists(file);
+    const data = isRecord(raw) ? raw : {};
+    data['harnesses'] = list;
+    ensureDir(path.dirname(file));
+    fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+function expandHome(p) {
+    return p === '~' || p.startsWith('~/') ? path.join(os.homedir(), p.slice(1)) : p;
+}
+function slug(text) {
+    return text.replace(/^@/, '').replace(/[^A-Za-z0-9._-]+/g, '-');
+}
+export function parseSource(spec, cwd = process.cwd()) {
+    if (spec.startsWith('github:')) {
+        const repo = spec.slice('github:'.length).replace(/\.git$/, '');
+        if (!/^[\w.-]+\/[\w.-]+$/.test(repo))
+            throw new HarnessError(`Use github:<owner>/<repo>, not ${spec}`);
+        return { spec, kind: 'git', location: `https://github.com/${repo}.git`, dir: path.join(harnesspmHome(), 'harnesses', slug(repo)), editable: true };
+    }
+    if (spec.startsWith('git:')) {
+        const url = spec.slice('git:'.length);
+        const parts = url.replace(/\.git$/, '').split(/[/:]/).filter(Boolean).slice(-2);
+        return { spec, kind: 'git', location: url, dir: path.join(harnesspmHome(), 'harnesses', slug(parts.join('/'))), editable: true };
+    }
+    if (spec.startsWith('npm:')) {
+        const name = spec.slice('npm:'.length);
+        return { spec, kind: 'npm', location: name, dir: path.join(harnesspmHome(), 'cache', slug(name.replace(/@[^@/]*$/, '')), 'package'), editable: false };
+    }
+    const dir = path.resolve(cwd, expandHome(spec));
+    return { spec: dir, kind: 'folder', location: dir, dir, editable: true };
+}
+function run(cmd, args, cwd) {
+    const result = spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+    return { ok: result.status === 0, out: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() };
+}
+/** Puts the source on this machine. Returns a note for the person. */
+export function fetchSource(source) {
+    if (source.kind === 'folder') {
+        if (!isDir(source.dir))
+            throw new HarnessError(`Folder not found: ${source.dir}`);
+        return undefined;
+    }
+    if (source.kind === 'git') {
+        if (isDir(path.join(source.dir, '.git')))
+            return undefined;
+        ensureDir(path.dirname(source.dir));
+        const result = run('git', ['clone', '--quiet', source.location, source.dir]);
+        if (!result.ok)
+            throw new HarnessError(`git clone ${source.location} failed: ${result.out}`);
+        return `cloned ${source.location} into ${source.dir}`;
+    }
+    return fetchNpm(source);
+}
+function fetchNpm(source) {
+    const cache = path.dirname(source.dir);
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'harnesspm-npm-'));
+    const packed = run('npm', ['pack', source.location, '--silent', '--pack-destination', tmp]);
+    if (!packed.ok)
+        throw new HarnessError(`npm pack ${source.location} failed: ${packed.out}`);
+    const tarball = path.join(tmp, packed.out.split('\n').pop().trim());
+    fs.rmSync(cache, { recursive: true, force: true });
+    ensureDir(cache);
+    const extracted = run('tar', ['-xzf', tarball, '-C', cache]);
+    fs.rmSync(tmp, { recursive: true, force: true });
+    if (!extracted.ok)
+        throw new HarnessError(`Cannot unpack ${source.location}: ${extracted.out}`);
+    return `fetched ${source.location} into ${cache}`;
+}
+/** Brings a source up to date. Never changes a working copy with local work (spec 8.7). */
+export function updateSource(source) {
+    if (source.kind === 'folder')
+        return `${source.spec}: a folder, used as it is`;
+    if (source.kind === 'npm')
+        return fetchNpm(source);
+    if (!isDir(path.join(source.dir, '.git'))) {
+        fetchSource(source);
+        return `${source.spec}: cloned`;
+    }
+    const dirty = run('git', ['status', '--porcelain'], source.dir);
+    if (dirty.out !== '')
+        return `${source.spec}: skipped, the working copy has uncommitted changes`;
+    const ahead = run('git', ['rev-list', '--count', '@{upstream}..HEAD'], source.dir);
+    if (ahead.ok && ahead.out !== '0')
+        return `${source.spec}: skipped, the working copy has ${ahead.out} unpushed commits`;
+    const pulled = run('git', ['pull', '--quiet', '--ff-only'], source.dir);
+    return pulled.ok ? `${source.spec}: up to date` : `${source.spec}: pull failed: ${pulled.out}`;
+}
+/** `<host>/<path>` of a repository's `origin` remote, without `.git`, for SSH and HTTPS URLs. */
+export function remoteKey(projectDir) {
+    const result = run('git', ['remote', 'get-url', 'origin'], projectDir);
+    if (!result.ok || result.out === '')
+        return undefined;
+    return normalizeRemote(result.out);
+}
+export function normalizeRemote(url) {
+    let rest = url.trim().replace(/\.git$/, '').replace(/\/$/, '');
+    const scp = /^[^@/]+@([^:/]+):(.+)$/.exec(rest);
+    if (scp)
+        return `${scp[1]}/${scp[2].replace(/^\/+/, '')}`;
+    rest = rest.replace(/^[a-z+]+:\/\//i, '').replace(/^[^@/]+@/, '');
+    const [hostPort, ...segments] = rest.split('/');
+    return [hostPort.replace(/:\d+$/, ''), ...segments].join('/');
+}
+function loadEntry(pkg, key) {
+    if (key === undefined)
+        return undefined;
+    const rel = pkg.ext.projects[key];
+    if (rel === undefined)
+        return undefined;
+    const dir = path.resolve(pkg.harnessDir, rel);
+    if (!isDir(dir))
+        return undefined;
+    // An entry has the layout of harness/. Its optional plugin.json uses the harness's name and holds overrides.
+    const manifest = path.join(dir, 'plugin.json');
+    const raw = isFile(manifest) ? readJson(manifest) : {};
+    const data = isRecord(raw) ? raw : {};
+    if (data['name'] !== undefined && data['name'] !== pkg.plugin) {
+        throw new HarnessError(`${manifest}: "name" must be "${pkg.plugin}", the name of its harness`);
+    }
+    const problems = [];
+    const ext = parseExtension(data, problems);
+    return { ...pkg, name: `${pkg.name} (entry ${key})`, dir, harnessDir: dir, ext: { ...ext, projects: {} }, problems };
+}
+/** Added harnesses in order: user scope first, then local scope, each as listed. */
+export function loadAdded(projectDir, warnings) {
+    const result = [];
+    const key = projectDir !== undefined ? remoteKey(projectDir) : undefined;
+    const scopes = projectDir !== undefined ? ['user', 'local'] : ['user'];
+    for (const scope of scopes) {
+        for (const spec of readList(configFileFor(scope, projectDir ?? ''))) {
+            const source = parseSource(spec);
+            if (!isFile(path.join(source.dir, 'harness', 'plugin.json'))) {
+                warnings.push(`${spec} is not on this machine yet. Run \`${NPX_ANY} update\`.`);
+                continue;
+            }
+            const pkg = loadHarnessPackage(source.dir, 'added');
+            if (pkg.name === path.basename(source.dir))
+                pkg.name = spec;
+            const entry = loadEntry(pkg, key);
+            result.push({ source, scope, pkg, ...(entry ? { entry } : {}) });
+        }
+    }
+    return result;
+}
+/**
+ * Who runs harnesspm (spec 6.2, rule 4). Claude Code marks model commands (`AI_AGENT=…_agent`) and hooks
+ * (`…_harness`). Codex sets `CODEX_CI=1` and `CODEX_TOOL_CALL_ID` only in commands the model runs.
+ */
+export function caller(env = process.env) {
+    const agent = env['AI_AGENT'] ?? '';
+    if (agent.endsWith('_agent'))
+        return 'model';
+    if (agent.endsWith('_harness'))
+        return 'hook';
+    if (agent === '' && env['CLAUDECODE'] === '1')
+        return 'model';
+    if (env['CODEX_CI'] === '1' || (env['CODEX_TOOL_CALL_ID'] ?? '') !== '')
+        return 'model';
+    return 'person';
+}
+export const RULES_DIR = path.join(NS, 'rules');

package/dist/check.js

@@ -0,0 +1,160 @@
+// harnesspm check: validate a harness before it is published (spec 2.10).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseFrontmatter, stringList } from './frontmatter.js';
+import { discoverExecUnits } from './exec-units.js';
+import { discoverUnits, loadHarnessPackage, NS, ruleMeta } from './manifest.js';
+import { HarnessError, isDir, isFile, isRecord, readJsonIfExists, readText, relPosix } from './util.js';
+const SECRET_PATTERNS = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, 'a private key'],
+    [/\bgh[pousr]_[A-Za-z0-9]{30,}\b/, 'a GitHub token'],
+    [/\bsk-[A-Za-z0-9_-]{20,}\b/, 'an API key'],
+    [/\bAKIA[0-9A-Z]{16}\b/, 'an AWS access key'],
+    [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/, 'a Slack token'],
+];
+function inside(dir, file) {
+    const rel = path.relative(dir, file);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+function walkFiles(dir) {
+    const files = [];
+    const walk = (current) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile())
+                files.push(full);
+        }
+    };
+    if (isDir(dir))
+        walk(dir);
+    return files.sort();
+}
+/** `target` is a package root, or a harness/ folder, or an added harness folder. */
+export function checkHarness(target) {
+    let root = path.resolve(target);
+    if (path.basename(root) === 'harness' && isFile(path.join(root, 'plugin.json')))
+        root = path.dirname(root);
+    const pkg = loadHarnessPackage(root, 'project');
+    if (!pkg)
+        throw new HarnessError(`No harness found: ${relPosix(process.cwd(), path.join(root, 'harness', 'plugin.json'))} does not exist`);
+    const errors = [...pkg.problems];
+    const warnings = [];
+    const show = (file) => relPosix(root, file);
+    const pkgJson = readJsonIfExists(path.join(root, 'package.json'));
+    if (isRecord(pkgJson) && Array.isArray(pkgJson['files'])) {
+        const files = pkgJson['files'].filter((f) => typeof f === 'string').map((f) => f.replace(/^\.\//, '').replace(/\/$/, ''));
+        if (!files.includes('harness'))
+            errors.push('package.json: "files" must include "harness"');
+        if (pkg.ext.docs !== undefined) {
+            const docsRel = relPosix(root, path.resolve(pkg.harnessDir, pkg.ext.docs));
+            // The folder itself, a parent of it, or entries inside it, such as `docs/components` or `docs/*.md`.
+            const covers = (f) => docsRel === f || docsRel.startsWith(`${f}/`) || f.startsWith(`${docsRel}/`);
+            if (!files.some(covers))
+                errors.push(`package.json: "files" must include the docs folder "${docsRel}", or entries inside it`);
+        }
+    }
+    const checkPath = (label, rel, mustExist) => {
+        const full = path.resolve(pkg.harnessDir, rel);
+        if (!inside(root, full))
+            errors.push(`${label}: ${rel} points outside the package`);
+        else if (mustExist === 'file' ? !isFile(full) : !isDir(full))
+            errors.push(`${label}: ${rel} does not exist`);
+    };
+    for (const [id, file] of Object.entries(pkg.ext.replace))
+        checkPath(`replace ${id}`, file, 'file');
+    for (const [id, file] of Object.entries(pkg.ext.patch)) {
+        checkPath(`patch ${id}`, file, 'file');
+        if (!id.includes(':rules/'))
+            errors.push(`patch ${id}: patches work on rules only`);
+    }
+    if (pkg.ext.docs !== undefined)
+        checkPath('docs', pkg.ext.docs, 'dir');
+    for (const [name, def] of Object.entries(pkg.ext.scripts)) {
+        if (!def.file.startsWith('./'))
+            errors.push(`script ${name}: "file" must start with "./"`);
+        checkPath(`script ${name}`, def.file, 'file');
+    }
+    for (const [remote, dir] of Object.entries(pkg.ext.projects))
+        checkPath(`project entry ${remote}`, dir, 'dir');
+    const overrideFiles = new Set([...Object.values(pkg.ext.replace), ...Object.values(pkg.ext.patch)].map((f) => path.resolve(pkg.harnessDir, f)));
+    const units = discoverUnits(pkg, overrideFiles);
+    let alwaysOnBytes = 0;
+    for (const rule of units.rules) {
+        try {
+            const text = readText(rule.file);
+            const meta = ruleMeta(text, rule.name, rule.file);
+            const { data } = parseFrontmatter(text, rule.file);
+            if (data['paths'] !== undefined && !stringList(data['paths']))
+                errors.push(`${show(rule.file)}: "paths" must be a string or a list of strings`);
+            if (data['description'] !== undefined && typeof data['description'] !== 'string')
+                errors.push(`${show(rule.file)}: "description" must be a string`);
+            if (meta.activation === 'always')
+                alwaysOnBytes += Buffer.byteLength(meta.body);
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
+    }
+    for (const skill of units.skills) {
+        const file = path.join(skill.dir, 'SKILL.md');
+        try {
+            const { data, hasFrontmatter } = parseFrontmatter(readText(file), file);
+            if (!hasFrontmatter)
+                errors.push(`${show(file)}: needs frontmatter with "name" and "description"`);
+            if (data['name'] !== skill.name)
+                errors.push(`${show(file)}: "name" must be "${skill.name}", the folder name`);
+            if (typeof data['description'] !== 'string' || data['description'].trim() === '')
+                errors.push(`${show(file)}: needs a "description"`);
+            if (!skill.name.startsWith(`${pkg.plugin}-`) && skill.name !== pkg.plugin) {
+                warnings.push(`skill "${skill.name}" should start with the plugin name, such as "${pkg.plugin}-${skill.name}"`);
+            }
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
+    }
+    let jsonOk = true;
+    for (const json of ['mcp.json', path.join(NS, 'hooks.json'), path.join(NS, 'permissions.json')]) {
+        const file = path.join(pkg.harnessDir, json);
+        if (isFile(file)) {
+            try {
+                JSON.parse(readText(file));
+            }
+            catch (error) {
+                jsonOk = false;
+                errors.push(`${show(file)}: ${error.message}`);
+            }
+        }
+    }
+    if (jsonOk) {
+        try {
+            discoverExecUnits(pkg, errors);
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
+    }
+    // Links in Markdown and secrets in any file.
+    const scanned = [...walkFiles(pkg.harnessDir), ...(units.docs ? walkFiles(units.docs.dir) : [])];
+    for (const file of [...new Set(scanned)]) {
+        const text = fs.readFileSync(file, 'utf8');
+        for (const [pattern, what] of SECRET_PATTERNS)
+            if (pattern.test(text))
+                warnings.push(`${show(file)} looks like it contains ${what}`);
+        if (!file.endsWith('.md'))
+            continue;
+        for (const match of text.matchAll(/\]\(([^)\s#]+)(?:#[^)]*)?\)/g)) {
+            const link = match[1];
+            if (/^[a-z][a-z0-9+.-]*:/i.test(link) || link.startsWith('/'))
+                continue;
+            const target = path.resolve(path.dirname(file), decodeURI(link));
+            if (!inside(root, target))
+                errors.push(`${show(file)}: the link ${link} points outside the package`);
+            else if (!fs.existsSync(target))
+                errors.push(`${show(file)}: the link ${link} points at a missing file`);
+        }
+    }
+    return { errors, warnings, alwaysOnBytes, plugin: pkg.plugin };
+}

package/dist/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { add, approve, check, fetch, init, mcp, newUnit, remove, run, status, sync, update, why } from './commands.js';
+import { Refused } from './run.js';
+import { HarnessError, readJson } from './util.js';
+const HELP = `harnesspm — the harness package manager
+
+Projects
+  harnesspm init                 set up harnesspm in this project
+  harnesspm sync [--check]       write the agent files (--check: compare only, for CI)
+  harnesspm status               layers, packages and always-on size
+  harnesspm why <ID>             where a unit comes from and how to change it
+  harnesspm run <plugin>:<script> [-- args]
+                                 run a script of a trusted package
+  harnesspm approve [<package>]  approve a "pin" package's new version, and write what an agent could not
+  harnesspm fetch                download the harness packages in the lock, for jobs without an install
+
+Harnesses on top of the repository's (your team's, your own)
+  harnesspm add <source> [--local] [--no-hook]
+                                 add a harness: github:<owner>/<repo>, git:<url>, npm:<name> or a folder
+  harnesspm remove <source> [--local]
+  harnesspm update               fetch new versions of added harnesses
+
+Authors
+  harnesspm check [<folder>]     validate a harness before publishing
+  harnesspm new <kind> <name> [--to <plugin>] [--entry]
+                                 a rule, skill, agent, script, hook or mcp from a template
+  harnesspm new patch <rule ID> [--to <plugin>] [--entry]
+                                 a patch that changes some sections of a rule
+`;
+const out = {
+    log: (line) => console.log(line),
+    warn: (line) => console.error(line),
+};
+function main(argv) {
+    const [command, ...rest] = argv;
+    if (command !== 'run' && command !== 'mcp' && (rest.includes('--help') || rest.includes('-h'))) {
+        console.log(HELP);
+        return 0;
+    }
+    if (command === 'run' || command === 'mcp') {
+        // Everything after the script name goes to the script, untouched.
+        let agent;
+        let i = 0;
+        if (rest[0] === '--agent') {
+            agent = rest[1];
+            i = 2;
+        }
+        const ref = rest[i];
+        if (ref === undefined)
+            throw new HarnessError(`Usage: harnesspm ${command} [--agent <claude|codex>] <plugin>:<name>${command === 'run' ? ' [-- args]' : ''}`);
+        const args = rest.slice(i + 1);
+        if (args[0] === '--')
+            args.shift();
+        return command === 'run' ? run(process.cwd(), ref, args, agent) : mcp(process.cwd(), ref, agent);
+    }
+    const flags = new Set(rest.filter((a) => a.startsWith('--')));
+    const args = rest.filter((a) => !a.startsWith('--'));
+    const cwd = process.cwd();
+    const unknown = (allowed) => {
+        for (const flag of flags)
+            if (!allowed.includes(flag))
+                throw new HarnessError(`Unknown option ${flag} for ${command}`);
+    };
+    switch (command) {
+        case 'init':
+            unknown([]);
+            return init(cwd, out);
+        case 'sync':
+            unknown(['--check']);
+            return sync(cwd, out, { check: flags.has('--check') });
+        case 'status':
+            unknown([]);
+            return status(cwd, out);
+        case 'why':
+            unknown([]);
+            if (args[0] === undefined)
+                throw new HarnessError('Usage: harnesspm why <ID>');
+            return why(cwd, args[0], out);
+        case 'add':
+        case 'remove': {
+            unknown(command === 'add' ? ['--local', '--no-hook'] : ['--local']);
+            if (args[0] === undefined)
+                throw new HarnessError(`Usage: harnesspm ${command} <source>${command === 'add' ? ' [--local] [--no-hook]' : ' [--local]'}`);
+            if (command === 'add')
+                return add(cwd, args[0], out, { local: flags.has('--local'), hook: !flags.has('--no-hook') });
+            return remove(cwd, args[0], out, { local: flags.has('--local') });
+        }
+        case 'update':
+            unknown([]);
+            return update(cwd, out);
+        case 'new': {
+            const flagArgs = rest.filter((a, i) => a === '--to' || rest[i - 1] === '--to' || a === '--entry');
+            const positional = rest.filter((a) => !flagArgs.includes(a) && !a.startsWith('--'));
+            const toIndex = rest.indexOf('--to');
+            const to = toIndex >= 0 ? rest[toIndex + 1] : undefined;
+            for (const a of rest)
+                if (a.startsWith('--') && a !== '--to' && a !== '--entry')
+                    throw new HarnessError(`Unknown option ${a} for new`);
+            if (positional.length !== 2)
+                throw new HarnessError('Usage: harnesspm new <kind> <name> [--to <plugin>] [--entry], or harnesspm new patch <rule ID>');
+            return newUnit(cwd, positional[0], positional[1], { ...(to !== undefined ? { to } : {}), entry: rest.includes('--entry') }, out);
+        }
+        case 'fetch':
+            unknown([]);
+            return fetch(cwd, out);
+        case 'approve':
+            unknown([]);
+            return approve(cwd, args[0], out);
+        case 'check':
+            unknown([]);
+            return check(args[0] ?? cwd, out);
+        case '--version':
+        case '-v': {
+            const pkg = readJson(new URL('../package.json', import.meta.url).pathname);
+            console.log(pkg.version);
+            return 0;
+        }
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(HELP);
+            return 0;
+        default:
+            throw new HarnessError(`Unknown command "${command}". Run \`harnesspm help\`.`);
+    }
+}
+try {
+    process.exitCode = main(process.argv.slice(2));
+}
+catch (error) {
+    if (error instanceof HarnessError) {
+        console.error(`harnesspm: ${error.message}`);
+        process.exitCode = error instanceof Refused ? 2 : 1;
+    }
+    else {
+        throw error;
+    }
+}