@ai-ecoverse/biome-jsh 0.0.0-development

package/README.md

@@ -0,0 +1,83 @@
+# biome-jsh — a jsh-aware Biome runner
+
+Biome's CLI ignores `.jsh` / `.bsh` files, so linting them means renaming each
+one to `.js` first. But SLICC shell scripts run as an **AsyncFunction body**
+(see `kernel/realm/realm-module-system.ts`): top-level `await` **and** top-level
+`return` are both valid. A naive rename makes Biome parse the body as a module
+and emit a bogus error:
+
+```
+× Illegal return statement outside of a function
+```
+
+`biome-jsh` fixes this. For every `.jsh` / `.bsh` file it:
+
+1. wraps the body in `async function __slicc() { … }` (the same shape the
+   runtime uses), so top-level `await`/`return` parse cleanly;
+2. writes the wrapped content to a temp `.js` file and runs Biome on it in
+   **file mode** with `--reporter=github`;
+3. shifts every diagnostic back onto the real file — the wrapper prefix is one
+   newline-terminated line at column 0, so only the line number moves (columns
+   are already correct) — and rewrites the temp path to the real `.jsh` path.
+
+`.js` / `.ts` / `.json` / … files pass straight through, unwrapped.
+
+This is the single jsh-aware runner meant to replace the ad-hoc
+"copy-to-`.js`, lint, rename back" hack in downstream CI (e.g.
+`ai-ecoverse/skills`). The wrap/unwrap/span-shift logic in
+[`jsh-biome-source.mjs`](./jsh-biome-source.mjs) is a byte-aligned mirror of the
+in-app Biome command
+(`packages/webapp/src/shell/supplemental-commands/jsh-biome-source.ts`, WASM
+path); this CLI is the binary path.
+
+## Usage
+
+```sh
+biome-jsh check  [paths...]           # lint + format-check (github reporter)
+biome-jsh format [paths...]           # print formatted output to stdout
+biome-jsh format --write [paths...]   # format files in place
+```
+
+Paths may be files or directories (walked recursively; `node_modules` and
+`.git` skipped). `check` exits non-zero when any file has an error or is not
+formatted, and emits GitHub Actions annotations on stdout so CI surfaces them
+inline.
+
+```sh
+biome-jsh check skills/
+```
+
+## Biome binary
+
+`@biomejs/biome` is a declared dependency but the binary is **resolved at
+runtime**, not bundled: `biome-jsh` looks for `node_modules/.bin/biome` walking
+up from the current directory and from its own location, or uses `$BIOME_BIN`.
+Any already-installed Biome is reused, so no fresh install is required.
+
+## Published package
+
+Published to npm as **`@ai-ecoverse/biome-jsh`** (public), released **in lockstep
+with SLICC** via slicc's semantic-release pipeline — its version tracks the
+`sliccy` release version (see the second `@semantic-release/npm` target with
+`pkgRoot: packages/dev-tools/biome-jsh` in `.releaserc.json`). Downstream repos
+consume it as a dev dependency:
+
+```sh
+npm i -D @ai-ecoverse/biome-jsh
+```
+
+then run `npx biome-jsh check <paths>` in CI — it reuses the repo's own
+already-installed `@biomejs/biome`, so there's nothing to rename and no false
+`return`/`await` parse errors.
+
+## Layout
+
+| File                   | Role                                                            |
+| ---------------------- | --------------------------------------------------------------- |
+| `biome-jsh.mjs`        | CLI entry (I/O: file walking, temp files, spawning Biome).      |
+| `lib.mjs`              | Pure logic: github-annotation parse / shift / rewrite.          |
+| `jsh-biome-source.mjs` | Pure wrap / unwrap / span-shift helpers (mirror of the webapp). |
+
+Tests are co-located `*.test.mjs` and run under the repo's `dev-tools` Vitest
+project. The integration suite spawns the real Biome binary and skips cleanly
+when none is installed.

package/biome-jsh.mjs

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+/*
+ * biome-jsh — a jsh-aware Biome runner.
+ *
+ * Biome's CLI ignores `.jsh`/`.bsh` files, and these scripts run as an
+ * AsyncFunction body (top-level `await` AND `return` are valid). Renaming a
+ * `.jsh` to `.js` and linting it (the naive hack) makes Biome parse the body
+ * as a module and emit a bogus "Illegal return statement outside of a
+ * function" error. This tool instead wraps each `.jsh`/`.bsh` body in an async
+ * function, runs Biome (`--reporter=github`) on the wrapped temp `.js`, then
+ * shifts every diagnostic back onto the real file — so top-level await/return
+ * never trip a false positive. `.js/.ts/.json/...` pass straight through.
+ *
+ * Usage:
+ *   biome-jsh check  [paths...]        Lint + format-check (github reporter)
+ *   biome-jsh format [paths...]        Print formatted output to stdout
+ *   biome-jsh format --write [paths...] Format in place
+ *
+ * The `@biomejs/biome` binary is resolved at runtime from `node_modules/.bin`
+ * (walking up from CWD and from this file), or from $BIOME_BIN — it is NOT
+ * bundled, so an existing install is reused rather than a fresh one required.
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  isLintableFile,
+  JSH_WRAP_PREFIX_LINE_COUNT,
+  shouldWrapForBiome,
+  unwrapFormattedJsh,
+  wrapJshForBiome,
+} from './jsh-biome-source.mjs';
+import {
+  biomeBinCandidates,
+  formatGithubAnnotation,
+  makeErrorAnnotation,
+  remapGithubOutput,
+} from './lib.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const HELP = `biome-jsh - a jsh-aware Biome runner
+
+Usage:
+  biome-jsh check  [paths...]          Lint + format-check (--reporter=github)
+  biome-jsh format [paths...]          Print formatted output to stdout
+  biome-jsh format --write [paths...]  Format files in place
+
+.jsh/.bsh bodies are wrapped in an async function before Biome sees them, so
+top-level await/return do not raise a false "return outside of function" error.
+Diagnostics are shifted back onto the real file. Other extensions pass through.
+
+Env:
+  BIOME_BIN   Path to the @biomejs/biome binary (default: resolved from
+              node_modules/.bin, walking up from CWD and this tool).
+`;
+
+function resolveBiomeBinary() {
+  const fromEnv = process.env.BIOME_BIN;
+  if (fromEnv) {
+    if (existsSync(fromEnv)) return fromEnv;
+    fail(`BIOME_BIN is set to '${fromEnv}' but that file does not exist`);
+  }
+  for (const candidate of biomeBinCandidates([process.cwd(), HERE])) {
+    if (existsSync(candidate)) return candidate;
+  }
+  fail(
+    'could not find the @biomejs/biome binary. Install it (npm i @biomejs/biome) ' +
+      'or set BIOME_BIN to its path.'
+  );
+}
+
+function runBiome(bin, args, cwd) {
+  const result = spawnSync(bin, args, {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.error) fail(`failed to run biome: ${result.error.message}`);
+  return {
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    status: result.status ?? 0,
+  };
+}
+
+function parseArgs(argv) {
+  const parsed = { subcommand: null, paths: [], write: false, help: false, version: false };
+  for (const arg of argv) {
+    if (arg === '-h' || arg === '--help') parsed.help = true;
+    else if (arg === '-v' || arg === '--version') parsed.version = true;
+    else if (arg === '--write') parsed.write = true;
+    else if (parsed.subcommand === null && (arg === 'check' || arg === 'format'))
+      parsed.subcommand = arg;
+    else if (arg.startsWith('-')) fail(`unknown option: ${arg}`);
+    else parsed.paths.push(arg);
+  }
+  return parsed;
+}
+
+function expandPaths(paths) {
+  const files = [];
+  const missing = [];
+  for (const raw of paths) {
+    if (!existsSync(raw)) {
+      missing.push(raw);
+      continue;
+    }
+    if (statSync(raw).isDirectory()) walkDirectory(raw, files);
+    else if (isLintableFile(raw)) files.push(raw);
+  }
+  return { files, missing };
+}
+
+function walkDirectory(dir, out) {
+  for (const name of readdirSync(dir)) {
+    if (name === 'node_modules' || name.startsWith('.git')) continue;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) walkDirectory(full, out);
+    else if (isLintableFile(full)) out.push(full);
+  }
+}
+
+/** Format the wrapped content of a `.jsh`/`.bsh` file back to real-file terms.
+ * Biome 2.x `format` (no --write) only prints a diff, so we format the temp in
+ * place with `--write` and read it back. Mirrors the webapp WASM path: a
+ * re-format round-trip guards the tab de-indent so a lossy unwrap (multi-line
+ * template literals whose lines start with a real tab) keeps the source. */
+function formatWrapped(bin, source, dir, tempBase, tempPath) {
+  const wrapped = wrapJshForBiome(source);
+  writeFileSync(tempPath, wrapped);
+  const fmt = runBiome(bin, ['format', '--write', tempBase], dir);
+  // A non-zero status means Biome could not format (parse error, bad config);
+  // the temp is left unchanged, so surface it rather than reporting success.
+  if (fmt.status !== 0) return { safe: source, changed: false, failed: true, stderr: fmt.stderr };
+  const formattedWrapped = readFileSync(tempPath, 'utf8');
+  // Unchanged (already formatted) → no diff.
+  if (formattedWrapped === wrapped) return { safe: source, changed: false, failed: false };
+  const candidate = unwrapFormattedJsh(formattedWrapped);
+  writeFileSync(tempPath, wrapJshForBiome(candidate));
+  const reFmt = runBiome(bin, ['format', '--write', tempBase], dir);
+  if (reFmt.status !== 0)
+    return { safe: source, changed: false, failed: true, stderr: reFmt.stderr };
+  const reFormatted = readFileSync(tempPath, 'utf8');
+  const safe = reFormatted === formattedWrapped ? candidate : source;
+  return { safe, changed: safe !== source, failed: false };
+}
+
+function processWrappedCheck(bin, file) {
+  const dir = dirname(file);
+  const source = readFileSync(file, 'utf8');
+  const tempBase = tempName(file);
+  const tempPath = join(dir, tempBase);
+  const out = { lines: [], errorCount: 0, warningCount: 0 };
+  try {
+    writeFileSync(tempPath, wrapJshForBiome(source));
+    const lint = runBiome(bin, ['lint', '--reporter=github', tempBase], dir);
+    const remapped = remapGithubOutput(lint.stdout, file, JSH_WRAP_PREFIX_LINE_COUNT);
+    out.lines.push(...remapped.lines);
+    out.errorCount += remapped.errorCount;
+    out.warningCount += remapped.warningCount;
+    // A hard biome failure (e.g. bad config) exits non-zero with no annotations.
+    if (lint.status !== 0 && remapped.errorCount === 0 && remapped.warningCount === 0) {
+      out.errorCount++;
+      out.lines.push(makeStderrLines(lint.stderr));
+    }
+    const fmt = formatWrapped(bin, source, dir, tempBase, tempPath);
+    if (fmt.failed) {
+      out.lines.push(
+        formatGithubAnnotation(makeErrorAnnotation(file, 'Biome could not format this file'))
+      );
+      out.lines.push(makeStderrLines(fmt.stderr));
+      out.errorCount++;
+    } else if (fmt.safe !== source) {
+      out.lines.push(
+        formatGithubAnnotation(
+          makeErrorAnnotation(file, 'File is not formatted (run: biome-jsh format --write)')
+        )
+      );
+      out.errorCount++;
+    }
+  } finally {
+    safeUnlink(tempPath);
+  }
+  return out;
+}
+
+function processWrappedFormat(bin, file, write) {
+  const dir = dirname(file);
+  const source = readFileSync(file, 'utf8');
+  const tempBase = tempName(file);
+  const tempPath = join(dir, tempBase);
+  try {
+    const { safe, changed, failed, stderr } = formatWrapped(bin, source, dir, tempBase, tempPath);
+    if (failed) {
+      process.stderr.write(`biome-jsh: ${file}: ${makeStderrLines(stderr)}\n`);
+      return { stdout: '', changed: false, failed: true };
+    }
+    if (write) {
+      if (changed) writeFileSync(file, safe);
+      return { stdout: '', changed, failed: false };
+    }
+    return { stdout: safe, changed, failed: false };
+  } finally {
+    safeUnlink(tempPath);
+  }
+}
+
+function processPlainCheck(bin, file) {
+  const dir = dirname(file);
+  const result = runBiome(bin, ['check', '--reporter=github', basename(file)], dir);
+  const remapped = remapGithubOutput(result.stdout, file, 0);
+  if (result.status !== 0 && remapped.errorCount === 0 && remapped.warningCount === 0) {
+    remapped.errorCount++;
+    remapped.lines.push(makeStderrLines(result.stderr));
+  }
+  return remapped;
+}
+
+function processPlainFormat(bin, file, write) {
+  const dir = dirname(file);
+  if (write) {
+    const r = runBiome(bin, ['format', '--write', basename(file)], dir);
+    if (r.status !== 0) {
+      process.stderr.write(`biome-jsh: ${file}: ${makeStderrLines(r.stderr)}\n`);
+      return { stdout: '', failed: true };
+    }
+    return { stdout: '' };
+  }
+  // Biome 2.x `format` (no --write) prints a diff, not the formatted content,
+  // so format a same-extension temp copy in place and read it back.
+  const source = readFileSync(file, 'utf8');
+  const dot = basename(file).lastIndexOf('.');
+  const ext = dot >= 0 ? basename(file).slice(dot) : '';
+  const tempBase = `${basename(file)}.__biomejsh__.${mkToken()}${ext}`;
+  const tempPath = join(dir, tempBase);
+  try {
+    writeFileSync(tempPath, source);
+    const r = runBiome(bin, ['format', '--write', tempBase], dir);
+    if (r.status !== 0) {
+      process.stderr.write(`biome-jsh: ${file}: ${makeStderrLines(r.stderr)}\n`);
+      return { stdout: '', failed: true };
+    }
+    return { stdout: readFileSync(tempPath, 'utf8') };
+  } finally {
+    safeUnlink(tempPath);
+  }
+}
+
+function tempName(file) {
+  const token = mkToken();
+  return `${basename(file)}.__biomejsh__.${token}.js`;
+}
+
+let tokenCounter = 0;
+function mkToken() {
+  tokenCounter += 1;
+  return `${process.pid}-${Date.now()}-${tokenCounter}`;
+}
+
+function makeStderrLines(stderr) {
+  return stderr.trim() === '' ? 'biome exited non-zero' : stderr.trimEnd();
+}
+
+function safeUnlink(path) {
+  try {
+    unlinkSync(path);
+  } catch {
+    // best-effort cleanup
+  }
+}
+
+function fail(message) {
+  process.stderr.write(`biome-jsh: ${message}\n`);
+  process.exit(2);
+}
+
+function runCheck(bin, files, missing) {
+  const outLines = [];
+  let errorCount = missing.length;
+  let warningCount = 0;
+  for (const file of files) {
+    const r = shouldWrapForBiome(file)
+      ? processWrappedCheck(bin, file)
+      : processPlainCheck(bin, file);
+    outLines.push(...r.lines);
+    errorCount += r.errorCount;
+    warningCount += r.warningCount;
+  }
+  if (outLines.length > 0) process.stdout.write(outLines.join('\n') + '\n');
+  process.stderr.write(
+    `biome-jsh: ${files.length} file(s), ${errorCount} error(s), ${warningCount} warning(s)\n`
+  );
+  process.exitCode = errorCount > 0 ? 1 : 0;
+}
+
+function runFormat(bin, files, write, hadMissing) {
+  const stdoutChunks = [];
+  let failed = 0;
+  for (const file of files) {
+    const r = shouldWrapForBiome(file)
+      ? processWrappedFormat(bin, file, write)
+      : processPlainFormat(bin, file, write);
+    if (r.failed) failed += 1;
+    else if (!write && r.stdout) stdoutChunks.push(r.stdout);
+  }
+  if (!write && stdoutChunks.length > 0) process.stdout.write(stdoutChunks.join(''));
+  process.exitCode = hadMissing || failed > 0 ? 1 : 0;
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help || (!parsed.subcommand && parsed.paths.length === 0 && !parsed.version)) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const bin = resolveBiomeBinary();
+  if (parsed.version) {
+    const v = runBiome(bin, ['--version'], process.cwd());
+    process.stdout.write(v.stdout || v.stderr);
+    return;
+  }
+  if (!parsed.subcommand) fail('missing subcommand (expected check or format)');
+  if (parsed.paths.length === 0) fail('no files or directories specified');
+
+  const { files, missing } = expandPaths(parsed.paths);
+  for (const m of missing) process.stderr.write(`biome-jsh: ${m}: no such file or directory\n`);
+
+  if (parsed.subcommand === 'check') runCheck(bin, files, missing);
+  else runFormat(bin, files, parsed.write, missing.length > 0);
+}
+
+main();

package/jsh-biome-source.mjs

@@ -0,0 +1,112 @@
+/**
+ * Pure, dependency-free helpers that make Biome lint/format `.jsh`/`.bsh`
+ * shell scripts correctly. Self-contained so the `biome-jsh` CLI stays
+ * standalone and publishable without a `@slicc/*` dependency.
+ *
+ * `.jsh` scripts and `.bsh` browser helpers run as an AsyncFunction body, so
+ * top-level `await` AND top-level `return` are valid there. Biome's file-mode
+ * parser maps a bare `.jsh`/`.bsh` body to a module and emits a bogus "return
+ * outside of function" parse error, so the body is wrapped in an async
+ * function before Biome sees it and the diagnostics are shifted back.
+ *
+ * This is a byte-aligned mirror of
+ * `packages/webapp/src/shell/supplemental-commands/jsh-biome-source.ts`
+ * (the in-app WASM path). Keep the two in sync when either changes.
+ */
+
+const LINTABLE_EXTENSIONS = new Set([
+  'js',
+  'mjs',
+  'cjs',
+  'jsx',
+  'ts',
+  'mts',
+  'cts',
+  'tsx',
+  'json',
+  'jsonc',
+  'css',
+  'graphql',
+  'gql',
+  'html',
+  'svelte',
+  'vue',
+  'astro',
+  'jsh',
+  'bsh',
+]);
+
+/** True when `path` has an extension Biome (via this wrapper) can lint. */
+export function isLintableFile(path) {
+  const dot = path.lastIndexOf('.');
+  if (dot < 0) return false;
+  return LINTABLE_EXTENSIONS.has(path.slice(dot + 1).toLowerCase());
+}
+
+/**
+ * Map a real path to the virtual path Biome should parse it under. `.jsh`
+ * and `.bsh` both wrap to an AsyncFunction body, so a plain `.js` parser
+ * path is correct for both. Everything else is returned unchanged.
+ */
+export function biomeVirtualPath(realPath) {
+  if (realPath.endsWith('.jsh')) return `${realPath.slice(0, -'.jsh'.length)}.js`;
+  if (realPath.endsWith('.bsh')) return `${realPath.slice(0, -'.bsh'.length)}.js`;
+  return realPath;
+}
+
+/**
+ * Wrapper that gives a `.jsh`/`.bsh` body the same AsyncFunction semantics it
+ * runs under, so top-level `await` and top-level `return` are both valid and
+ * Biome does not emit a bogus "return outside of function" parse error.
+ *
+ * The body is placed at column 0 on its own lines — the prefix ends in a
+ * newline and adds no indentation — so a diagnostic's column is identical to
+ * the real file's column and only its line/byte offset shifts by the prefix.
+ */
+export const JSH_WRAP_PREFIX = 'async function __slicc() {\n';
+export const JSH_WRAP_SUFFIX = '\n}';
+
+/**
+ * UTF-8 byte length of {@link JSH_WRAP_PREFIX}. Biome diagnostic spans are
+ * byte offsets, so a wrapped-source span maps back by subtracting this.
+ */
+export const JSH_WRAP_PREFIX_BYTE_LENGTH = new TextEncoder().encode(JSH_WRAP_PREFIX).length;
+
+/**
+ * Number of newlines the prefix inserts ahead of the body. The `--reporter=github`
+ * output is line/column based, so a diagnostic on the wrapped source maps back
+ * to the real file by subtracting this from its `line`/`endLine`. Because the
+ * prefix is exactly one newline-terminated line at column 0, this is the
+ * line-space equivalent of subtracting {@link JSH_WRAP_PREFIX_BYTE_LENGTH}.
+ */
+export const JSH_WRAP_PREFIX_LINE_COUNT = (JSH_WRAP_PREFIX.match(/\n/g) || []).length;
+
+/** Wrap a `.jsh`/`.bsh` body for Biome. Inverse: {@link unwrapFormattedJsh}. */
+export function wrapJshForBiome(source) {
+  return JSH_WRAP_PREFIX + source + JSH_WRAP_SUFFIX;
+}
+
+/** True when `realPath` is a shell script whose body needs the wrapper. */
+export function shouldWrapForBiome(realPath) {
+  return realPath.endsWith('.jsh') || realPath.endsWith('.bsh');
+}
+
+/**
+ * Strip the async-function wrapper Biome added around a formatted
+ * `.jsh`/`.bsh` body: drop the first line (`async function __slicc() {`) and
+ * the last line (`}`), then remove exactly one leading TAB (Biome's default
+ * indent unit) from each remaining line. A trailing newline is always emitted.
+ *
+ * This de-indent is NOT lossless for multi-line template literals whose
+ * continuation lines start with a real tab — callers MUST guard the result
+ * with a re-format round-trip and fall back to the original content when it
+ * does not reproduce the formatted wrapped output.
+ */
+export function unwrapFormattedJsh(formatted) {
+  const trimmed = formatted.endsWith('\n') ? formatted.slice(0, -1) : formatted;
+  const lines = trimmed.split('\n');
+  lines.shift();
+  lines.pop();
+  const body = lines.map((line) => (line.startsWith('\t') ? line.slice(1) : line));
+  return body.join('\n') + '\n';
+}

package/lib.mjs

@@ -0,0 +1,134 @@
+/**
+ * biome-jsh — pure orchestration logic (no I/O, no process spawning).
+ *
+ * Parses Biome's `--reporter=github` annotation lines, shifts each diagnostic
+ * from the wrapped temp file back onto the real `.jsh`/`.bsh` file (line-space
+ * shift + path rewrite), and enumerates candidate `@biomejs/biome` binary
+ * locations. The I/O — file walking, temp files, spawning Biome, write-back —
+ * lives in `biome-jsh.mjs`. Keeping this module side-effect-free lets the
+ * span-shift + parsing logic be unit-tested without a Biome binary.
+ */
+
+import { dirname, join } from 'node:path';
+
+// Matches a single GitHub Actions workflow-command annotation line, e.g.
+//   ::error title=lint/suspicious/noDoubleEquals,file=a.js,line=3,col=8::msg
+// Group 1 is the level, group 2 the comma-separated `key=value` property
+// block, group 3 the (possibly percent-encoded) message.
+const ANNOTATION_RE = /^::(error|warning|notice)\s+(.*?)::([\s\S]*)$/;
+
+/**
+ * Parse one `--reporter=github` line into `{ level, fields, message }`, or
+ * `null` when the line is not an annotation (Biome also prints a human summary
+ * to stdout/stderr that we ignore). `fields` preserves Biome's key order.
+ */
+export function parseGithubAnnotation(line) {
+  const match = ANNOTATION_RE.exec(line);
+  if (!match) return null;
+  const [, level, propsStr, message] = match;
+  const fields = {};
+  for (const pair of propsStr.split(',')) {
+    const eq = pair.indexOf('=');
+    if (eq < 0) continue;
+    fields[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return { level, fields, message };
+}
+
+/** Reconstruct a GitHub annotation line from a parsed `{ level, fields, message }`. */
+export function formatGithubAnnotation(annotation) {
+  const props = Object.entries(annotation.fields)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(',');
+  return `::${annotation.level} ${props}::${annotation.message}`;
+}
+
+/**
+ * Map a diagnostic computed on the wrapped temp file back onto the real file:
+ * rewrite `file=` to `realPath` and subtract `lineDelta` from `line`/`endLine`
+ * (clamped ≥ 1). Because the wrapper prefix is one newline-terminated line at
+ * column 0, columns are already correct and only the line moves.
+ */
+export function shiftAnnotationToRealFile(annotation, realPath, lineDelta) {
+  const fields = { ...annotation.fields };
+  if (fields.file !== undefined) fields.file = realPath;
+  for (const key of ['line', 'endLine']) {
+    if (fields[key] === undefined) continue;
+    const parsed = Number.parseInt(fields[key], 10);
+    if (Number.isFinite(parsed)) fields[key] = String(Math.max(1, parsed - lineDelta));
+  }
+  return { level: annotation.level, fields, message: annotation.message };
+}
+
+/**
+ * Transform every annotation line of Biome's github-reporter `stdout`: keep
+ * non-annotation lines untouched, and rewrite each annotation's `file=` to
+ * `realPath` while shifting its `line`/`endLine` back by `lineDelta` (0 for
+ * pass-through, non-wrapped files; the prefix line count for wrapped ones).
+ * Returns `{ lines, errorCount, warningCount }`.
+ */
+export function remapGithubOutput(stdout, realPath, lineDelta) {
+  const lines = [];
+  let errorCount = 0;
+  let warningCount = 0;
+  for (const raw of splitLines(stdout)) {
+    const annotation = parseGithubAnnotation(raw);
+    if (!annotation) {
+      lines.push(raw);
+      continue;
+    }
+    if (annotation.level === 'error') errorCount++;
+    else if (annotation.level === 'warning') warningCount++;
+    lines.push(formatGithubAnnotation(shiftAnnotationToRealFile(annotation, realPath, lineDelta)));
+  }
+  return { lines, errorCount, warningCount };
+}
+
+function splitLines(text) {
+  if (text === '') return [];
+  const trimmed = text.endsWith('\n') ? text.slice(0, -1) : text;
+  return trimmed.split('\n');
+}
+
+/**
+ * Build a GitHub error annotation for a real file at `line` (used to surface
+ * "file is not formatted" without any wrapped-source coordinates).
+ */
+export function makeErrorAnnotation(file, message, line = 1) {
+  return {
+    level: 'error',
+    fields: {
+      title: 'format',
+      file,
+      line: String(line),
+      endLine: String(line),
+      col: '1',
+      endColumn: '1',
+    },
+    message,
+  };
+}
+
+/**
+ * Candidate `node_modules/.bin/biome` paths, walking up from each start
+ * directory to the filesystem root. Deduplicated, order-preserving. The CLI
+ * probes these with `existsSync` and uses the first hit.
+ */
+export function biomeBinCandidates(startDirs) {
+  const seen = new Set();
+  const candidates = [];
+  for (const start of startDirs) {
+    let dir = start;
+    for (;;) {
+      const candidate = join(dir, 'node_modules', '.bin', 'biome');
+      if (!seen.has(candidate)) {
+        seen.add(candidate);
+        candidates.push(candidate);
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return candidates;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@ai-ecoverse/biome-jsh",
+  "version": "0.0.0-development",
+  "description": "A jsh-aware Biome runner: lint/format .jsh/.bsh shell scripts (AsyncFunction bodies) without false return/await parse errors.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "biome-jsh": "./biome-jsh.mjs"
+  },
+  "main": "./lib.mjs",
+  "files": [
+    "biome-jsh.mjs",
+    "lib.mjs",
+    "jsh-biome-source.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@biomejs/biome": "^2.5.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ai-ecoverse/slicc",
+    "directory": "packages/dev-tools/biome-jsh"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}