@holdyourvoice/hyv 3.5.1 → 3.6.1

package/Readme.md

@@ -13,63 +13,7 @@ The package also checks hidden Unicode, source-backed facts, document logic, and
 
 ## how it works
 
-```mermaid
-flowchart TD
-    samples["Writing samples"] --> profile["Local VoiceDNA profile"]
-    draft["Draft"] --> analyze["hyv analyze"]
-    profile --> analyze
-    brief["Optional WritingBrief"] -.-> analyze
-
-    subgraph inspect["1 · inspect the draft"]
-        analyze --> voice["VoiceDNA check"]
-        analyze --> patterns["AI pattern lint"]
-        analyze --> hidden["Hidden-text / Unicode check"]
-        voice --> local{"Local result"}
-        patterns --> local
-        hidden -.-> local
-    end
-
-    local -->|No blocking change| candidate["Candidate text"]
-    local -->|Blocking edit scope| editTask["Prepare fingerprint-bound edit task"]
-    local -->|Judgment required| judgment["Prepare and reduce judgments"]
-    judgment --> route{"SHIP, EDIT, or REBUILD?"}
-    route -->|SHIP| candidate
-    route -->|EDIT| editTask
-    route -->|REBUILD| authorization["REBUILD recommendation + CopySpec + signed authorization"]
-    authorization --> rebuildTask["Prepare fingerprint-bound rebuild task"]
-    editTask --> editor["Human editor or model you choose"]
-    rebuildTask --> editor
-    editor --> response["Bound response"]
-
-    brief -.-> logic
-    sources["Optional fact sources in WritingBrief"] -.-> facts
-    spec["Optional for verify-spec; required for rebuild"] -.-> authorization
-    spec -.-> standard
-
-    subgraph verification["2 · verification gate"]
-        candidate --> standard["hyv verify / verify-spec"]
-        response --> mode{"Bound task mode"}
-        mode -->|EDIT| editApply["apply-rewrite + standard verification"]
-        mode -->|REBUILD| rebuildApply["apply-rebuild + rebuild verification"]
-        standard --> standardRules["Preservation gate + CopySpec claims when supplied"]
-        editApply --> standardRules
-        rebuildApply --> rebuildRules["CopySpec claims; preservation reported"]
-        standardRules --> engines["VoiceDNA + AI Editor checks and blocking regressions"]
-        rebuildRules --> engines
-        engines --> logic["Logic lint"]
-        logic --> facts["Fact lint when sources are supplied"]
-        facts --> outputGate["Hidden-text + final-output gate"]
-        outputGate --> passed{"All required checks pass?"}
-    end
-
-    passed -->|No| repair["Repair externally or prepare a new task"]
-    repair --> analyze
-    passed -->|Yes| review["Semantic review and human approval, when required"]
-    review --> final["Run final-check after the last change"]
-    final --> output["Exact accepted text"]
-```
-
-HYV keeps draft inspection, candidate verification, and final delivery separate. Standard verification reruns VoiceDNA and AI Editor, rejects blocking regressions, enforces preservation, runs logic lint, applies fact lint when a WritingBrief supplies sources, and withholds hidden-text failures. `verify-spec` adds CopySpec claim checks. Authorized rebuilds require an upstream REBUILD recommendation, a CopySpec, and signed authorization; their verification reports preservation without using the standard preservation threshold. Run `final-check` again after the last human, model, formatter, or template change. HYV never calls a model; a human editor or model you choose supplies edits and judgments.
+inspect the draft, let your editor make the changes, then verify the candidate and check the exact output. the [architecture guide](docs/ARCHITECTURE.md#writing-workflow) shows the full flow, including judgments, authorized rebuilds, and approval gates.
 
 ## install
 
@@ -131,7 +75,7 @@ producer | hyv final-check -
 | `hyv score <draft> <profile-v3.json> <heldout...>` | Measure the draft against a separate held-out local writing range; may abstain. |
 | `hyv ingest <source> <export> --owner=owner --output=/absolute/dir` | Create redacted, owner-authorized Gmail or Telegram samples and a text-free receipt. |
 | `hyv analyze <draft> <profile.json>` | Run VoiceDNA, AI Editor, and hygiene checks. |
-| `hyv strict-check <draft> <profile-v3.json> <sample...>` | Run the opt-in strict local quality gate. It requires a calibrated V3 profile built from five or more samples, five non-duplicate samples with a consistent visible format and 1,500 words total, and returns `strict-ready`, `needs-human-review`, or `blocked`. |
+| `hyv strict-check <draft> <profile-v3.json> <sample...>` | Run the calibrated local strict-quality gate. It requires a V3 profile built from five or more samples, five non-duplicate validation samples with a consistent visible format and 1,500 words total, and returns `strict-ready`, `needs-human-review`, or `blocked`. |
 | `hyv hygiene <draft> [--fix]` | Inspect hidden Unicode or write a conservative cleaned copy. |
 | `hyv inspect-hidden-text <draft> [policy.json]` | Inspect hidden text with an optional policy. |
 | `hyv apply-hidden-text-policy <draft> <policy.json> <output>` | Apply approved hidden-text removals. |
@@ -143,7 +87,7 @@ producer | hyv final-check -
 | `hyv fact-lint <draft\|-> --source=id:path` | Check claims against local source files. |
 | `hyv logic-lint <draft\|-> [brief.json]` | Check deterministic document logic. |
 | `hyv batch-analyze <draft...>` | Find repeated openings and endings across drafts. |
-| `hyv rewrite-prompt <draft> <profile.json>` | Create a constrained editing brief. |
+| `hyv rewrite-prompt <draft> <profile.json>` | Create a strict constrained editing brief. |
 | `hyv prepare-rewrite ...` | Create a fingerprint-bound edit task. |
 | `hyv apply-rewrite ...` | Apply and verify a response to an edit task. |
 | `hyv prepare-judgment ...` | Create a pre-edit or post-candidate judgment task. |
@@ -159,6 +103,8 @@ producer | hyv final-check -
 | `hyv agent list\|validate\|describe\|emit` | Inspect or emit portable agent contracts. |
 | `hyv mcp` | Start the local MCP server on standard input/output. |
 
+`rewrite-prompt`, `prepare-rewrite`, `apply-rewrite`, and `verify` are strict by default: every active AI Editor finding must be repaired, and verification rejects a candidate that leaves one unresolved. A Profile v3 `disabled` policy is the only deliberate exception. `strict-check` adds the separate calibrated voice-evidence decision.
+
 Most commands return JSON. Exit code `0` means the command completed, `2` means a content or policy gate failed, and `1` means the command or input was invalid.
 
 Run `hyv <command>` without enough arguments to see its exact usage. Read the [CLI reference](docs/wiki/CLI-Reference.md) for every option.

package/dist/ai-editor.js

@@ -104,11 +104,11 @@ export function serializedRules() {
         scope: rule.scope ?? 'sentence',
     }));
 }
-function documentFinding(rule, sentence) {
+function ruleFinding(rule, sentence) {
     return { engine: 'ai_editor', id: rule.id, severity: rule.severity, sentence: sentence.index, excerpt: sentence.text, reason: rule.reason, suggestion: rule.suggestion };
 }
 function documentMatches(rule, prose, mapped) {
-    const at = (index) => mapped[index] ? [documentFinding(rule, mapped[index])] : [];
+    const at = (index) => mapped[index] ? [ruleFinding(rule, mapped[index])] : [];
     if (rule.id === 'ai.repeated-sentence-opening') {
         for (let index = 0; index + 2 < mapped.length; index += 1) {
             const opening = mapped[index].text.match(/^\s*(\p{L}+)/u)?.[1]?.toLocaleLowerCase();
@@ -161,15 +161,7 @@ export function analyzeAiEditor(text, profile) {
     for (const sentence of mapped) {
         for (const rule of sentenceRules) {
             if (rule.expression.test(prose.slice(sentence.start, sentence.end))) {
-                matched.push({
-                    engine: 'ai_editor',
-                    id: rule.id,
-                    severity: rule.severity,
-                    sentence: sentence.index,
-                    excerpt: sentence.text,
-                    reason: rule.reason,
-                    suggestion: rule.suggestion,
-                });
+                matched.push(ruleFinding(rule, sentence));
             }
         }
     }
@@ -184,15 +176,7 @@ export function analyzeAiEditor(text, profile) {
                 ?? mapped.find((candidate) => candidate.start >= lineStart && candidate.start < lineStart + line.length);
             if (!sentence)
                 continue;
-            matched.push({
-                engine: 'ai_editor',
-                id: rule.id,
-                severity: rule.severity,
-                sentence: sentence.index,
-                excerpt: sentence.text,
-                reason: rule.reason,
-                suggestion: rule.suggestion,
-            });
+            matched.push(ruleFinding(rule, sentence));
         }
         lineStart += line.length + 1;
     }

package/dist/cli/agents.js

@@ -0,0 +1,108 @@
+import { writeFileSync } from 'node:fs';
+import { loadAll, validateAll, validateId, sortedIds, describe, emitJson, emitPrompt } from '../agents/index.js';
+import { json } from './io.js';
+function agentFlags(args) {
+    const values = [];
+    let host = 'generic';
+    let mode;
+    let output;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--host') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error('Usage: hyv agent --host HOST requires a value.');
+            host = value;
+            index += 1;
+        }
+        else if (argument.startsWith('--host=')) {
+            const value = argument.slice('--host='.length);
+            if (!value)
+                throw new Error('Usage: hyv agent --host HOST requires a value.');
+            host = value;
+        }
+        else if (argument === '--mode') {
+            const value = args[index + 1];
+            if (value !== 'prompt' && value !== 'json')
+                throw new Error('Usage: hyv agent --mode prompt|json requires a mode.');
+            mode = value;
+            index += 1;
+        }
+        else if (argument.startsWith('--mode=')) {
+            const value = argument.slice('--mode='.length);
+            if (value !== 'prompt' && value !== 'json')
+                throw new Error('Usage: hyv agent --mode prompt|json requires a mode.');
+            mode = value;
+        }
+        else if (argument === '--output') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error('Usage: hyv agent --output FILE requires a value.');
+            output = value;
+            index += 1;
+        }
+        else if (argument.startsWith('--output=')) {
+            const value = argument.slice('--output='.length);
+            if (!value)
+                throw new Error('Usage: hyv agent --output FILE requires a value.');
+            output = value;
+        }
+        else {
+            values.push(argument);
+        }
+    }
+    return { values, host, mode, output };
+}
+export function runAgent(args) {
+    const [subcommand, ...subargs] = args;
+    if (subcommand === 'list') {
+        if (subargs.length)
+            throw new Error('Usage: hyv agent list');
+        const packages = loadAll();
+        const ids = sortedIds(packages);
+        json(ids.map((id) => {
+            const descriptor = packages.get(id).descriptor;
+            return { id, role: descriptor.role, workflow_phase: descriptor.workflow_phase, description: descriptor.description };
+        }));
+        return 0;
+    }
+    if (subcommand === 'validate') {
+        if (subargs.length > 1)
+            throw new Error('Usage: hyv agent validate [id]');
+        const packages = loadAll();
+        const id = subargs[0];
+        if (id !== undefined)
+            validateId(packages, id);
+        validateAll(packages);
+        json({ schema_version: '1.0.0', status: 'PASS', agent: id ?? 'all' });
+        return 0;
+    }
+    if (subcommand === 'describe') {
+        const { values, host, mode, output } = agentFlags(subargs);
+        if (values.length !== 1 || mode !== undefined || output !== undefined)
+            throw new Error('Usage: hyv agent describe <id> [--host HOST]');
+        const packages = loadAll();
+        validateId(packages, values[0]);
+        json(describe(packages.get(values[0]), host));
+        return 0;
+    }
+    if (subcommand === 'emit') {
+        const { values, host, mode, output } = agentFlags(subargs);
+        if (values.length !== 1)
+            throw new Error('Usage: hyv agent emit <id> --mode prompt|json [--host HOST] [--output FILE]');
+        if (!mode)
+            throw new Error('Usage: hyv agent emit <id> --mode prompt|json [--host HOST] [--output FILE]');
+        const packages = loadAll();
+        validateId(packages, values[0]);
+        const pkg = packages.get(values[0]);
+        const body = mode === 'prompt' ? emitPrompt(pkg, host) : `${emitJson(pkg, host)}\n`;
+        if (output !== undefined) {
+            writeFileSync(output, body, { encoding: 'utf8', flag: 'wx' });
+        }
+        else {
+            process.stdout.write(body);
+        }
+        return 0;
+    }
+    throw new Error('Usage: hyv agent <list|validate|describe|emit> ...');
+}

package/dist/cli/checks.js

@@ -0,0 +1,226 @@
+import { linkSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { RULESET_VERSION, serializedRules } from '../ai-editor.js';
+import { parseCopySpec } from '../copy-spec.js';
+import { analyzeBatch } from '../editorial-packs.js';
+import { cleanHygiene, finalOutputCheck, inspectHygiene } from '../hygiene.js';
+import { applyHiddenTextPolicy, inspectHiddenText, parseHiddenTextPolicy } from '../hidden-text.js';
+import { analyze, verify, verifyWithCopySpec } from '../pipeline.js';
+import { formatFactLintReport, lintFacts } from '../fact-linter.js';
+import { lintLogic } from '../logic-linter.js';
+import { inspectDeliveryIntegrity, parseDeliveryIntegrityPolicy } from '../delivery-integrity.js';
+import { evaluateStrictQuality } from '../strict-quality.js';
+import { normalizeFinding, parseSurfacePolicy } from '../disposition.js';
+import { input, readJson, readProfile, readBrief, json } from './io.js';
+function cleanedPath(path) {
+    const extension = extname(path);
+    const stem = extension ? path.slice(0, -extension.length) : path;
+    return `${stem}.cleaned${extension}`;
+}
+function hygieneArguments(args) {
+    const [path, ...options] = args;
+    if (!path)
+        throw new Error('Usage: hyv hygiene draft.md [--fix] [--output=cleaned.md]');
+    let fix = false;
+    let output;
+    for (const option of options) {
+        if (option === '--fix')
+            fix = true;
+        else if (option.startsWith('--output='))
+            output = option.slice('--output='.length).trim();
+        else
+            throw new Error('Usage: hyv hygiene draft.md [--fix] [--output=cleaned.md]');
+    }
+    if (output !== undefined && (!output || !fix))
+        throw new Error('--output requires --fix and a non-empty path.');
+    return { path, fix, ...(output ? { output } : {}) };
+}
+function writeNewFileAtomically(path, text) {
+    const temporaryDirectory = mkdtempSync(join(dirname(resolve(path)), '.hyv-hygiene-'));
+    const temporaryPath = join(temporaryDirectory, 'cleaned');
+    let primaryError;
+    try {
+        writeFileSync(temporaryPath, text, 'utf8');
+        try {
+            linkSync(temporaryPath, path);
+        }
+        catch (error) {
+            const code = error.code;
+            if (!['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EXDEV'].includes(code ?? ''))
+                throw error;
+            throw new Error(`Atomic hygiene output is not supported by this filesystem: ${path}`);
+        }
+    }
+    catch (error) {
+        primaryError = error.code === 'EEXIST' ? new Error(`Hygiene output already exists: ${path}`) : error;
+    }
+    try {
+        rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (!primaryError)
+            console.error(`Warning: output was published, but temporary-file cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (primaryError)
+        throw primaryError;
+}
+export function runDeliveryCheck(args) {
+    const [path, policyPath, ...extra] = args;
+    if (!path || extra.length)
+        throw new Error('Usage: hyv delivery-check <path|-> [policy.json]');
+    const report = inspectDeliveryIntegrity(input(path), policyPath ? parseDeliveryIntegrityPolicy(readJson(policyPath)) : undefined, process.cwd());
+    json(report);
+    return report.passed ? 0 : 2;
+}
+export function runAnalyze(args) {
+    const [draft, profilePath, briefPath] = args;
+    if (!draft || !profilePath)
+        throw new Error('Usage: hyv analyze draft.md profile.json [writing-brief.json]');
+    json(analyze(input(draft), readProfile(profilePath), readBrief(briefPath)));
+    return 0;
+}
+export function runStrictCheck(args) {
+    const [draft, profilePath, ...samplePaths] = args;
+    if (!draft || !profilePath || samplePaths.length < 2)
+        throw new Error('Usage: hyv strict-check draft.md profile-v3.json sample-a.md sample-b.md [sample-c.md ...]');
+    const report = evaluateStrictQuality(input(draft), readProfile(profilePath), samplePaths.map(input));
+    json(report);
+    return report.disposition === 'strict-ready' ? 0 : 2;
+}
+export function runHygiene(args) {
+    const { path, fix, output } = hygieneArguments(args);
+    if (fix && path === '-')
+        throw new Error('hyv hygiene --fix requires a file path so the original can be preserved.');
+    const text = input(path);
+    if (!fix) {
+        json(inspectHygiene(text));
+        return 0;
+    }
+    const outputPath = output ?? cleanedPath(path);
+    if (resolve(outputPath) === resolve(path))
+        throw new Error('Hygiene output must differ from the input path.');
+    const result = cleanHygiene(text);
+    writeNewFileAtomically(outputPath, result.cleaned);
+    json({ ...result.report, changed: result.changed, changes: result.changes, outputPath });
+    return 0;
+}
+export function runInspectHiddenText(args) {
+    const [path, policyPath, ...extra] = args;
+    if (!path || extra.length)
+        throw new Error('Usage: hyv inspect-hidden-text draft.md [policy.json]');
+    json(inspectHiddenText(input(path), policyPath ? parseHiddenTextPolicy(readJson(policyPath)) : undefined));
+    return 0;
+}
+export function runApplyHiddenTextPolicy(args) {
+    const [path, policyPath, output, ...extra] = args;
+    if (!path || !policyPath || !output || extra.length)
+        throw new Error('Usage: hyv apply-hidden-text-policy draft.md policy.json output.md');
+    if (path === '-' || resolve(path) === resolve(output))
+        throw new Error('Hidden-text output must differ from the input path.');
+    const result = applyHiddenTextPolicy(input(path), parseHiddenTextPolicy(readJson(policyPath)));
+    writeNewFileAtomically(output, result.output);
+    json({ ...result, outputPath: output });
+    return 0;
+}
+export function runFinalCheck(args) {
+    const [path, ...options] = args;
+    if (!path || options.length)
+        throw new Error('Usage: hyv final-check <path|->');
+    const result = finalOutputCheck(input(path));
+    if (!result.accepted) {
+        console.error(JSON.stringify(result, null, 2));
+        return 2;
+    }
+    if (result.changed)
+        console.error(JSON.stringify({ changed: true, changes: result.changes }, null, 2));
+    process.stdout.write(result.output);
+    return 0;
+}
+export function runFactLint(args) {
+    const [draftPath, ...options] = args;
+    const sources = [];
+    let metadata;
+    let strict = false;
+    let human = false;
+    if (!draftPath)
+        throw new Error('Usage: hyv fact-lint <draft|-> --source=id:path [--source=id:path] [--metadata=metadata.json] [--strict] [--human]');
+    for (const option of options) {
+        if (option === '--strict') {
+            strict = true;
+            continue;
+        }
+        if (option === '--human') {
+            human = true;
+            continue;
+        }
+        if (option.startsWith('--source=')) {
+            const value = option.slice('--source='.length);
+            const separator = value.indexOf(':');
+            const id = value.slice(0, separator).trim();
+            const path = value.slice(separator + 1);
+            if (separator < 1 || !id || !path)
+                throw new Error('Sources must use --source=id:path.');
+            sources.push({ id, text: input(path) });
+            continue;
+        }
+        if (option.startsWith('--metadata=')) {
+            metadata = JSON.parse(input(option.slice('--metadata='.length)));
+            continue;
+        }
+        throw new Error('Usage: hyv fact-lint <draft|-> --source=id:path [--source=id:path] [--metadata=metadata.json] [--strict] [--human]');
+    }
+    const report = lintFacts({ sources, draft: input(draftPath), metadata });
+    if (human)
+        console.log(formatFactLintReport(report));
+    else
+        json(report);
+    return strict && report.findings.some((item) => item.severity === 'error') ? 2 : 0;
+}
+export function runLogicLint(args) {
+    const [draftPath, briefPath, ...extra] = args;
+    if (!draftPath || extra.length)
+        throw new Error('Usage: hyv logic-lint <draft|-> [writing-brief.json]');
+    const report = lintLogic(input(draftPath), readBrief(briefPath));
+    json(report);
+    return report.passed ? 0 : 2;
+}
+export function runBatchAnalyze(args) {
+    if (args.length < 2)
+        throw new Error('Usage: hyv batch-analyze draft-a.md draft-b.md [draft-c.md]');
+    json(analyzeBatch(args.map(input)));
+    return 0;
+}
+export function runVerify(args) {
+    const [original, candidate, profilePath, briefPath] = args;
+    if (!original || !candidate || !profilePath)
+        throw new Error('Usage: hyv verify original.md candidate.md profile.json [writing-brief.json]');
+    const profile = readProfile(profilePath);
+    const originalText = input(original);
+    const candidateText = input(candidate);
+    const result = verify(originalText, candidateText, profile, readBrief(briefPath));
+    json(result);
+    return result.passed ? 0 : 2;
+}
+export function runVerifySpec(args) {
+    const [original, candidate, profilePath, specPath, briefPath] = args;
+    if (!original || !candidate || !profilePath || !specPath)
+        throw new Error('Usage: hyv verify-spec original.md candidate.md profile.json copy-spec.json [writing-brief.json]');
+    const profile = readProfile(profilePath);
+    const candidateText = input(candidate);
+    const result = verifyWithCopySpec(input(original), candidateText, profile, parseCopySpec(JSON.parse(input(specPath))), readBrief(briefPath));
+    json(result);
+    return result.passed ? 0 : 2;
+}
+export function runPatterns() {
+    json({ version: RULESET_VERSION, rules: serializedRules() });
+    return 0;
+}
+export function runDispositions(args) {
+    const [draft, profilePath, briefPath, surfacePolicyPath] = args;
+    if (!draft || !profilePath)
+        throw new Error('Usage: hyv dispositions draft.md profile.json [writing-brief.json]');
+    const report = analyze(input(draft), readProfile(profilePath), readBrief(briefPath));
+    const policy = surfacePolicyPath ? parseSurfacePolicy(readJson(surfacePolicyPath)) : undefined;
+    json({ version: '1', findings: [report.voiceDna, report.aiEditor, report.editorial].flatMap((engine) => engine?.findings.map((finding) => normalizeFinding(finding, policy)) ?? []) });
+    return 0;
+}

package/dist/cli/context.test.js

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { buildProfile } from '../voice-dna.js';
+test('prepare-rewrite recognizes contexts in either order and rejects duplicates before writing', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'hyv-cli-context-'));
+    try {
+        const draft = join(directory, 'draft.md');
+        const profile = join(directory, 'profile.json');
+        const task = join(directory, 'task.json');
+        const spec = join(directory, 'spec.json');
+        const brief = join(directory, 'brief.json');
+        const ambiguous = join(directory, 'ambiguous.json');
+        const invalid = join(directory, 'invalid.json');
+        const copySpec = { version: '1', audience: 'writers', intent: 'explain', channel: 'general', claims: [{ id: 'mechanism', text: 'I keep the mechanism clear.', evidence: 'The source draft.' }] };
+        const writingBrief = { version: '1', audience: 'writers', intent: 'explain', format: 'general' };
+        writeFileSync(draft, 'I keep the mechanism clear.');
+        writeFileSync(profile, JSON.stringify(buildProfile(['I write plainly. I name the work.', 'I keep the mechanism clear. I avoid filler.'])));
+        writeFileSync(spec, JSON.stringify(copySpec));
+        writeFileSync(brief, JSON.stringify(writingBrief));
+        writeFileSync(ambiguous, JSON.stringify({ ...copySpec, ...writingBrief }));
+        writeFileSync(invalid, '{}');
+        const run = (contexts) => spawnSync(process.execPath, [new URL('../cli.js', import.meta.url).pathname, 'prepare-rewrite', draft, profile, task, ...contexts], { encoding: 'utf8' });
+        for (const contexts of [[spec, brief], [brief, spec]]) {
+            const result = run(contexts);
+            assert.equal(result.status, 0, result.stderr);
+            const prepared = JSON.parse(readFileSync(task, 'utf8'));
+            assert.deepEqual(prepared.copySpec, copySpec);
+            assert.deepEqual(prepared.writingBrief, writingBrief);
+        }
+        const result = run([ambiguous]);
+        assert.equal(result.status, 0, result.stderr);
+        const prepared = JSON.parse(readFileSync(task, 'utf8'));
+        assert.deepEqual(prepared.copySpec, { ...copySpec, ...writingBrief });
+        assert.equal(prepared.writingBrief, undefined);
+        for (const [contexts, error] of [
+            [[spec, spec], 'Prepare-rewrite accepts at most one CopySpec.'],
+            [[brief, brief], 'Prepare-rewrite accepts at most one WritingBrief.'],
+            [[invalid], `Expected a valid CopySpec or WritingBrief at ${invalid}.`],
+        ]) {
+            const before = readFileSync(task, 'utf8');
+            const rejected = run([...contexts]);
+            assert.equal(rejected.status, 1);
+            assert.equal(rejected.stdout, '');
+            assert.equal(rejected.stderr, `${error}\n`);
+            assert.equal(readFileSync(task, 'utf8'), before);
+        }
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});

package/dist/cli/io.js

@@ -0,0 +1,137 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync, readSync, writeFileSync } from 'node:fs';
+import { parseCopySpec } from '../copy-spec.js';
+import { parseWritingBrief } from '../editorial-packs.js';
+import { parseProfile } from '../profile.js';
+import { canonicalJson, parseCanonicalJson } from '../canonical-json.js';
+import { MAX_JSON_BYTES } from '../internal.js';
+export function input(path) {
+    return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
+}
+function parseBoundedJson(text) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_JSON_BYTES)
+        throw new Error('JSON input exceeds the byte limit.');
+    const value = JSON.parse(text);
+    canonicalJson(value);
+    return value;
+}
+function readBoundedDescriptor(descriptor) {
+    const chunks = [];
+    let size = 0;
+    while (size <= MAX_JSON_BYTES) {
+        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, MAX_JSON_BYTES + 1 - size));
+        const count = readSync(descriptor, chunk, 0, chunk.length, null);
+        if (!count)
+            break;
+        chunks.push(chunk.subarray(0, count));
+        size += count;
+    }
+    if (size > MAX_JSON_BYTES)
+        throw new Error('JSON input exceeds the byte limit.');
+    return Buffer.concat(chunks, size).toString('utf8');
+}
+export function readJson(path) {
+    if (path === '-')
+        return parseBoundedJson(readBoundedDescriptor(0));
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY);
+        return parseBoundedJson(readBoundedDescriptor(descriptor));
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+export function capabilityArguments(args) {
+    const values = [];
+    let source;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === '--capability-stdin') {
+            if (source)
+                throw new Error('Choose one capability source.');
+            source = { kind: 'stdin' };
+            continue;
+        }
+        if (args[index] === '--capability-file') {
+            const path = args[index + 1];
+            if (source || !path || path.startsWith('--capability-'))
+                throw new Error('Choose one capability source.');
+            source = { kind: 'file', path };
+            index += 1;
+            continue;
+        }
+        values.push(args[index]);
+    }
+    if (!source)
+        return { values };
+    if (source.kind === 'stdin' && values.includes('-'))
+        throw new Error('Capability stdin cannot be combined with another stdin input.');
+    let raw;
+    if (source.kind === 'stdin')
+        raw = readBoundedDescriptor(0);
+    else {
+        let descriptor;
+        try {
+            descriptor = openSync(source.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            const before = fstatSync(descriptor);
+            if (!before.isFile() || before.uid !== process.geteuid?.() || (before.mode & 0o077) !== 0 || before.nlink !== 1 || before.size > MAX_JSON_BYTES)
+                throw new Error('Capability file is unavailable or unsafe.');
+            raw = readBoundedDescriptor(descriptor);
+            const after = fstatSync(descriptor);
+            if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+                throw new Error('Capability file is unavailable or unsafe.');
+        }
+        catch {
+            throw new Error('Capability file is unavailable or unsafe.');
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+        }
+    }
+    if (Buffer.byteLength(raw, 'utf8') > MAX_JSON_BYTES)
+        throw new Error('JSON input exceeds the byte limit.');
+    return { values, capability: parseCanonicalJson(Buffer.from(raw, 'utf8')) };
+}
+export function readProfile(path) {
+    return parseProfile(JSON.parse(input(path)));
+}
+export function readBrief(path) {
+    return path ? parseWritingBrief(JSON.parse(input(path))) : undefined;
+}
+function tryParse(parse, value) {
+    try {
+        return parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function prepareContext(paths) {
+    let copySpec;
+    let writingBrief;
+    for (const path of paths) {
+        const value = JSON.parse(input(path));
+        const parsedCopySpec = tryParse(parseCopySpec, value);
+        if (parsedCopySpec) {
+            if (copySpec)
+                throw new Error('Prepare-rewrite accepts at most one CopySpec.');
+            copySpec = parsedCopySpec;
+            continue;
+        }
+        const parsedBrief = tryParse(parseWritingBrief, value);
+        if (!parsedBrief)
+            throw new Error(`Expected a valid CopySpec or WritingBrief at ${path}.`);
+        if (writingBrief)
+            throw new Error('Prepare-rewrite accepts at most one WritingBrief.');
+        writingBrief = parsedBrief;
+    }
+    return { copySpec, writingBrief };
+}
+export function json(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+export function canonical(value) { process.stdout.write(`${canonicalJson(value)}\n`); }
+export function writeJson(path, value) {
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}