@rhost/testkit 0.1.1 → 1.3.1

package/ROADMAP.md

@@ -0,0 +1,241 @@
+# @rhost/testkit Roadmap
+
+Features are ranked by priority — highest value, lowest friction first.
+Shipped items are marked ✅.
+
+---
+
+## ✅ v0.2.0 — Offline Validator + Watch Mode
+
+**Offline Softcode Validator** (`validate`, `validateFile`, `rhost-testkit validate`)
+- Tokenizer → Parser → Semantic checker pipeline, no server connection needed
+- Catches unbalanced parens/brackets, unknown functions, wrong argument counts
+- 150+ built-in function signatures with min/max arg counts
+- CLI with human-readable and `--json` output; exit code 0/1
+
+**Watch Mode** (`rhost-testkit watch`)
+- Auto-discovers `*.test.ts` / `*.spec.ts` files
+- Re-runs changed files on save with 300ms debounce
+- Persistent terminal output with clear-between-runs
+- Spawns `ts-node --transpile-only` for TypeScript test files
+
+---
+
+## ✅ v1.0.0 — Snapshot Testing + Extended World API + CI/CD Templates
+
+**Snapshot Testing** — `await expect('iter(lnum(1,10),##)').toMatchSnapshot()`
+- Stored in `__snapshots__/<testfile>.snap` JSON files, auto-located
+- First run writes; subsequent runs compare with diff output on mismatch
+- `RHOST_UPDATE_SNAPSHOTS=1` or `updateSnapshots: true` in options to refresh
+- Obsolete snapshot detection with trimming on update
+
+**Extended World API** — closes remaining gaps in `RhostWorld`:
+`pemit` · `remit` · `force` · `parent` · `zone` · `addToChannel` · `grantQuota` · `wait` · `mail`
+
+**CI/CD Templates** — `rhost-testkit init --ci github|gitlab`
+- Generates `.github/workflows/mush-tests.yml` or `.gitlab-ci.yml`
+- Lowers the barrier to "tests in CI" to near zero
+
+---
+
+## ✅ v1.1.0 — Tier 1 Features
+
+### ✅ 1. Server Pre-flight Assertions
+
+Verify the server's configuration matches what your softcode requires, before deploying or running tests. Especially valuable in CI where the target server may differ from dev.
+
+```typescript
+import { preflight } from '@rhost/testkit';
+
+await preflight(client, [
+  assertFunctionExists('json'),
+  assertFunctionExists('lsearch'),
+  assertServerFlag('FUNCTION_SIDE_EFFECTS', false),
+  assertAttributeLimit(500),
+]);
+// Throws a summary error if any check fails — stops CI before tests run
+```
+
+- Zero new infrastructure — pure `client.eval()` calls
+- Natural extension of the CI/CD templates just shipped
+- Returns a structured report: passed / failed / skipped
+
+---
+
+### ✅ 2. Multi-Persona Test Matrix
+
+The single biggest blind spot in MUSH testing: everyone tests as Wizard, so permission bugs are invisible. Define a test once and run it against multiple permission levels, asserting which outputs should match and which should differ.
+
+```typescript
+runner.describe('Room visibility', ({ personas }) => {
+  personas(
+    ['mortal', 'builder', 'wizard'],
+    'hidden room is only visible to builders+',
+    async ({ expect, persona }) => {
+      if (persona === 'mortal') {
+        await expect(`lsearch(me,type,room,eval,isvisible(%#,%#))`).toBe('0');
+      } else {
+        await expect(`lsearch(me,type,room,eval,isvisible(%#,%#))`).not.toBe('0');
+      }
+    }
+  );
+});
+```
+
+- Runner connects as each persona in sequence using separate credentials
+- Clearly marks which permission level a failure occurred at
+- No other MUSH tool — including PennMUSH's `kilt` — does this
+- Source: documented as the #1 class of bugs missed in wizard-only testing
+
+---
+
+### ✅ 3. Side-Effect Assertion Mode
+
+MUSHcode's "function side effects" feature means calling a function for its return value can secretly create objects, write attributes, or emit to players. Tests today only check return values. This catches the invisible class.
+
+```typescript
+it('add() has no side effects', async ({ expect }) => {
+  await expect('add(2,3)')
+    .toBe('5')
+    .withNoSideEffects();  // fails if any object was created/modified
+});
+
+it('this attr must only emit to enactor', async ({ expect, world }) => {
+  const obj = await world.create('Greeter');
+  await world.set(obj, 'GREET', '@pemit %#=hello');
+  await expect.sideEffects(async () => {
+    await world.trigger(obj, 'GREET');
+  }).toOnlyEmitTo('me');
+});
+```
+
+- Implemented by snapshotting world state (dbrefs + attributes) before/after eval
+- `world` already tracks creation — extend to also track attribute writes
+- Analogous to Jest's `expect(fn).not.toHaveBeenCalled()` spy assertions
+- Source: described as "Satan's spawn" in MUSH security community
+
+---
+
+## ✅ v1.2.0 — Tier 2 Features
+
+### ✅ 4. Register Clobber / Re-entrancy Analyzer
+
+`%q0`–`%q9` registers are scoped per queue entry. Attributes called inside `iter()`, `@dolist`, or recursive `@trigger` chains that also write registers can silently clobber each other — the softcode equivalent of a race condition. This is a static analysis pass in the offline validator.
+
+```
+$ rhost-testkit validate --file combat.mush
+
+WARNING: register clobber risk
+  COMBAT_ROLL writes %q0 and is called inside iter() at line 14.
+  Concurrent invocations will overwrite each other's %q0.
+  Consider wrapping in localize().
+```
+
+- Pure static analysis — no server needed
+- Extends the existing semantic checker
+- Source: documented in practical-mush-coding guides as a frequent silent bug
+
+---
+
+### ✅ 5. Deploy Pipeline with Rollback
+
+The current softcode deployment workflow is manual paste-and-pray with no rollback. This addresses it directly.
+
+```bash
+npx rhost-testkit deploy --file mycode.mush --target '#42' --test
+```
+
+1. **Snapshot** — `@decomp` all target objects, store attribute state
+2. **Upload** — apply the softcode file to the target object(s)
+3. **Test** — run the test suite
+4. **Rollback** — if tests fail, restore every attribute to pre-deploy state atomically
+
+- Source: Faraday (AresMUSH creator) cited explicitly: *"when something breaks, the players are immediately affected — there's no form of revision history"*
+- Highest real-world operational impact of anything on this list
+- Most complex to implement correctly (ordering, partial failure, `@decomp` parsing)
+
+---
+
+### ✅ 6. Dialect Compatibility Report
+
+PennMUSH 1.8.5 is compatible with 359 community softcode files; RhostMUSH 3.9.4 with only 119. Developers sharing code across servers have no way to know which functions are portable. Given a softcode file, emit a compatibility report.
+
+```bash
+$ rhost-testkit validate --compat mycode.mush
+
+DIALECT COMPATIBILITY
+  ✓ add, sub, mul, div          — all platforms
+  ✓ iter, lnum, sort            — all platforms
+  ⚠ localize()                  — RhostMUSH, PennMUSH only (not TinyMUX)
+  ✗ json(), jsonquery()         — RhostMUSH only
+  ✗ cluster_set(), cluster_get() — RhostMUSH only
+```
+
+- The function signature table already exists in the validator — add a `platforms` field per function
+- Community-wide value: like a browser-compat table for softcode
+- Source: documented cross-platform portability failures across PennMUSH/TinyMUX/Rhost
+
+---
+
+## ✅ v1.3.0 — Tier 3 Features (Batch 1)
+
+### ✅ 7. Benchmark Mode
+
+Profile softcode performance against a live server:
+
+```typescript
+runner.bench('Heavy iter', async ({ client }) => {
+  await client.eval('iter(lnum(1,1000),##)');
+}, { iterations: 100, warmup: 10 });
+```
+
+- Reports median, p95, p99 latency per expression
+- Compares before/after across runs (regression detection)
+- **Recursion depth profiler** (extension): track max call depth reached, warn when approaching server limits — gives context to opaque `#-1 FUNCTION RECURSION LIMIT` errors
+- No other MUSH tooling exists for this
+
+---
+
+### ✅ 8. Softcode Formatter
+
+```bash
+npx rhost-testkit fmt mycode.mush
+npx rhost-testkit fmt --check  # exit non-zero if not formatted
+```
+
+- Normalise spacing around `(`, `,`, `)`
+- Indent nested function calls for readability
+- Like Prettier, but for MUSH softcode
+
+---
+
+## Planned — Tier 3 (Remaining)
+
+### 9. Test Coverage Tracking
+
+- Track which attributes on which objects were exercised during a run
+- Produce a coverage report: tested vs. untested softcode attributes
+- Similar to Istanbul/c8 for JavaScript
+- Novel in the MUSH ecosystem
+
+---
+
+### 10. Interactive REPL
+
+```bash
+npx rhost-testkit repl [--host localhost] [--port 4201]
+```
+
+- Persistent MUSH connection with readline history
+- Tab completion for known built-in function names
+- Full world API available inline (create/destroy objects, set attributes)
+- Faster than raw telnet; smarter than `think` in a MUSH client
+
+---
+
+### 11. Parallel Test Execution
+
+- Run independent `describe` blocks concurrently on separate connections
+- Connection-per-suite model fits naturally with the current architecture
+- Significant speedup for large codebases with independent modules
+- Complex to implement correctly (world cleanup, reporter ordering)

package/dist/benchmark.d.ts

@@ -0,0 +1,44 @@
+import { RhostClient } from './client';
+export interface BenchOptions {
+    /** Human-readable label. Defaults to the expression string. */
+    name?: string;
+    /** Number of measured iterations (after warmup). Default: 100. */
+    iterations?: number;
+    /** Number of un-measured warmup runs. Default: 10. */
+    warmup?: number;
+}
+export interface BenchmarkResult {
+    name: string;
+    iterations: number;
+    warmup: number;
+    /** All measured samples in milliseconds, in run order. */
+    samples: number[];
+    mean: number;
+    median: number;
+    p95: number;
+    p99: number;
+    min: number;
+    max: number;
+}
+/**
+ * Run a single softcode expression against `client` and return timing stats.
+ */
+export declare function runBench(client: RhostClient, expression: string, options?: BenchOptions): Promise<BenchmarkResult>;
+export declare class RhostBenchmark {
+    private readonly client;
+    private readonly entries;
+    constructor(client: RhostClient);
+    /**
+     * Register a benchmark expression. Returns `this` for chaining.
+     */
+    add(expression: string, options?: BenchOptions): this;
+    /**
+     * Run all registered benchmarks in sequence and return their results.
+     */
+    run(): Promise<BenchmarkResult[]>;
+}
+/**
+ * Format an array of BenchmarkResults into a human-readable table string.
+ */
+export declare function formatBenchResults(results: BenchmarkResult[]): string;
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../src/benchmark.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAMvC,MAAM,WAAW,YAAY;IACzB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACf;AAMD;;GAEG;AACH,wBAAsB,QAAQ,CAC1B,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,YAAiB,GAC3B,OAAO,CAAC,eAAe,CAAC,CA0B1B;AAWD,qBAAa,cAAc;IAGX,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAEf,MAAM,EAAE,WAAW;IAEhD;;OAEG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,IAAI;IAKzD;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;CAQ1C;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAqBrE"}

package/dist/benchmark.js

@@ -0,0 +1,118 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Benchmark Mode — profile softcode performance against a live server
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RhostBenchmark = void 0;
+exports.runBench = runBench;
+exports.formatBenchResults = formatBenchResults;
+// ---------------------------------------------------------------------------
+// runBench — low-level timing primitive
+// ---------------------------------------------------------------------------
+/**
+ * Run a single softcode expression against `client` and return timing stats.
+ */
+async function runBench(client, expression, options = {}) {
+    const name = options.name ?? expression;
+    const iterations = options.iterations ?? 100;
+    const warmup = options.warmup ?? 10;
+    // Warmup runs — not measured
+    for (let i = 0; i < warmup; i++) {
+        await client.eval(expression);
+    }
+    // Measured iterations
+    const samples = [];
+    for (let i = 0; i < iterations; i++) {
+        const start = performance.now();
+        await client.eval(expression);
+        const elapsed = performance.now() - start;
+        samples.push(elapsed);
+    }
+    return {
+        name,
+        iterations,
+        warmup,
+        samples,
+        ...computeStats(samples),
+    };
+}
+class RhostBenchmark {
+    constructor(client) {
+        this.client = client;
+        this.entries = [];
+    }
+    /**
+     * Register a benchmark expression. Returns `this` for chaining.
+     */
+    add(expression, options = {}) {
+        this.entries.push({ expression, options });
+        return this;
+    }
+    /**
+     * Run all registered benchmarks in sequence and return their results.
+     */
+    async run() {
+        const results = [];
+        for (const { expression, options } of this.entries) {
+            const result = await runBench(this.client, expression, options);
+            results.push(result);
+        }
+        return results;
+    }
+}
+exports.RhostBenchmark = RhostBenchmark;
+// ---------------------------------------------------------------------------
+// formatBenchResults — human-readable report
+// ---------------------------------------------------------------------------
+/**
+ * Format an array of BenchmarkResults into a human-readable table string.
+ */
+function formatBenchResults(results) {
+    if (results.length === 0) {
+        return 'No benchmark results.';
+    }
+    const lines = ['Benchmark Results', '─'.repeat(72)];
+    for (const r of results) {
+        lines.push('');
+        lines.push(`  ${r.name}`);
+        lines.push(`  iterations: ${r.iterations}  warmup: ${r.warmup}`);
+        lines.push(`  median: ${fmt(r.median)}ms  mean: ${fmt(r.mean)}ms` +
+            `  p95: ${fmt(r.p95)}ms  p99: ${fmt(r.p99)}ms`);
+        lines.push(`  min: ${fmt(r.min)}ms  max: ${fmt(r.max)}ms`);
+    }
+    lines.push('');
+    lines.push('─'.repeat(72));
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Internal stats helpers
+// ---------------------------------------------------------------------------
+function computeStats(samples) {
+    if (samples.length === 0) {
+        return { mean: 0, median: 0, p95: 0, p99: 0, min: 0, max: 0 };
+    }
+    const sorted = [...samples].sort((a, b) => a - b);
+    const mean = samples.reduce((s, v) => s + v, 0) / samples.length;
+    return {
+        mean,
+        median: percentile(sorted, 50),
+        p95: percentile(sorted, 95),
+        p99: percentile(sorted, 99),
+        min: sorted[0],
+        max: sorted[sorted.length - 1],
+    };
+}
+/** Compute the p-th percentile of a pre-sorted ascending array. */
+function percentile(sorted, p) {
+    if (sorted.length === 1)
+        return sorted[0];
+    const index = (p / 100) * (sorted.length - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    const weight = index - lower;
+    return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+}
+function fmt(n) {
+    return n.toFixed(3);
+}
+//# sourceMappingURL=benchmark.js.map

package/dist/benchmark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.js","sourceRoot":"","sources":["../src/benchmark.ts"],"names":[],"mappings":"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"}

package/dist/cli/deploy.d.ts

@@ -0,0 +1,2 @@
+export declare function runDeployCli(args: string[], cwd?: string): void;
+//# sourceMappingURL=deploy.d.ts.map

package/dist/cli/deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/cli/deploy.ts"],"names":[],"mappings":"AAYA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAwD9E"}

package/dist/cli/deploy.js

@@ -0,0 +1,120 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// rhost-testkit deploy — softcode deploy pipeline with rollback
+// ---------------------------------------------------------------------------
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeployCli = runDeployCli;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const deployer_1 = require("../deployer");
+// ---------------------------------------------------------------------------
+// Public entry point (testable with injected cwd)
+// ---------------------------------------------------------------------------
+function runDeployCli(args, cwd = process.cwd()) {
+    // --help
+    if (args.includes('--help') || args.includes('-h')) {
+        printHelp();
+        process.exit(0);
+    }
+    // Parse flags
+    const fileIndex = args.indexOf('--file');
+    const filePath = fileIndex !== -1 ? args[fileIndex + 1] : undefined;
+    const dryRun = args.includes('--dry-run');
+    const parseOnly = args.includes('--parse-only');
+    if (!filePath) {
+        console.error('rhost-testkit deploy: --file <path> is required\n');
+        printHelp();
+        process.exit(1);
+    }
+    const resolved = path.resolve(cwd, filePath);
+    if (!fs.existsSync(resolved)) {
+        console.error(`rhost-testkit deploy: file not found: ${resolved}`);
+        process.exit(1);
+    }
+    const content = fs.readFileSync(resolved, 'utf8');
+    const commands = (0, deployer_1.parseDeployFile)(content);
+    // --parse-only: validate file contents and exit
+    if (parseOnly) {
+        if (commands.length === 0) {
+            console.error('rhost-testkit deploy: no commands found in file');
+            process.exit(1);
+        }
+        console.log(`rhost-testkit deploy: ${commands.length} command(s) parsed OK`);
+        for (const cmd of commands) {
+            console.log(`  &${cmd.attr} ${cmd.dbref}=<value>`);
+        }
+        process.exit(0);
+    }
+    // --dry-run: show what would be applied without connecting
+    if (dryRun) {
+        console.log(`rhost-testkit deploy (dry-run): ${commands.length} command(s) would be applied`);
+        for (const cmd of commands) {
+            console.log(`  &${cmd.attr} ${cmd.dbref}=${cmd.value}`);
+        }
+        return;
+    }
+    // Live deploy requires connection flags — remind the user
+    console.error('rhost-testkit deploy: live deploy requires --host, --port, --user, --pass.\n' +
+        'Use --dry-run to preview without connecting, or the programmatic API for full deploy.');
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+function printHelp() {
+    console.log(`
+USAGE
+  rhost-testkit deploy --file <path> [options]
+
+OPTIONS
+  --file <path>    Path to softcode file (required)
+  --dry-run        Preview commands without connecting to the server
+  --parse-only     Validate the file format and exit
+  -h, --help       Show this help
+
+FILE FORMAT
+  Lines of the form:  &ATTRNAME #DBREF=value
+  Lines starting with # or @@ are treated as comments.
+
+EXAMPLES
+  rhost-testkit deploy --file mycode.mush --dry-run
+  rhost-testkit deploy --file mycode.mush --parse-only
+
+For live deployment with rollback, use the programmatic API:
+  import { deploy, parseDeployFile } from '@rhost/testkit';
+`.trim());
+}
+//# sourceMappingURL=deploy.js.map

package/dist/cli/deploy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.js","sourceRoot":"","sources":["../../src/cli/deploy.ts"],"names":[],"mappings":"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"}

package/dist/cli/fmt.d.ts

@@ -0,0 +1,2 @@
+export declare function runFmtCli(args: string[], cwd?: string): void;
+//# sourceMappingURL=fmt.d.ts.map

package/dist/cli/fmt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fmt.d.ts","sourceRoot":"","sources":["../../src/cli/fmt.ts"],"names":[],"mappings":"AAYA,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAyD3E"}

package/dist/cli/fmt.js

@@ -0,0 +1,119 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// rhost-testkit fmt — softcode formatter
+// ---------------------------------------------------------------------------
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFmtCli = runFmtCli;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const formatter_1 = require("../validator/formatter");
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+function runFmtCli(args, cwd = process.cwd()) {
+    if (args.includes('--help') || args.includes('-h')) {
+        printHelp();
+        process.exit(0);
+    }
+    const checkMode = args.includes('--check');
+    const pretty = args.includes('--pretty');
+    const lowercase = args.includes('--lowercase');
+    // Collect file paths (all non-flag args)
+    const files = args.filter(a => !a.startsWith('-'));
+    if (files.length === 0) {
+        // Read from stdin
+        const input = fs.readFileSync('/dev/stdin', 'utf8');
+        const result = (0, formatter_1.format)(input.trim(), { pretty, lowercase });
+        if (!checkMode) {
+            process.stdout.write(result.formatted + '\n');
+        }
+        if (checkMode && result.changed) {
+            process.stderr.write('<stdin>: not formatted\n');
+            process.exit(1);
+        }
+        return;
+    }
+    let anyChanged = false;
+    for (const file of files) {
+        const resolved = path.resolve(cwd, file);
+        if (!fs.existsSync(resolved)) {
+            console.error(`rhost-testkit fmt: file not found: ${resolved}`);
+            process.exit(1);
+        }
+        const content = fs.readFileSync(resolved, 'utf8');
+        const result = (0, formatter_1.format)(content.trim(), { pretty, lowercase });
+        if (checkMode) {
+            if (result.changed) {
+                console.error(`${file}: not formatted`);
+                anyChanged = true;
+            }
+        }
+        else {
+            if (result.changed) {
+                fs.writeFileSync(resolved, result.formatted + '\n', 'utf8');
+                console.log(`${file}: formatted`);
+            }
+            else {
+                console.log(`${file}: already formatted`);
+            }
+        }
+    }
+    if (checkMode && anyChanged) {
+        process.exit(1);
+    }
+}
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+function printHelp() {
+    console.log(`
+USAGE
+  rhost-testkit fmt [options] [file...]
+
+OPTIONS
+  --check        Exit non-zero if any file is not formatted (no writes)
+  --pretty       Indent nested function calls for human readability
+  --lowercase    Normalise function names to lowercase
+  -h, --help     Show this help
+
+EXAMPLES
+  rhost-testkit fmt mycode.mush
+  rhost-testkit fmt --check mycode.mush
+  rhost-testkit fmt --pretty mycode.mush
+  echo "add( 2, 3 )" | rhost-testkit fmt
+`.trim());
+}
+//# sourceMappingURL=fmt.js.map