@astrosheep/keiyaku 4.6.4 → 4.6.6

package/build/src/cli/render/kanshi-akuma.js

@@ -38,22 +38,26 @@ function endpointFact(id, observed) {
     // cannot name the reason is absent, while a complete read that established absence says so.
     return observed === "missing" ? `${id} (missing)` : id;
 }
-function renderAkuma(report, context) {
-    const section = report.akuma;
+/**
+ * One Akuma board section. The World board omits an empty section because its other
+ * sections already say what the World holds; a category board states that emptiness
+ * itself, since it is the whole answer.
+ */
+function renderAkumaBoard(section, observedAt, context, emptyRows) {
     if (section.kind === "absent")
         return ["AKUMA // absent"];
     if (section.kind === "failed")
         return ["AKUMA // unavailable", "", tone(`! ${safeText(section.failure.message)}`, "alert", context.color)];
     const rows = section.value.rows;
     if (rows.length === 0)
-        return [];
+        return emptyRows;
     const rowLines = rows.map((row) => {
-        const statusTone = akumaStatusTone(row, report.observedAt);
+        const statusTone = akumaStatusTone(row, observedAt);
         const mark = statusTone === null ? akumaMark(row.life) : tone(akumaMark(row.life), statusTone, context.color);
         const lifeAt = "lifeAt" in row ? row.lifeAt : null;
-        const lifeAge = formatAge(lifeAt, report.observedAt);
+        const lifeAge = formatAge(lifeAt, observedAt);
         const life = `${row.life} · ${lifeAge}`;
-        const activityAge = "lastActivityAt" in row && row.lastActivityAt !== null ? formatAge(row.lastActivityAt, report.observedAt) : null;
+        const activityAge = "lastActivityAt" in row && row.lastActivityAt !== null ? formatAge(row.lastActivityAt, observedAt) : null;
         const activity = activityAge === null || activityAge === lifeAge ? [] : [`activity ${activityAge}`];
         const key = row.life === "stranded" && "strandedReason" in row && row.strandedReason === "resume-unsupported"
             ? [life, ...activity, "resume unsupported"]
@@ -85,9 +89,12 @@ function renderAkuma(report, context) {
     const header = `AKUMA // ${rows.length} recent`;
     return [header, ...rendered.slice(1)];
 }
+function renderAkuma(report, context) {
+    return renderAkumaBoard(report.akuma, report.observedAt, context, []);
+}
 function formatAge(source, observedAt) {
     if (source === null || source === undefined)
         return "—";
     return ageText(source, observedAt);
 }
-export { endpointFact, formatAge, NARROW_COLUMNS, renderAkuma };
+export { endpointFact, formatAge, NARROW_COLUMNS, renderAkuma, renderAkumaBoard };

package/build/src/cli/render/kanshi.d.ts

@@ -1,3 +1,5 @@
-import type { KanshiReport } from "../../kanshi/index.js";
+import type { KanshiCategoryReport, KanshiReport } from "../../kanshi/index.js";
 import { type TextRenderContext } from "./terminal.js";
 export declare function renderKanshiText(report: KanshiReport, context?: TextRenderContext, selection?: "world" | "contract"): string;
+/** One category board: the section the selector asked for, and nothing it did not read. */
+export declare function renderKanshiCategoryText(report: KanshiCategoryReport, context?: TextRenderContext): string;

package/build/src/cli/render/kanshi.js

@@ -1,6 +1,6 @@
 import { abbreviateGitIds, afterWording, progressStrip, displayGitId, gateFact, gitIdsInRow, lifecycleWord, mergeSummary, targetMovementFacts, verificationFact, } from "./contract-observation.js";
-import { DEFAULT_CLI_COLUMNS, entityLines, elapsedMilliseconds, identityLine, plumbFacts, RECENT_TONE_MS, renderBoundedPayload, renderSectionBlock, safeText, tone, } from "./terminal.js";
-import { endpointFact, formatAge, NARROW_COLUMNS, renderAkuma } from "./kanshi-akuma.js";
+import { DEFAULT_CLI_COLUMNS, emptyCatalogue, entityLines, elapsedMilliseconds, identityLine, plumbFacts, RECENT_TONE_MS, renderBoundedPayload, renderSectionBlock, safeText, tone, } from "./terminal.js";
+import { endpointFact, formatAge, NARROW_COLUMNS, renderAkuma, renderAkumaBoard } from "./kanshi-akuma.js";
 import { contractMark, taskDispositionMark } from "./marks.js";
 import { dispositionText } from "./task.js";
 const REVIEW_ATTENTION_MS = 15 * 60 * 1_000;
@@ -26,13 +26,11 @@ function contractStatusTone(row, observedAt) {
     const journalAge = elapsedMilliseconds(row.lastJournalAt, observedAt);
     return journalAge !== null && journalAge <= RECENT_TONE_MS ? "recent" : null;
 }
-function gitAbbreviations(report) {
+function contractAbbreviations(section) {
     const ids = [];
-    if (report.contracts.kind !== "present")
-        return abbreviateGitIds(ids);
-    if (report.contracts.value.state !== null)
-        ids.push(report.contracts.value.state);
-    report.contracts.value.rows.forEach((row) => ids.push(...gitIdsInRow(row)));
+    if (section.state !== null)
+        ids.push(section.state);
+    section.rows.forEach((row) => ids.push(...gitIdsInRow(row)));
     return abbreviateGitIds(ids);
 }
 function workspaceState(row) {
@@ -54,10 +52,10 @@ function mergeFacts(row) {
     const summary = mergeSummary(row.workspaceObservation);
     return summary === undefined ? [] : [summary];
 }
-function linkedTask(report, taskId) {
-    if (report.tasks.kind !== "present")
+function linkedTask(tasks, taskId) {
+    if (tasks.kind !== "present")
         return `! ${taskId} · unavailable`;
-    const task = report.tasks.value.rows.find((candidate) => candidate.id === taskId);
+    const task = tasks.value.rows.find((candidate) => candidate.id === taskId);
     return task === undefined
         ? `! ${taskId} · unavailable`
         : `${taskDispositionMark(task.disposition)} ${task.id} · ${dispositionText(task.disposition)}`;
@@ -65,12 +63,12 @@ function linkedTask(report, taskId) {
 function isTerminalAkuma(life) {
     return life === "killed" || life === "stillborn";
 }
-function linkedAkumaSummary(row, report) {
+function linkedAkumaSummary(row, akuma) {
     if (row.roster.length === 0)
         return undefined;
-    if (report.akuma.kind !== "present")
+    if (akuma === undefined || akuma.kind !== "present")
         return "akuma  unavailable";
-    const byId = new Map(report.akuma.value.rows.map((akuma) => [akuma.id, akuma]));
+    const byId = new Map(akuma.value.rows.map((akuma) => [akuma.id, akuma]));
     const known = row.roster
         .map((attached) => byId.get(attached.id))
         .filter((akuma) => akuma !== undefined);
@@ -104,11 +102,11 @@ function payload(label, text, context) {
         truncated: false,
     });
 }
-function liveAlarms(row, report) {
+function liveAlarms(row, tasks) {
     return [
         ...mergeFacts(row),
         ...(row.holder.kind === "unavailable" ? ["task unavailable"] : []),
-        ...(row.holder.kind === "held" && linkedTask(report, row.holder.taskId).startsWith("!")
+        ...(row.holder.kind === "held" && tasks !== undefined && linkedTask(tasks, row.holder.taskId).startsWith("!")
             ? ["task unavailable"]
             : []),
         ...(row.issue === undefined ? [] : ["pending reconciliation"]),
@@ -135,14 +133,14 @@ function staleVerificationFacts(row) {
     const fact = verificationFact(row.verification);
     return fact === undefined ? [] : [fact];
 }
-function renderSelectedContractRow(row, report, context, abbreviations) {
+function renderSelectedContractRow(row, facts, context, abbreviations) {
     const title = row.title ?? "title unavailable";
-    const statusTone = contractStatusTone(row, report.observedAt);
+    const statusTone = contractStatusTone(row, facts.observedAt);
     const lines = [
         ...entityLines({
             mark: statusTone === null ? contractMark(row) : tone(contractMark(row), statusTone, context.color),
             identity: row.id,
-            state: `${lifecycleWord(row.phase)} · ${formatAge(row.phaseAt, report.observedAt)}`,
+            state: `${lifecycleWord(row.phase)} · ${formatAge(row.phaseAt, facts.observedAt)}`,
             title,
             facts: [],
             context,
@@ -170,51 +168,57 @@ function renderSelectedContractRow(row, report, context, abbreviations) {
     }
     if (deniedReview?.current.kind === "attested" && deniedReview.current.summary !== undefined)
         lines.push(...payload("review  ×", deniedReview.current.summary, context));
-    const akuma = linkedAkumaSummary(row, report);
+    const akuma = linkedAkumaSummary(row, facts.akuma);
     if (akuma !== undefined)
         lines.push(...semanticBlock("akuma", [akuma], context));
     if (row.worktreePath !== null)
         lines.push(...semanticBlock("worktree", [`worktree  ${row.worktreePath}`], context));
-    lines.push(...semanticBlock("alarms", liveAlarms(row, report), context));
+    lines.push(...semanticBlock("alarms", liveAlarms(row, facts.tasks), context));
     return lines;
 }
-function renderWorldContractRow(row, report, context) {
+function renderWorldContractRow(row, facts, context, abbreviations) {
     const title = row.title ?? "title unavailable";
-    const abbreviations = gitAbbreviations(report);
     const contractFacts = row.phase === "claimed" || row.phase === "abandoned"
         ? terminalFacts(row, context, abbreviations)
             .filter((fact) => !fact.startsWith("  "))
             .slice(0, 1)
         : [
             progressStrip(row),
-            ...(linkedAkumaSummary(row, report) === undefined ? [] : [linkedAkumaSummary(row, report)]),
-            ...liveAlarms(row, report),
+            ...(linkedAkumaSummary(row, facts.akuma) === undefined ? [] : [linkedAkumaSummary(row, facts.akuma)]),
+            ...liveAlarms(row, facts.tasks),
         ];
-    const statusTone = contractStatusTone(row, report.observedAt);
+    const statusTone = contractStatusTone(row, facts.observedAt);
     return entityLines({
         mark: statusTone === null ? contractMark(row) : tone(contractMark(row), statusTone, context.color),
         identity: row.id,
-        state: formatAge(row.phaseAt, report.observedAt),
+        state: formatAge(row.phaseAt, facts.observedAt),
         title,
         facts: contractFacts,
         context,
     });
 }
-function renderContracts(report, context) {
-    const section = report.contracts;
+/**
+ * One Contract board section. A category board states its own emptiness; the World
+ * board leaves an empty section out because the world is its surrounding answer.
+ */
+function renderContractBoard(section, facts, context, emptyRows) {
     if (section.kind === "absent")
         return ["CONTRACTS // absent"];
     if (section.kind === "failed")
         return ["CONTRACTS // unavailable", "", tone(`! ${safeText(section.failure.message)}`, "alert", context.color)];
     if (section.value.rows.length === 0)
-        return [];
+        return emptyRows;
+    const abbreviations = contractAbbreviations(section.value);
     const rendered = renderSectionBlock({
         name: "CONTRACTS",
-        rows: section.value.rows.map((row) => renderWorldContractRow(row, report, context)),
+        rows: section.value.rows.map((row) => renderWorldContractRow(row, facts, context, abbreviations)),
     });
     const header = "CONTRACTS // recent";
     return [header, ...rendered.slice(1), ...(section.value.hasMore === true ? ["…"] : [])];
 }
+function renderContracts(report, context) {
+    return renderContractBoard(report.contracts, { observedAt: report.observedAt, akuma: report.akuma, tasks: report.tasks }, context, []);
+}
 function renderSelectedContract(report, context) {
     const section = report.contracts;
     if (section.kind === "absent")
@@ -224,7 +228,7 @@ function renderSelectedContract(report, context) {
     const row = section.value.rows[0];
     return row === undefined
         ? ["  keiyaku absent"]
-        : renderSelectedContractRow(row, report, context, gitAbbreviations(report));
+        : renderSelectedContractRow(row, { observedAt: report.observedAt, akuma: report.akuma, tasks: report.tasks }, context, contractAbbreviations(section.value));
 }
 function taskFailureFact(failure) {
     return failure.coordinate === undefined ? failure.message : `${failure.coordinate} · failed ${failure.message}`;
@@ -277,3 +281,11 @@ export function renderKanshiText(report, context = { columns: DEFAULT_CLI_COLUMN
     const blocks = [renderContracts(report, context), renderAkuma(report, context), renderTasks(report, context)].filter((block) => block.length > 0);
     return blocks.length === 0 ? "○ world empty" : blocks.map((block) => block.join("\n")).join("\n\n");
 }
+/** One category board: the section the selector asked for, and nothing it did not read. */
+export function renderKanshiCategoryText(report, context = { columns: DEFAULT_CLI_COLUMNS, color: false }) {
+    if (report.category === "akuma")
+        return renderAkumaBoard(report.akuma, report.observedAt, context, [emptyCatalogue("akuma")]).join("\n");
+    return renderContractBoard(report.contracts, { observedAt: report.observedAt }, context, [
+        emptyCatalogue("contracts"),
+    ]).join("\n");
+}

package/build/src/cli/render/receipt.js

@@ -243,7 +243,12 @@ export function cleanupLines(cleanup, columns) {
 }
 export function leakLines(leak, columns) {
     const lines = [];
-    receiptRow(lines, " ", "verification scratch kept at", [{ text: leak.path, opaque: true }], columns);
+    if (leak.path === undefined) {
+        receiptRow(lines, " ", "verification scratch not retained", [], columns);
+    }
+    else {
+        receiptRow(lines, " ", "verification scratch kept at", [{ text: leak.path, opaque: true }], columns);
+    }
     receiptPayload(lines, "reason", leak.diagnostic);
     return lines;
 }

package/build/src/cli/render/task.d.ts

@@ -22,12 +22,12 @@ type TaskFailure = Extract<TaskMutationResult, {
 /** Task dispositions and relation states are snake_case facts; people read them as words. */
 export declare function dispositionText(word: string): string;
 export declare function taskFrameHead(view: string, scope: string): string;
+export declare function renderDoctor(report: TaskDoctorReport): string;
 /** One addressed show selection rendered directly from its native answer. */
 export declare function renderTaskShow(result: TaskShowResult, context?: TextRenderContext): string;
 /** One list read rendered from its native answer and the leaf's presentation-only scope. */
 export declare function renderTaskList(action: "ls" | "ready" | "blocked" | "query", scope: TaskListScope, result: TaskListOutcome, context?: TextRenderContext): string;
 export declare function renderTaskTree(result: TaskDecompositionTree, context?: TextRenderContext): string;
-export declare function renderTaskDoctor(result: TaskDoctorReport): string;
 export declare function renderTaskContext(result: TaskContextResult, context?: TextRenderContext): string;
 export declare function renderTaskCompose(result: TaskCompositionResult, context?: TextRenderContext): string;
 /** One single-Task mutation answer; `verb` is the literal action the leaf invoked. */

package/build/src/cli/render/task.js

@@ -1,6 +1,6 @@
 import { taskMark } from "./marks.js";
 import { outcomeLines, receiptPayload, receiptRow, refusalLines } from "./receipt.js";
-import { DEFAULT_CLI_COLUMNS, displayColumns, emptyCatalogue, safeText } from "./terminal.js";
+import { DEFAULT_CLI_COLUMNS, displayColumns, emptyCatalogue, renderTextBlock, safeText, } from "./terminal.js";
 export { taskMark } from "./marks.js";
 const DEFAULT_CONTEXT = { columns: DEFAULT_CLI_COLUMNS, color: false };
 /** Task dispositions and relation states are snake_case facts; people read them as words. */
@@ -23,28 +23,7 @@ function entityLines(entity, columns, indent = "") {
     const inline = `${scan} — ${title}`;
     if (displayColumns(inline) <= columns)
         return [inline];
-    return [scan, ...dashTitleLines(title, `${indent}  `, columns)];
-}
-/** Wrap `— <title>` as one unit: the dash never dangles alone at a line end. */
-function dashTitleLines(title, indent, columns) {
-    const words = title
-        .trim()
-        .split(/\s+/u)
-        .filter((word) => word.length > 0);
-    const unit = words.length === 0 ? [`—`] : [`— ${words[0]}`, ...words.slice(1)];
-    const lines = [];
-    let current = indent;
-    for (const word of unit) {
-        const candidate = current === indent ? `${indent}${word}` : `${current} ${word}`;
-        if (current !== indent && displayColumns(candidate) > columns) {
-            lines.push(current);
-            current = `${indent}${word}`;
-        }
-        else
-            current = candidate;
-    }
-    lines.push(current);
-    return lines;
+    return [scan, ...renderTextBlock(title, `${indent}  `, columns, "—")];
 }
 function stateEntity(task) {
     return {
@@ -206,7 +185,7 @@ function doctorIssue(issue) {
         return `! self-relation ${issue.taskId} ${issue.relation}`;
     return `! cycle ${issue.relation} ${issue.tasks.join(" ")}`;
 }
-function renderDoctor(report) {
+export function renderDoctor(report) {
     if (report.issues.length === 0)
         return "✓ doctor  healthy";
     const noun = report.issues.length === 1 ? "issue" : "issues";
@@ -306,9 +285,6 @@ export function renderTaskTree(result, context = DEFAULT_CONTEXT) {
         ? treeLines(result.value, context.columns).join("\n")
         : renderFailure("tree", result, context.columns);
 }
-export function renderTaskDoctor(result) {
-    return renderDoctor(result);
-}
 export function renderTaskContext(result, context = DEFAULT_CONTEXT) {
     if (result.kind !== "accepted")
         return renderFailure("context", result, context.columns);

package/build/src/cli/render/terminal.d.ts

@@ -5,7 +5,7 @@ export type TextRenderContext = Readonly<{
     columns: number;
     color: boolean;
 }>;
-export type GitShortStat = Readonly<{
+type GitShortStat = Readonly<{
     filesChanged: number;
     insertions: number;
     deletions: number;
@@ -50,7 +50,11 @@ type CheckoutNotFollowable = Readonly<{
     paths: readonly string[];
 }>;
 export declare function checkoutNotFollowableLines(refusal: CheckoutNotFollowable): readonly string[];
-export declare function renderTextBlock(value: string, indent: string, columns: number): readonly string[];
+/**
+ * Wrap `value` into the column budget under one indent. A `lead` such as an em dash joins the first
+ * word as one unit, so it never dangles alone at a line end.
+ */
+export declare function renderTextBlock(value: string, indent: string, columns: number, lead?: string): readonly string[];
 export declare function renderOpaqueBlock(value: string, indent: string, columns: number): readonly string[];
 export type SemanticTone = "dim" | "recent" | "attention" | "alert";
 export declare const RECENT_TONE_MS: number;

package/build/src/cli/render/terminal.js

@@ -234,13 +234,19 @@ export function checkoutNotFollowableLines(refusal) {
     }
     return lines;
 }
-export function renderTextBlock(value, indent, columns) {
+/**
+ * Wrap `value` into the column budget under one indent. A `lead` such as an em dash joins the first
+ * word as one unit, so it never dangles alone at a line end.
+ */
+export function renderTextBlock(value, indent, columns, lead) {
     const words = safeText(value)
         .trim()
         .split(/\s+/u)
         .filter((word) => word.length > 0);
     if (words.length === 0)
-        return [indent];
+        return [lead === undefined ? indent : `${indent}${lead}`];
+    if (lead !== undefined)
+        words[0] = `${lead} ${words[0]}`;
     const lines = [];
     let current = indent;
     for (const word of words) {

package/build/src/cli/runtime.js

@@ -15,7 +15,7 @@ import { createExecutionProgressRenderer } from "./render/execution-progress.js"
 import { executionFailureLines } from "./render/receipt.js";
 import { renderRefusal, renderStructuredRefusal } from "./render/refusal.js";
 import { DEFAULT_CLI_COLUMNS, safeText } from "./render/terminal.js";
-import { displayContext, writeJson, writeStderr, writeStdout } from "./streams.js";
+import { displayContext, emit, writeJson, writeStderr, writeStdout } from "./streams.js";
 function processStdin() {
     return (async () => {
         const chunks = [];
@@ -78,11 +78,7 @@ async function admitBindInput(command, invocation, runtime, processCwd) {
 }
 async function runInstall(command, environment) {
     const result = await installHarnesses(command.harnesses, environment);
-    if (command.output === "json")
-        writeJson(result);
-    else
-        writeStdout(renderInstallText(result));
-    return installExitCode(result);
+    return emit(command.output, result, () => renderInstallText(result), installExitCode(result));
 }
 /** Projection of one native Akuma addressing/observation failure into its stated refusal body. */
 export async function akumaFailureProjection(error, command) {
@@ -164,16 +160,7 @@ async function writeFailure(error, command) {
         return akumaFailure.exitCode;
     }
     if (error instanceof AkumaArchetypeError && command.command === "call") {
-        if (command.output === "json")
-            writeJson({
-                kind: "refused",
-                diagnostic: "Akuma not found",
-                archetype: error.archetype,
-                available: "keiyaku ls aku/",
-            });
-        else
-            writeStdout(renderStructuredRefusal("call", `Akuma not found · ${safeText(error.archetype)}`, ["available  keiyaku ls aku/"], usageGuideForCommand(command)));
-        return 1;
+        return emit(command.output, { kind: "refused", diagnostic: "Akuma not found", archetype: error.archetype, available: "keiyaku ls aku/" }, () => renderStructuredRefusal("call", `Akuma not found · ${safeText(error.archetype)}`, ["available  keiyaku ls aku/"], usageGuideForCommand(command)), 1);
     }
     if (command.output === "json")
         writeJson(encodeFailureWire(error));

package/build/src/cli/scan.d.ts

@@ -0,0 +1,26 @@
+/** One surface's option table, named the way its refusal text names the surface. */
+export type ScanFlagKind = "boolean" | "value" | "raw-value" | "repeat";
+export type ScanSpec<Reader extends string = string> = Readonly<{
+    /** Names this surface in refusal text: `bind`, `call`, `task add`. */
+    subject: string;
+    flags: Readonly<Record<string, ScanFlagKind>>;
+    /** The reader that consumes `-` input; absent makes `-` invalid here. */
+    stdin?: Reader;
+    /** Refusal text for `-` on a surface that reads no stdin. */
+    stdinRefusal: string;
+    /** Option whose `-` value is stdin input, named as the reader it selects. */
+    stdinValue?: Reader;
+    /** Tokens this surface refuses everywhere, each with its own option-position refusal text. */
+    refused?: Readonly<Record<string, string>>;
+}>;
+export type ScannedArgs<Reader extends string = string> = Readonly<{
+    flags: Record<string, string | true | readonly string[]>;
+    positionals: readonly string[];
+    stdin?: Reader;
+}>;
+/**
+ * One argument scan for every CLI grammar: `--name value` options, `--` positional-only mode,
+ * `-` stdin, and the surface's own refusal text. A refused token is refused in option position with
+ * its own text, and in value position as the missing-value refusal.
+ */
+export declare function scanArgs<Reader extends string = string>(argv: readonly string[], spec: ScanSpec<Reader>, fail: (message: string) => never): ScannedArgs<Reader>;

package/build/src/cli/scan.js

@@ -0,0 +1,82 @@
+import { isBlankInput } from "./usage.js";
+/** The one `-` reader for this invocation; a second `-` is the duplicate refusal. */
+function selectStdin(spec, stdin, fail) {
+    if (spec.stdin === undefined)
+        fail(spec.stdinRefusal);
+    if (stdin !== undefined)
+        fail("stdin marker '-' may appear only once");
+    return spec.stdin;
+}
+/** A value token this surface refuses: `-`, or one of its own refused tokens. */
+function refusedValue(kind, value, spec) {
+    if (kind === "raw-value")
+        return false;
+    return value === "-" || spec.refused?.[value] !== undefined;
+}
+/** The admitted value after `--name`: absent, dash-like, and blank values carry their own refusals. */
+function optionValue(token, value, kind, spec, fail) {
+    if (value === undefined || value.startsWith("--") || refusedValue(kind, value, spec))
+        fail(`${token} requires a value`);
+    if (kind !== "raw-value" && isBlankInput(value))
+        fail(`${token} requires a nonblank value`);
+    return value;
+}
+/** One `--name` option: a boolean, a repeated value, or a single value. Returns its consumed tokens. */
+function assignOption(option, spec, flags, fail) {
+    const { token, name, kind, value } = option;
+    if (flags[name] !== undefined && kind !== "repeat")
+        fail(`duplicate option: ${token}`);
+    if (kind === "boolean") {
+        flags[name] = true;
+        return 0;
+    }
+    const admitted = optionValue(token, value, kind, spec, fail);
+    flags[name] = kind === "repeat" ? [...(Array.isArray(flags[name]) ? flags[name] : []), admitted] : admitted;
+    return 1;
+}
+/**
+ * One argument scan for every CLI grammar: `--name value` options, `--` positional-only mode,
+ * `-` stdin, and the surface's own refusal text. A refused token is refused in option position with
+ * its own text, and in value position as the missing-value refusal.
+ */
+export function scanArgs(argv, spec, fail) {
+    const flags = {};
+    const positionals = [];
+    let stdin;
+    let positionalOnly = false;
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!positionalOnly && token === "--") {
+            positionalOnly = true;
+            continue;
+        }
+        if (!positionalOnly && spec.refused?.[token] !== undefined)
+            fail(spec.refused[token]);
+        if (!positionalOnly && token === "-") {
+            stdin = selectStdin(spec, stdin, fail);
+            continue;
+        }
+        if (positionalOnly || !token.startsWith("--")) {
+            if (isBlankInput(token))
+                fail(`${spec.subject} requires a nonblank value`);
+            positionals.push(token);
+            continue;
+        }
+        const name = token.slice(2);
+        const kind = spec.flags[name];
+        if (kind === undefined)
+            fail(`option ${token} is not valid for ${spec.subject}`);
+        const reader = spec.stdinValue;
+        const value = kind === "boolean" ? undefined : argv[index + 1];
+        if (reader !== undefined && reader === name && value === "-") {
+            if (stdin !== undefined)
+                fail("stdin marker '-' may appear only once");
+            flags[name] = "";
+            stdin = reader;
+            index += 1;
+            continue;
+        }
+        index += assignOption({ token, name, kind, value }, spec, flags, fail);
+    }
+    return { flags, positionals, ...(stdin === undefined ? {} : { stdin }) };
+}

package/build/src/cli/streams.d.ts

@@ -9,3 +9,8 @@ export declare function displayContext(): TextRenderContext;
 export declare function resultContext(): TextRenderContext;
 /** One JSON product answer, verbatim from the native value. */
 export declare function writeJson(value: unknown): void;
+/**
+ * One product result: JSON writes the untouched native value, text writes the rendered projection,
+ * and the native exit classifier's verdict follows.
+ */
+export declare function emit<Result>(output: "text" | "json", result: Result, text: () => string, code: number): number;

package/build/src/cli/streams.js

@@ -30,3 +30,14 @@ export function resultContext() {
 export function writeJson(value) {
     writeStdout(JSON.stringify(value));
 }
+/**
+ * One product result: JSON writes the untouched native value, text writes the rendered projection,
+ * and the native exit classifier's verdict follows.
+ */
+export function emit(output, result, text, code) {
+    if (output === "json")
+        writeJson(result);
+    else
+        writeStdout(text());
+    return code;
+}