@roughen/cli 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Upforge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @roughen/cli
+
+Lint prose files, page copy or stdin locally with Roughen, plan a whole site's copy pass, and verify the rewrite. No uploads, model calls, or telemetry.
+
+```sh
+roughen ./content --json
+roughen ./content --fix
+roughen ./src --copy --brief
+roughen --stdin --format md --brief
+roughen site . --out ../copy-pass
+roughen verify --git
+```
+
+Safe fixes are the default; `--fix --careful` also applies explicitly careful edits. Manual findings never auto-apply. `--brief` prints a revision brief instead of individual findings: what to rewrite, why, and what must not change. Hand it to a writer or a model.
+
+## Page copy
+
+Named `.tsx`, `.jsx`, `.ts` and `.js` files are read as page copy. That means JSX text, copy attributes such as `alt`, and copy-named properties such as `description`, `answer`, `detail` and `rows`. It also covers FAQ `{ q, a }` pairs, conditional JSX branches, string concatenations, arrays mapped into JSX, and any property whose value reads as prose. In directories, source files are included only with `--copy`. Fixes are never written to source files. Parsing uses `@babel/parser`, the CLI's only dependency beyond Roughen.
+
+Every copy string has a role, listed with its line and key under `copy.strings` in `--json`:
+
+- **body**: paragraphs and descriptions. Every rule applies.
+- **short**: headings, labels, buttons, alt text. Too short for density rules, but still editable.
+- **protected**: leave exactly as written. H1s, `title`/`metaTitle`/`headline`, FAQ questions, `keywords`, schema names, and verbatim words: quotes, testimonials, reviews, citations, and data modules named for them.
+
+Each finding carries the role of the string it sits in. The brief covers only what an editor may rewrite, and names any findings inside protected strings for the owner.
+
+## Config
+
+Config resolves upward from each file via roughen.config.js, .mjs, or .cjs:
+
+```js
+export default {
+  extends: ['marketing'],          // register: 'marketing' — list saturation against human marketing pages
+  voice: {
+    bannedCharacters: ['—'],       // every occurrence is an error, however rare
+    bannedPatterns: [{ pattern: '\\bgenuinely\\b', flags: 'i' }],
+    banned: [{ term: 'utilize', use: 'use' }],
+    required: ['Upforge'],
+  },
+  copy: {
+    body: ['soWhat'],              // project keys that hold copy
+    protected: ['serviceLabel'],   // project keys to leave alone
+    ignore: ['internalNote'],
+    protectedFiles: ['lib/data/citations.js'],
+  },
+  exclude: ['docs/**'],
+};
+```
+
+## `roughen site <dir>`
+
+Use this on a Next.js app-router project. It follows static, dynamic and template-literal imports from every route file (page, layout, template, not-found, error, loading), resolving tsconfig/jsconfig `paths`, and reports:
+
+- copy words and findings per route and per file;
+- copy no route ships;
+- prose in places the reader skips, such as call arguments and unknown variables, so you can add a key to `copy.body`;
+- a work plan: groups of files by route area, around `--group-words` editable words each (default 6,000). Files more than one area ships get their own `shared` groups. No file appears in two groups, so editors can work in parallel.
+
+`--json` includes each file's revision brief. `--out <dir>` writes `PLAN.md`, `plan.json` and `briefs/<group>.md` to a new directory outside the site. Nothing else is written.
+
+## `roughen verify`
+
+`roughen verify --git [<ref>] [<path> ...]` compares every changed file with its version at `<ref>`, which defaults to `HEAD`. `roughen verify --before a.md --after b.md` compares two files. For component copy it pairs strings through the AST with every string blanked, then fails on:
+
+- a code change (reported at its line), an edited import path or non-copy string, or a file that no longer parses;
+- an edited protected string;
+- a number, link or quotation lost, or a number or link added;
+- a new banned character;
+- rewritten copy more than 15% longer or shorter (with ten words of slack), or flagged habits that grew.
+
+It warns on strings outside ±15%, changed headings and new em dashes. Prose files get core's `judgeRevision` whole. New, deleted and untracked files are listed, not judged. Verify is read-only.
+
+## Exit codes and output
+
+Exit codes: 0 for no errors, 1 for lint or verify errors, 2 for invalid input/configuration. JSON output is `{ version, results }` for lint, the plan for `site`, and `{ version, files, errors, warnings, ok }` for `verify`. Findings after fixing point into the fixed text. Directory traversal skips symlinks and build/dependency folders. MIT.

package/bin/roughen.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import { readFile, readdir, lstat, writeFile, chmod, rename, unlink, mkdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { version } from '@roughen/core';
+import { loadConfig, included } from '../lib/config.mjs';
+import { formatFor, lintSource, proseFormats, sourceExtensions } from '../lib/lint-file.mjs';
+import { review } from '../lib/review.mjs';
+import { planSite, renderPlan, renderGroupBrief } from '../lib/site.mjs';
+import { verifyGit, verifyFiles, renderVerify, isCommit } from '../lib/verify.mjs';
+
+const cliVersion = createRequire(import.meta.url)('../package.json').version;
+const help = `Roughen ${cliVersion} (core ${version}) — local prose linting, with explained findings.
+
+Usage: roughen <file|directory ...> [--fix] [--careful] [--json] [--brief] [--copy]
+       roughen --stdin [--format text|md|mdx|html|copy] [--fix] [--brief]
+       roughen site <dir> [--json] [--out <dir>] [--group-words <n>]
+       roughen verify [--git [<ref>]] [<path> ...] [--json]
+       roughen verify --before <file> --after <file> [--json]
+
+  --fix             Apply safe fixes; stdin writes the cleaned text to stdout.
+  --careful         Also apply careful fixes (requires --fix). Never applies manual edits.
+  --brief           Print a revision brief: what to rewrite, why, and what must not change.
+  --copy            In directories, also read copy from .tsx/.jsx/.ts/.js source.
+  --config <path>   Load a local roughen.config.js, .mjs, or .cjs file.
+  --json            Machine-readable results, including residual findings after --fix.
+  --help            Show this help.
+
+Without --config, look upward from each file for roughen.config.{js,mjs,cjs}.
+Directories include .txt, .md, .mdx, and .html (plus source with --copy);
+symlinks are not followed. Named .tsx/.jsx/.ts/.js files are always read as copy:
+JSX text, copy attributes (alt, title, …) and copy-named properties. Fixes are
+never written to source files.
+site: for a Next.js app-router project, follow imports from every route file
+(tsconfig paths included) and report copy words and findings per route and
+per file, copy no route ships, and a work plan: groups of files, no file in
+two, with a revision brief for each. --out writes PLAN.md, plan.json and
+one brief per group to a new directory; nothing else is written.
+
+verify: compare copy before and after a rewrite, file by file. With --git
+(the default) the before is <ref> (default HEAD) and the after is the working
+tree. Fails on code changes, files that no longer parse, edited protected
+strings (H1s, titles, FAQ questions, keywords, quotes), lost or added
+numbers and links, new banned characters, and body length beyond 15%.
+Read-only.
+
+Exit status: 0 no errors, 1 lint errors, 2 invalid input/configuration.
+No network calls, model calls, or telemetry. Calibration scores are unavailable.
+`;
+
+async function filesAt(input, options, discovered = false) {
+  const file = path.resolve(input);
+  const stat = await lstat(file);
+  if (stat.isSymbolicLink()) {
+    if (discovered) return [];
+    throw new Error(`Refusing to follow a symlink: ${file}`);
+  }
+  if (stat.isDirectory()) {
+    const files = [];
+    for (const name of (await readdir(file)).sort()) {
+      if (name.startsWith('.') || ['node_modules', 'dist', 'build', 'coverage', 'out'].includes(name)) continue;
+      files.push(...await filesAt(path.join(file, name), options, true));
+    }
+    return files;
+  }
+  if (!stat.isFile()) return [];
+  const extension = path.extname(file).toLowerCase();
+  if (discovered && !proseFormats[extension] && !(options.copy && sourceExtensions.has(extension) && formatFor(file))) return [];
+  return [file];
+}
+
+async function replaceFile(file, original, replacement) {
+  if (original === replacement) return;
+  if (await readFile(file, 'utf8') !== original) throw new Error(`File changed during linting: ${file}`);
+  const temporary = path.join(path.dirname(file), `.roughen-${randomUUID()}.tmp`);
+  try {
+    const stat = await lstat(file);
+    if (!stat.isFile()) throw new Error(`Not a regular file: ${file}`);
+    await writeFile(temporary, replacement, { flag: 'wx', mode: stat.mode });
+    // The umask narrows the create mode; restore the original bits exactly.
+    await chmod(temporary, stat.mode & 0o7777);
+    await rename(temporary, file);
+  } finally {
+    await unlink(temporary).catch((error) => { if (error.code !== 'ENOENT') throw error; });
+  }
+}
+
+async function readStdin() {
+  process.stdin.setEncoding('utf8');
+  let source = '';
+  for await (const chunk of process.stdin) source += chunk;
+  return source;
+}
+
+async function site(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    json: { type: 'boolean' }, out: { type: 'string' }, 'group-words': { type: 'string' }, config: { type: 'string' },
+  } });
+  if (positionals.length !== 1) throw new Error('Usage: roughen site <dir>; see --help');
+  const groupWords = values['group-words'] ? Number(values['group-words']) : 6000;
+  if (!Number.isInteger(groupWords) || groupWords < 100) throw new Error('--group-words must be a whole number of at least 100');
+  const plan = await planSite(positionals[0], { configPath: values.config, groupWords });
+  if (values.out) {
+    const out = path.resolve(values.out);
+    let existing = null;
+    try { existing = await readdir(out); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (existing?.length) throw new Error(`${out} isn't empty; give --out a new directory`);
+    if (out === plan.root || out.startsWith(`${plan.root}${path.sep}`)) throw new Error('--out must be outside the site; Roughen never writes into the project it reads');
+    await mkdir(path.join(out, 'briefs'), { recursive: true });
+    await writeFile(path.join(out, 'PLAN.md'), renderPlan(plan));
+    await writeFile(path.join(out, 'plan.json'), `${JSON.stringify({ version, ...plan }, null, 2)}\n`);
+    for (const group of plan.plan) await writeFile(path.join(out, 'briefs', `${group.id}.md`), renderGroupBrief(plan, group));
+  }
+  if (values.json) process.stdout.write(`${JSON.stringify({ version, ...plan }, null, 2)}\n`);
+  else process.stdout.write(renderPlan(plan));
+  if (values.out && !values.json) process.stdout.write(`\nWrote PLAN.md, plan.json and ${plan.plan.length} group briefs to ${path.resolve(values.out)}.\n`);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (command === 'site') return site(rest);
+  if (command === 'verify') return verifyCommand(rest);
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+    fix: { type: 'boolean' }, careful: { type: 'boolean' }, json: { type: 'boolean' }, brief: { type: 'boolean' }, copy: { type: 'boolean' },
+    stdin: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, version: { type: 'boolean' },
+    format: { type: 'string' }, config: { type: 'string' },
+  } });
+  if (values.help) { process.stdout.write(help); return; }
+  if (values.version) { process.stdout.write(`roughen ${cliVersion} (core ${version})\n`); return; }
+  if (values.careful && !values.fix) throw new Error('--careful requires --fix');
+  if (values.stdin && positionals.length) throw new Error('Use files or --stdin, not both');
+  if (!values.stdin && !positionals.length) throw new Error('Provide a file/directory or --stdin; see --help');
+  if (values.format && !['text', 'md', 'mdx', 'html', 'copy'].includes(values.format)) throw new Error(`Unsupported format: ${values.format}`);
+  const files = values.stdin ? [null] : [...new Set((await Promise.all(positionals.map((file) => filesAt(file, values)))).flat())].sort();
+  if (!files.length) throw new Error('No supported prose files found');
+  const reports = [];
+  for (const file of files) {
+    const loaded = await loadConfig(file, values.config);
+    if (file && !included(file, loaded)) continue;
+    const { config } = loaded;
+    const detected = file ? formatFor(file) : 'text';
+    // JS/TS is always read as copy; a config's format applies to prose files and stdin.
+    const format = values.format ?? (detected === 'copy' ? 'copy' : config.format ?? detected);
+    if (!format) throw new Error(`Unsupported file extension: ${file}; use --format for explicit prose input`);
+    const source = file ? await readFile(file, 'utf8') : await readStdin();
+    const result = lintSource(source, { file: file ?? 'stdin.tsx', format, config, fix: values.fix && format !== 'copy', careful: values.careful });
+    if (file && values.fix && result.fixed !== undefined) await replaceFile(file, source, result.fixed);
+    // The brief describes the text as it now stands, after any fixes.
+    const reviewed = values.brief ? review(result.fixed ?? source, { file: file ?? 'stdin.tsx', format, config }) : null;
+    reports.push({ file: file ?? '<stdin>', ...result, ...(reviewed ? { brief: reviewed.brief, mechanical: reviewed.mechanical.length } : {}) });
+  }
+  if (!reports.length) throw new Error('no files matched include/exclude');
+  if (values.json) process.stdout.write(JSON.stringify({ version, results: reports }, null, 2) + '\n');
+  else {
+    if (values.stdin && values.fix) process.stdout.write(reports[0]?.fixed ?? '');
+    const stream = values.stdin && values.fix ? process.stderr : process.stdout;
+    for (const report of reports) {
+      if (values.brief) {
+        stream.write(report.brief.text ? `${report.file}\n${report.brief.text}\n` : `${report.file}: nothing to revise.\n`);
+        if (report.mechanical) stream.write(`${report.file}: ${report.mechanical} mechanical fix(es) available with --fix.\n`);
+        continue;
+      }
+      // Each rule's explanation prints once per file; density rules can flag dozens of passages.
+      const explained = new Set();
+      for (const finding of report.findings) {
+        stream.write(`${report.file}:${finding.loc.line}:${finding.loc.column} ${finding.severity} ${finding.ruleId}: ${finding.message}\n`);
+        if (!explained.has(finding.ruleId)) { stream.write(`  ${finding.why}\n`); explained.add(finding.ruleId); }
+      }
+      stream.write(`${report.file}: ${report.findings.length} finding(s)${report.fixes ? `, ${report.fixes.applied} fix(es) applied` : ''}\n`);
+    }
+  }
+  process.exitCode = reports.some((report) => report.findings.some((finding) => finding.severity === 'error')) ? 1 : 0;
+}
+
+async function verifyCommand(args) {
+  // --git takes an optional ref: `--git`, `--git HEAD~2`, `--git=main`. A following path stays a path.
+  let ref = 'HEAD';
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--git=')) { ref = arg.slice(6); continue; }
+    if (arg === '--git') {
+      const next = args[i + 1];
+      if (next && !next.startsWith('-') && !existsSync(next) && isCommit(process.cwd(), next)) { ref = next; i++; }
+      continue;
+    }
+    rest.push(arg);
+  }
+  const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: {
+    json: { type: 'boolean' }, before: { type: 'string' }, after: { type: 'string' }, config: { type: 'string' }, ref: { type: 'string' },
+  } });
+  if (values.ref) ref = values.ref;
+  if (!!values.before !== !!values.after) throw new Error('--before and --after go together');
+  const result = values.before
+    ? await verifyFiles({ before: values.before, after: values.after, configPath: values.config })
+    : await verifyGit({ paths: positionals.length ? positionals : ['.'], ref, configPath: values.config });
+  process.stdout.write(values.json ? `${JSON.stringify({ version, ...result }, null, 2)}\n` : renderVerify(result));
+  process.exitCode = result.ok ? 0 : 1;
+}
+
+main().catch((error) => { process.stderr.write(`roughen: ${error.message}\n`); process.exitCode = 2; });

package/lib/config.mjs

@@ -0,0 +1,86 @@
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import * as presets from '@roughen/config';
+import { protectedByName } from './jsx.mjs';
+
+/** Single source of truth for roughen.config resolution, shared by the CLI and the Claude plugin. */
+export const configNames = ['roughen.config.js', 'roughen.config.mjs', 'roughen.config.cjs'];
+
+function merge(base, extra) {
+  return { ...base, ...extra, rules: { ...base.rules, ...extra.rules }, voice: { ...base.voice, ...extra.voice } };
+}
+
+async function exists(file) {
+  try { await lstat(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+const cache = new Map();
+
+/** The nearest roughen.config above `file` (or `explicit`), merged over its presets. */
+export async function loadConfig(file, explicit) {
+  let configFile = explicit ? path.resolve(explicit) : null;
+  if (!configFile) {
+    let dir = file ? path.dirname(path.resolve(file)) : process.cwd();
+    while (true) {
+      for (const name of configNames) {
+        if (await exists(path.join(dir, name))) { configFile = path.join(dir, name); break; }
+      }
+      if (configFile || path.dirname(dir) === dir) break;
+      dir = path.dirname(dir);
+    }
+  }
+  if (!configFile) return { config: {}, dir: process.cwd() };
+  if (cache.has(configFile)) return cache.get(configFile);
+  const raw = (await import(pathToFileURL(configFile).href)).default;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error(`${configFile} must export a config object`);
+  const supported = new Set(['extends', 'format', 'register', 'include', 'exclude', 'rules', 'voice', 'copy']);
+  for (const key of Object.keys(raw)) if (!supported.has(key)) throw new Error(`Unsupported config option: ${key}`);
+  let config = {};
+  const extensions = raw.extends ?? [];
+  if (!Array.isArray(extensions)) throw new Error('Config extends must be an array');
+  for (const name of extensions) {
+    const key = String(name).replace(/^@roughen\/config\//, '');
+    if (!Object.hasOwn(presets, key)) throw new Error(`Unknown preset: ${name}`);
+    config = merge(config, presets[key]);
+  }
+  for (const key of ['include', 'exclude']) if (raw[key] && (!Array.isArray(raw[key]) || !raw[key].every((value) => typeof value === 'string'))) throw new Error(`${key} must be an array of glob strings`);
+  validateCopy(raw.copy);
+  const merged = merge(config, raw);
+  // Protected-file globs resolve against the config's directory, like include and exclude.
+  if (raw.copy) merged.copy = { ...raw.copy, base: path.dirname(configFile) };
+  const loaded = { config: merged, dir: path.dirname(configFile) };
+  cache.set(configFile, loaded);
+  return loaded;
+}
+
+const copyRoles = ['body', 'short', 'protected', 'ignore', 'protectedFiles'];
+
+/** `copy`: keys a project adds to a role ({ body, short, protected, ignore }) and files whose copy is all protected. */
+function validateCopy(copy) {
+  if (copy === undefined) return;
+  if (!copy || typeof copy !== 'object' || Array.isArray(copy)) throw new Error('copy must be an object');
+  for (const [key, value] of Object.entries(copy)) {
+    if (!copyRoles.includes(key)) throw new Error(`Unsupported copy option: ${key}; use ${copyRoles.join(', ')}`);
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item)) throw new Error(`copy.${key} must be an array of strings`);
+  }
+}
+
+/**
+ * Extraction options for a file: the project's copy keys, and whether the
+ * file's copy is all protected (a copy.protectedFiles glob, or a data module
+ * named for citations, testimonials, reviews or quotes).
+ */
+export function copyOptions(file, config) {
+  const copy = config?.copy;
+  const relative = file && copy?.base ? path.relative(copy.base, path.resolve(file)).split(path.sep).join('/') : null;
+  const listed = !!relative && !!copy.protectedFiles?.some((glob) => path.matchesGlob(relative, glob));
+  return { ...(copy ? { keys: copy } : {}), protectedFile: listed || protectedByName(file) };
+}
+
+/** Whether a config's include/exclude globs admit `file`, relative to the config's directory. */
+export function included(file, { config, dir }) {
+  const relative = path.relative(dir, file).split(path.sep).join('/');
+  if (config.exclude?.some((glob) => path.matchesGlob(relative, glob))) return false;
+  return !config.include?.length || config.include.some((glob) => path.matchesGlob(relative, glob));
+}