Add @razroo/iso and release iso-harness 0.3.0

Author: CharlieGreenman

.github/workflows/ci.yml

@@ -78,6 +78,9 @@ jobs:
       - name: Pipeline integration (agentmd → isolint → iso-harness)
         run: node examples/pipeline/build.mjs
 
+      - name: iso wrapper smoke build
+        run: node packages/iso/bin/iso.mjs build packages/iso-harness/examples/minimal --skip-isolint --dry-run --out /tmp/iso-wrapper-smoke --target claude
+
       - name: iso-harness smoke build
         working-directory: packages/iso-harness
         run: npm run smoke

.github/workflows/iso-release.yml

@@ -0,0 +1,53 @@
+name: iso Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+defaults:
+  run:
+    working-directory: packages/iso
+
+jobs:
+  publish:
+    name: Publish @razroo/iso to npm
+    if: startsWith(github.ref_name, 'iso-v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+          cache: npm
+
+      - name: Verify tag matches package.json version
+        run: |
+          TAG="${GITHUB_REF_NAME#iso-v}"
+          PKG="$(node -p "require('./package.json').version")"
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match packages/iso/package.json version $PKG"
+            exit 1
+          fi
+
+      - name: Install (workspace root)
+        run: npm ci
+        working-directory: .
+
+      - run: npm run build --workspace @razroo/agentmd
+        working-directory: .
+
+      - run: npm run build --workspace @razroo/isolint
+        working-directory: .
+
+      - run: npm test
+
+      - name: Publish
+        run: npm publish --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -23,7 +23,8 @@ Today, writing agent instructions is fragmented on two axes:
    unstructured rationale all drop silently at 7B. You don't find out
    until the agent misbehaves in production.
 
-The three packages in this repo compose into a pipeline that fixes both:
+Three core packages in this repo compose into a pipeline that fixes both,
+and a fourth wrapper package exposes that whole chain behind one CLI:
 
 ```
    authored source              structural dialect             portable prose             fan-out to harnesses
@@ -58,6 +59,11 @@ The three packages in this repo compose into a pipeline that fixes both:
   MCP servers into `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`,
   `.opencode/agents/*.md`, etc., so all four harnesses stay in lockstep.
 
+- **[`packages/iso`](./packages/iso)** — `@razroo/iso`
+  The wrapper CLI for the whole flow: if `agent.md` is your authored source,
+  `iso build` runs `agentmd lint`, `agentmd render`, `isolint lint`, then
+  `iso-harness build` in one command.
+
 Each package is independently published on npm and works on its own.
 They're in one repo because they're designed to compose.
 
@@ -70,7 +76,8 @@ iso/
 └── packages/
     ├── agentmd/          # structure + adherence
     ├── isolint/          # portable prose
-    └── iso-harness/      # one source, every harness
+    ├── iso-harness/      # one source, every harness
+    └── iso/              # one command for the whole pipeline
 ```
 
 ## Build & test
@@ -85,6 +92,7 @@ npm run test:pipeline       # end-to-end demo (agentmd → isolint → iso-harne
 # Target a single package
 npm run build --workspace @razroo/isolint
 npm run test  --workspace @razroo/agentmd
+npm run test  --workspace @razroo/iso
 ```
 
 ## Releasing
@@ -117,5 +125,6 @@ build, and `npm publish --provenance`.
 [`examples/pipeline/`](./examples/pipeline) is an executable demonstration
 of the composed pipeline: one authored `agent.md` is structurally linted,
 rendered, prose-linted, and fanned out into the 11 files each coding-agent
-harness expects. Run `npm run test:pipeline` to exercise all three packages
-against a single source.
+harness expects. Run `npm run test:pipeline` to exercise the core pipeline,
+or use `@razroo/iso` in your own project when you want the same chain behind
+one CLI.

package-lock.json

@@ -1,5 +1,12 @@
 # @razroo/iso-harness
 
+## 0.3.0
+
+### Minor Changes
+
+- Add `iso-harness build --dry-run` and `--watch`, and include dry-run
+  summaries with per-file byte sizes.
+
 ## 0.2.0
 
 ### Minor Changes

packages/iso-harness/CHANGELOG.md

@@ -33,8 +33,18 @@ Or once installed as a CLI:
 iso-harness build                         # reads ./iso, writes to ./
 iso-harness build --target claude,cursor  # only two targets
 iso-harness build --source path/to/iso --out path/to/project
+iso-harness build --dry-run               # print planned writes, no disk changes
+iso-harness build --watch                 # rebuild on every change under iso/
 ```
 
+## Build modes
+
+- `--dry-run` validates and renders the full output plan, but prints what
+  would be written instead of touching disk.
+- `--watch` keeps a filesystem watcher on the source directory and reruns the
+  build after changes. Combine it with `--target` when you only care about one
+  harness while iterating.
+
 ## Source format
 
 ```

packages/iso-harness/README.md

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { build, validate } from '../src/build.mjs';
 import { formatDiagnostic } from '../src/validate.mjs';
-import { readFileSync } from 'node:fs';
+import { readFileSync, watch as fsWatch } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -34,6 +34,7 @@ const USAGE = `iso-harness — one source directory, every agent harness
 Usage:
   iso-harness --version
   iso-harness build    [--source <dir>] [--out <dir>] [--target claude,cursor,codex,opencode]
+                       [--dry-run] [--watch]
   iso-harness validate [--source <dir>] [--format text|json]
 
 Commands:
@@ -47,6 +48,8 @@ Flags:
   --source <dir>     Path to iso source directory (default: iso)
   --out <dir>        Output root directory (default: .)
   --target <list>    Comma-separated targets (default: all four)
+  --dry-run          Print what would be written, with byte sizes. No disk writes.
+  --watch            Rebuild on changes to the source directory. Ctrl-C to exit.
   --format <fmt>     validate-only: text (default) | json
 `;
 
@@ -70,21 +73,58 @@ if (!cmd || cmd === '-h' || cmd === '--help' || cmd === 'help') {
   process.exit(cmd ? 0 : 0);
 }
 
+async function runBuildOnce({ source, out, targets, dryRun }) {
+  try {
+    const summary = await build({ source, out, targets, dryRun });
+    for (const line of summary) console.log(line);
+    return 0;
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+}
+
+function watchBuild({ source, out, targets, dryRun }) {
+  const sourceAbs = resolve(source);
+  let scheduled = null;
+  let building = false;
+  const trigger = () => {
+    if (scheduled) clearTimeout(scheduled);
+    scheduled = setTimeout(async () => {
+      scheduled = null;
+      if (building) return;
+      building = true;
+      console.log(`\n--- change detected — rebuilding ---`);
+      await runBuildOnce({ source, out, targets, dryRun });
+      building = false;
+    }, 150);
+  };
+  try {
+    fsWatch(sourceAbs, { recursive: true }, trigger);
+  } catch (err) {
+    console.error(`watch failed for ${sourceAbs}: ${err.message}`);
+    process.exit(1);
+  }
+  console.log(`watching ${sourceAbs} — press ^C to exit`);
+}
+
 if (cmd === 'build') {
   const source = flag('source', 'iso');
   const out = flag('out', '.');
   const targets = list('target') ?? ALL_TARGETS;
+  const dryRun = boolFlag('dry-run');
+  const watchMode = boolFlag('watch');
   const unknown = targets.filter(t => !ALL_TARGETS.includes(t));
   if (unknown.length) {
     console.error(`Unknown target(s): ${unknown.join(', ')}. Valid: ${ALL_TARGETS.join(', ')}`);
     process.exit(2);
   }
-  try {
-    const summary = await build({ source, out, targets });
-    for (const line of summary) console.log(line);
-  } catch (err) {
-    console.error(err.message);
-    process.exit(1);
+  const initial = await runBuildOnce({ source, out, targets, dryRun });
+  if (watchMode) {
+    watchBuild({ source, out, targets, dryRun });
+    // Keep the process alive; ^C exits.
+  } else {
+    process.exit(initial);
   }
 } else if (cmd === 'validate') {
   const source = flag('source', 'iso');

packages/iso-harness/bin/iso-harness.mjs

@@ -1,6 +1,6 @@
 {
   "name": "@razroo/iso-harness",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One config for every coding agent — Cursor, Claude Code, Codex, OpenCode.",
   "type": "module",
   "bin": {

packages/iso-harness/package.json

@@ -13,22 +13,41 @@ const EMITTERS = {
   opencode: emitOpenCode,
 };
 
-export async function build({ source, out, targets }) {
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+export async function build({ source, out, targets, dryRun = false }) {
   const src = await loadSource(source);
   const diagnostics = validateSource(src);
   const errors = diagnostics.filter((d) => d.severity === 'error');
   if (errors.length) throw new ValidationError(diagnostics);
 
   const outAbs = path.resolve(out);
-  const summary = [`iso-harness: loaded ${src.agents.length} agent(s), ${src.commands.length} command(s), ${Object.keys(src.mcp.servers).length} MCP server(s) from ${src.sourceDir}`];
+  const prefix = dryRun ? 'iso-harness (dry-run)' : 'iso-harness';
+  const summary = [`${prefix}: loaded ${src.agents.length} agent(s), ${src.commands.length} command(s), ${Object.keys(src.mcp.servers).length} MCP server(s) from ${src.sourceDir}`];
   const warnings = diagnostics.filter((d) => d.severity === 'warning');
   for (const w of warnings) summary.push(`  warning: ${formatDiagnostic(w)}`);
 
+  const opts = { dryRun };
+  let totalBytes = 0;
+  let totalFiles = 0;
   for (const target of targets) {
     const emit = EMITTERS[target];
-    const written = await emit(src, outAbs);
-    summary.push(`  [${target}] wrote ${written.length} file(s)`);
-    for (const f of written) summary.push(`    - ${path.relative(outAbs, f)}`);
+    const written = await emit(src, outAbs, opts);
+    const verb = dryRun ? 'would write' : 'wrote';
+    summary.push(`  [${target}] ${verb} ${written.length} file(s)`);
+    for (const f of written) {
+      totalBytes += f.bytes;
+      totalFiles += 1;
+      const size = dryRun ? ` (${formatBytes(f.bytes)})` : '';
+      summary.push(`    - ${path.relative(outAbs, f.path)}${size}`);
+    }
+  }
+  if (dryRun) {
+    summary.push(`\n${totalFiles} file(s), ${formatBytes(totalBytes)} — no files written`);
   }
   return summary;
 }

packages/iso-harness/src/build.mjs

@@ -1,11 +1,17 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
-export async function writeFile(filePath, content) {
+// `dryRun` short-circuits the actual filesystem write so callers can still
+// accumulate the "what would be emitted" list without touching disk. The
+// return value reports bytes for dry-run summary display.
+export async function writeFile(filePath, content, { dryRun = false } = {}) {
+  const bytes = Buffer.byteLength(content);
+  if (dryRun) return { bytes, wrote: false };
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   await fs.writeFile(filePath, content);
+  return { bytes, wrote: true };
 }
 
-export async function writeJson(filePath, obj) {
-  await writeFile(filePath, JSON.stringify(obj, null, 2) + '\n');
+export async function writeJson(filePath, obj, opts) {
+  return writeFile(filePath, JSON.stringify(obj, null, 2) + '\n', opts);
 }