ruvnet/RuView · error · Error

Refusing CLI access: README marker is not a regular file

Error message

Refusing CLI access: README marker is not a regular file

What it means

After confirming the README marker resolves inside the trusted root, repo-trust stats it and requires a regular file. If README.md resolves to a directory, FIFO, or any other non-file node, this error is thrown so the trust check never reads a non-README object.

Source

Thrown at harness/homecore/src/repo-trust.js:34

  'v2/Cargo.toml',
  'v2/crates/homecore/Cargo.toml',
  'v2/crates/homecore-server/Cargo.toml',
  'docs/adr/ADR-126-ruview-native-ha-port-master.md',
]);

function isWithin(parent, child) {
  const rel = relative(parent, child);
  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
}

function readContainedPrefix(root, path, maxBytes) {
  const real = realpathSync(path);
  if (!isWithin(root, real)) {
    throw new Error('Refusing CLI access: repository marker escapes the trusted root');
  }
  const stat = statSync(real);
  if (!stat.isFile()) {
    throw new Error('Refusing CLI access: README marker is not a regular file');
  }
  const buffer = Buffer.alloc(Math.min(stat.size, maxBytes));
  const descriptor = openSync(real, 'r');
  try {
    const bytes = readSync(descriptor, buffer, 0, buffer.length, 0);
    return buffer.subarray(0, bytes).toString('utf8');
  } finally {
    closeSync(descriptor);
  }
}

export function looksLikeHomecoreRepo(path) {
  if (!path || !existsSync(path)) return false;
  return REQUIRED_MARKERS.every((marker) => existsSync(join(path, marker)));
}

export function findHomecoreRepo(start = process.cwd()) {
  let current = resolve(start);

View on GitHub (pinned to 4685618388)

Solutions

Check the node type: ls -ld README.md (or stat on Windows)
If it is a directory, move its contents elsewhere and create a regular README.md file
Re-run the homecore CLI from the repaired checkout

Example fix

# before
$ ls -ld README.md
drwxr-xr-x  README.md/   # accidentally a directory

# after
$ mv README.md README.assets && printf '# RuView\n' > README.md

Defensive patterns

Strategy: validation

Validate before calling

import { statSync } from 'node:fs';
import { join } from 'node:path';
function readmeIsRegularFile(root) {
  try {
    return statSync(join(root, 'README.md')).isFile();
  } catch {
    return false;
  }
}

Prevention

Never create README.md as a directory; keep images in a sibling assets folder
Run ls -ld README.md in onboarding scripts to catch the wrong node type early
Fix the marker on disk instead of suppressing the error — the trust chain depends on it

When it happens

Trigger: README.md exists as a directory (e.g. created via 'mkdir README.md' or a packaging step that makes README a folder), or a symlink pointing to a directory inside the repo.

Common situations: Accidental directory creation, docs layouts that use README.md/ as a folder holding images, symlinked doc trees.

Related errors

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/9579dd4ab8110ef4. Report an issue: GitHub.