{"record":{"id":"08d022c4df4a30b1","repo":"pbakaus/impeccable","slug":"usage-surface-brief-mjs-path-list-read-write-t","errorCode":null,"errorMessage":"usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]","messagePattern":"usage: surface-brief\\.mjs <path\\|list\\|read\\|write> \\[target\\] \\[body-file\\] \\[related-target \\.\\.\\.\\]","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugin/skills/impeccable/scripts/surface-brief.mjs","lineNumber":55,"sourceCode":"    if (result.brief) {\n      process.stdout.write(result.brief.text);\n      return;\n    }\n    if (result.candidates.length) process.stderr.write(`${JSON.stringify(result.candidates.map((brief) => summary(brief, projectRoot)), null, 2)}\\n`);\n    process.exit(2);\n  }\n  if (command === 'write') {\n    if (!target || !bodyFile) throw new Error('usage: surface-brief.mjs write <primary-target> <body-file>');\n    const filePath = writeSurfaceBrief({\n      projectRoot,\n      primaryTarget: target,\n      relatedTargets,\n      body: fs.readFileSync(bodyFile, 'utf-8'),\n    });\n    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\\n`);\n    return;\n  }\n  throw new Error('usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]');\n}\n\nfunction isMainModule() {\n  if (!process.argv[1]) return false;\n  try {\n    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1]);\n  } catch {\n    return import.meta.url === pathToFileURL(process.argv[1]).href;\n  }\n}\n\nif (isMainModule()) {\n  try {\n    main(process.argv.slice(2));\n  } catch (error) {\n    process.stderr.write(`${error?.message || error}\\n`);\n    process.exit(1);\n  }","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/pbakaus/impeccable/blob/d14711ae3d1a1dd62dee61a358d27f107c51ccd0/plugin/skills/impeccable/scripts/surface-brief.mjs#L37-L73","documentation":"Thrown by surface-brief.mjs main when the command is missing entirely or is not one of path/list/read/write. It is the catch-all usage error emitted after all known command branches have been checked.","triggerScenarios":"Running `surface-brief.mjs` with no command, or with an unrecognized command like `surface-brief.mjs foo`.","commonSituations":"Typo in the command name, or invoking the script bare expecting default behavior.","solutions":["Use one of the supported commands: `path`, `list`, `read`, or `write`.","Check the script's help/README for the exact command vocabulary.","If automating, assert the command string against the known set before calling."],"exampleFix":"# before\nnode surface-brief.mjs\n\n# after\nnode surface-brief.mjs list","handlingStrategy":"validation","validationCode":"const KNOWN_COMMANDS = new Set(['path', 'list', 'read', 'write']);\nfunction isKnownCommand(cmd) {\n  return typeof cmd === 'string' && KNOWN_COMMANDS.has(cmd);\n}","typeGuard":"function isSurfaceBriefCommand(value) {\n  return value === 'path' || value === 'list' || value === 'read' || value === 'write';\n}","tryCatchPattern":"if (!isSurfaceBriefCommand(command)) {\n  console.error('usage: surface-brief.mjs <path|list|read|write> ...');\n  process.exit(2);\n}","preventionTips":["Assert the command is in the known set before dispatching.","Print the supported commands on no-args invocations.","Generate CLI help from a single source of truth to avoid drift."],"tags":["cli","surface-brief","usage"],"backgroundTag":null,"analyzedSha":"d14711ae3d1a1dd62dee61a358d27f107c51ccd0","analyzedAt":"2026-08-13T00:52:25.771Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}