Egonex-AI/Understand-Anything · error

Usage: node finalize-incremental.mjs <projectRoot>

Error message

Usage: node finalize-incremental.mjs <projectRoot>

What it means

finalize-incremental.mjs is a CLI script that must be invoked with exactly one positional argument, the project root directory, and no options. main() throws this usage error when the argument count is not exactly 1 or when the single argument starts with '--' (i.e. an option flag was passed where the project root is expected).

Source

Thrown at understand-anything-plugin/skills/understand/finalize-incremental.mjs:382

function projectMetadata(previousProject, plan, scan) {
  const languages = [...new Set(
    (scan.files ?? [])
      .map(file => file?.language)
      .filter(language => typeof language === 'string' && language.length > 0),
  )].sort();
  return {
    ...(previousProject ?? {}),
    languages,
    analyzedAt: new Date().toISOString(),
    gitCommitHash: plan.headCommit,
  };
}

async function main() {
  const args = process.argv.slice(2);
  if (args.length !== 1 || args[0].startsWith('--')) {
    throw new Error('Usage: node finalize-incremental.mjs <projectRoot>');
  }
  const projectRoot = realpathSync(args[0]);
  const uaDir = resolveUaDir(projectRoot);
  const intermediateDir = join(uaDir, 'intermediate');
  const plan = readJson(join(intermediateDir, 'incremental-plan.json'));
  const patch = readJson(join(intermediateDir, 'fingerprint-patch.json'));
  const scan = readJson(join(intermediateDir, 'scan-result.json'), { totalFiles: 0 });
  if (!plan || !patch) throw new Error('Incremental plan or fingerprint patch is missing');
  if (patch.baseCommit !== plan.baseCommit || patch.headCommit !== plan.headCommit) {
    throw new Error('Fingerprint patch does not match the incremental plan commits');
  }

  if (plan.action === 'FULL_UPDATE') {
    throw new Error('FULL_UPDATE must run the full /understand pipeline');
  }
  if (plan.action === 'SKIP' && isGeneratedOnly(plan)) {
    process.stdout.write('Generated artifacts only: analysis baseline unchanged\n');
    return;

View on GitHub (pinned to 07edf82a04)

Solutions

1. Invoke with exactly one argument: `node finalize-incremental.mjs <projectRoot>`.
2. Remove any flags — the script supports none; place any option handling in the calling tool instead.
3. Quote the project root path if it contains spaces so it counts as a single argument.

Example fix

// before
node finalize-incremental.mjs --verbose ~/myproject
// after
node finalize-incremental.mjs ~/myproject

const args = process.argv.slice(2);
if (args.length !== 1 || args[0].startsWith('--')) {
  console.error('Usage: node finalize-incremental.mjs <projectRoot>');
  process.exit(1);
}

try {
  await import('./finalize-incremental.mjs');
} catch (err) {
  if (String(err.message).startsWith('Usage: node finalize-incremental.mjs')) {
    console.error('Pass exactly one argument: the project root directory.');
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Running `node finalize-incremental.mjs` with no arguments; with two or more arguments; or passing a flag like `node finalize-incremental.mjs --dry-run /path/to/project` so the first arg starts with '--'.

Common situations: Copy-pasting an invocation from docs and dropping the projectRoot argument; assuming the script supports flags like --help or --verbose; running it from a wrapper that forwards extra arguments.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• Usage: node prepare-incremental.mjs <projectRoot> <baseCommi
• Usage: node prepare-symbol-retry.mjs <projectRoot>
• Invalid input: requires { projectRoot: string, sourceFilePat
• ${flag} requires a value
• Unknown option: ${arg}

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/87b8bea2d11f1e6a. Report an issue: GitHub.