@attentionform/astra 0.0.0-stage → 0.2.0

package/dist/packages/cli/src/cli/baseline-gate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The CLI side of the baseline-aware validation gate. A file that already has validator errors can be
+ * written when an edit adds none; `--strict` refuses every error as before.
+ */
+import { BASELINE_MAX_ERRORS, type BaselineVerdict, type ValidationResult } from '@attentionform/astra-engine';
+export { BASELINE_MAX_ERRORS };
+export type ToleratedVerdict = Extract<BaselineVerdict, {
+    kind: 'tolerated';
+}>;
+export type IntroducedVerdict = Extract<BaselineVerdict, {
+    kind: 'introduced';
+}>;
+/**
+ * Judges the result of a gate. A valid result is clean. Otherwise, unless `strict`, the errors are
+ * compared with those of the original bytes, which are validated only now and only when needed.
+ */
+export declare function judgeGate(result: ValidationResult, strict: boolean, original: () => Buffer): Promise<BaselineVerdict>;
+/** True when the gate must refuse the write. */
+export declare function refuses(verdict: BaselineVerdict): boolean;
+/** Wording of a refusal for an edit that adds errors to a file that already had some. */
+export declare function introducedText(verdict: IntroducedVerdict, description: string): string;
+/** Fields added to the JSON output when errors the file already had were tolerated. */
+export declare function toleratedFields(verdict: ToleratedVerdict | undefined): Record<string, unknown>;
+/** The line written to stderr when errors the file already had were tolerated. */
+export declare function toleratedNote(verdict: ToleratedVerdict): string;

package/dist/packages/cli/src/cli/batch-cmd.d.ts

@@ -0,0 +1,177 @@
+import { type DryRunPreview, type StyleGuideConfig } from '@attentionform/astra-engine';
+import { type GlobalOpts } from './output';
+import { type ZipCeilingOverrides } from './io';
+/** Canonical per-action ops examples (`batch --schema`). */
+export declare function batchSchemaPayload(): Record<string, unknown>;
+export interface OpsFile {
+    operations: unknown[];
+    sequential?: boolean;
+    rollbackOnError?: boolean;
+    maxSteps?: number;
+    maxRatio?: number;
+    maxUncompressedBytes?: number;
+}
+export declare function parseOpsFile(raw: string): OpsFile;
+export declare function printBatchSchema(out: GlobalOpts): number;
+/**
+ * Expand CLI-level op extensions before the engine schema gate:
+ * - `insert type:heading level:1..3` -> `insert type:xml` carrying a
+ *   Heading1..3 paragraph (the engine insert schema has no heading type, and
+ *   this CLI must not grow engine-side edges — the rewrite keeps one op, one
+ *   anchor, no extra ids).
+ * - `{action:'clearDoc'}` (alias `clear-doc`) -> counted separately; the body
+ *   reset itself runs via clearDocumentBody() before the remaining ops.
+ */
+export declare function expandCliOps(operations: unknown[]): {
+    ops: unknown[];
+    clearCount: number;
+};
+export interface BackupState {
+    /** Resolved backup path, or undefined when --backup was not given or this is a dry run. */
+    path: string | undefined;
+    done: boolean;
+}
+export interface BatchJob {
+    opsFile: OpsFile;
+    target: string;
+    rowLabel: string | undefined;
+}
+export interface RunBatchJobCtx {
+    file: string;
+    docx: Buffer;
+    opsFile: OpsFile;
+    target: string;
+    sequential: boolean | undefined;
+    skipValidate: boolean;
+    /** --strict: refuse every validator error, including errors the file already had. */
+    strict: boolean;
+    /** --no-history: do not record a history revision, even when the document has a history repository. */
+    noHistory?: boolean;
+    flagCeilings: ZipCeilingOverrides;
+    dryRun: boolean;
+    backupState: BackupState;
+    rowLabel: string | undefined;
+    reproducible: boolean | undefined;
+    macroOpts: {
+        allowMacros: true;
+    } | {
+        stripMacros: true;
+    } | undefined;
+    allowedDir?: string | undefined;
+    /** Resolved --style-guide config (omitted = built-in defaults, byte-identical). */
+    styleGuide?: StyleGuideConfig | undefined;
+    /** Parser diagnostics of the resolved --style-guide (ride JSON styleWarnings). */
+    styleGuideWarnings?: string[] | undefined;
+}
+export declare function resolveBackupPath(file: string, raw: string | undefined): string;
+/**
+ * Snapshot the pre-batch input bytes before the first write. Returns an
+ * exit code when the backup itself fails closed (target left untouched),
+ * or undefined when the backup is done (or not requested / already done).
+ */
+export declare function ensureBackupCopy(out: GlobalOpts, file: string, docx: Buffer, target: string, backupState: BackupState): Promise<number | undefined>;
+/** Split one CSV line (double-quote escaping, "" = literal quote). */
+export declare function splitCsvLine(line: string, source: string): string[];
+/**
+ * Minimal CSV reader for --matrix: first non-blank line is the header,
+ * every later non-blank line is one data row (one row = one --out).
+ */
+export declare function parseMatrixCsv(raw: string, source: string): {
+    headers: string[];
+    rows: Array<Record<string, string>>;
+};
+/**
+ * Literal {{var}} substitution: header names only, single pass over the
+ * original string (values are never re-scanned), no expressions,
+ * conditionals, loops, or filters. Unknown names fail closed.
+ */
+export declare const MATRIX_VAR_RE: RegExp;
+export declare function substituteMatrixString(template: string, row: Record<string, string>, ctx: string): string;
+export declare function substituteMatrixVars(value: unknown, row: Record<string, string>, ctx: string): unknown;
+export declare function truncLine(text: string, max: number): string;
+/** Unified diff of the affected nodes (changed nodes only). */
+export declare function renderUnifiedDiff(preview: DryRunPreview[]): string;
+/** Human + --json report for a successful dry run (writes nothing). */
+export declare function reportDryRun(out: GlobalOpts, args: {
+    file: string;
+    target: string;
+    appliedCount: number;
+    cleared: number;
+    preview: DryRunPreview[];
+    normalized: string[];
+    rowLabel: string | undefined;
+    possiblyStaleBodyRefs?: {
+        nodeId: string;
+        preview: string;
+    }[];
+}): void;
+export declare function cmdBatch(out: GlobalOpts, args: string[]): Promise<number>;
+export declare function runBatchJob(out: GlobalOpts, ctx: RunBatchJobCtx): Promise<number>;
+export type StreamOnError = 'abort' | 'continue';
+export declare const STREAM_DEFAULT_ON_ERROR: StreamOnError;
+export declare const STREAM_DEFAULT_MAX_ERRORS = 10;
+export interface StreamCmdArgs {
+    file: string | undefined;
+    opsPath: string | undefined;
+    outPath: string | undefined;
+    sequential: boolean | undefined;
+    skipValidate: boolean;
+    strict: boolean;
+    noHistory: boolean;
+    flagCeilings: ZipCeilingOverrides;
+    dryRun: boolean;
+    backupGiven: boolean;
+    backupRaw: string | undefined;
+    matrixRaw: string | undefined;
+    targetTextRaw: string | undefined;
+    appendRaw: string | undefined;
+    onErrorRaw: string | undefined;
+    maxErrorsRaw: string | undefined;
+    force: boolean;
+    reproducible: boolean | undefined;
+    macroOpts: {
+        allowMacros: true;
+    } | {
+        stripMacros: true;
+    } | undefined;
+    allowedDir?: string | undefined;
+    /** Resolved --style-guide config (one guide for the invocation; streams apply it wholesale). */
+    styleGuide?: StyleGuideConfig | undefined;
+    /** Parser diagnostics of the resolved --style-guide (ride the stream eof summary). */
+    styleGuideWarnings?: string[] | undefined;
+}
+export interface StreamSessionOpts {
+    file: string;
+    target: string;
+    sequential: boolean | undefined;
+    skipValidate: boolean;
+    strict?: boolean;
+    noHistory?: boolean;
+    flagCeilings: ZipCeilingOverrides;
+    backupState: BackupState;
+    backupSource: Buffer;
+    reproducible: boolean | undefined;
+    macroOpts: {
+        allowMacros: true;
+    } | {
+        stripMacros: true;
+    } | undefined;
+    onError: StreamOnError;
+    maxErrors: number;
+    allowedDir?: string | undefined;
+    /** Resolved --style-guide config (one guide for the whole stream). */
+    styleGuide?: StyleGuideConfig | undefined;
+    /** Parser diagnostics of the resolved --style-guide (ride the stream eof summary). */
+    styleGuideWarnings?: string[] | undefined;
+}
+/**
+ * Flag/arg validation for --stream plus session wiring. Pre-session failures
+ * use the standard fail path (nothing streamed yet, so no acks are owed).
+ */
+export declare function cmdBatchStream(out: GlobalOpts, args: StreamCmdArgs): Promise<number>;
+/**
+ * Resident stream session over an explicit line source. Emits exactly one ack
+ * per non-blank line plus one closing summary, then returns the exit code.
+ * Exported so tests can drive it with array lines (no stdin mocking).
+ */
+export declare function runStreamSession(out: GlobalOpts, docx: Buffer, opts: StreamSessionOpts, lines: Iterable<string> | AsyncIterable<string>, emit: (ack: Record<string, unknown>) => void): Promise<number>;

package/dist/packages/cli/src/cli/create-cmd.d.ts

@@ -0,0 +1,10 @@
+import { type GlobalOpts } from './output';
+export declare const CREATE_TEMPLATES: readonly ["report", "memo", "blank"];
+export type CreateTemplate = (typeof CREATE_TEMPLATES)[number];
+/**
+ * A note for a template that comes with text of its own, or undefined for `blank`. `report` holds a whole sample
+ * report with invented figures, and `memo` holds a heading and a placeholder line.
+ * When Markdown is composed via --from-md or import, the pristine template seed is cleanly replaced.
+ */
+export declare function templateSampleNote(template: string, composed: boolean): string | undefined;
+export declare function cmdCreate(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/errors.d.ts

@@ -0,0 +1,86 @@
+import { type EngineErrorCode } from '@attentionform/astra-engine';
+import { type GlobalOpts } from './output';
+export declare const KNOWN_CLI_CODES: readonly EngineErrorCode[];
+export type KnownCliCode = EngineErrorCode;
+/** Collapse to one line and strip V8 frames / absolute paths. */
+export declare function cleanCliMessage(raw: string): string;
+/** Rewrite engine/MCP-surface remedy names to CLI-correct ones. */
+export declare function rewriteMcpRemedies(message: string): string;
+/**
+ * Sanitize a verbose stack for stderr: same hygiene as the one-liner
+ * (relative paths, no emoji, no absolute paths) but multi-line so `at`
+ * frames survive. Used only when `--verbose` is set; default output is
+ * untouched (exactly one line, never frames).
+ */
+export declare function sanitizeVerboseDetail(raw: string): string;
+/** Classify an operational failure into { code, message, remedy }. */
+export declare function toCliError(err: unknown, opts?: {
+    file?: string;
+    fallbackCode?: KnownCliCode;
+    fallbackRemedy?: string;
+}): {
+    code: KnownCliCode;
+    message: string;
+    remedy: string;
+    verboseDetail?: string;
+};
+/** Emit the canonical one-line human error (+ optional --json) and return EXIT_FAIL. */
+export declare function failHuman(out: GlobalOpts, err: unknown, opts?: {
+    file?: string;
+    fallbackCode?: KnownCliCode;
+    fallbackRemedy?: string;
+    extra?: Record<string, unknown>;
+}): number;
+export declare function fail(out: GlobalOpts, message: string, extra?: Record<string, unknown>): number;
+/**
+ * Gate engine-side console chatter (console.error/console.warn) during an
+ * engine call. The engine logs raw diagnostics (stacks, absolute paths) that
+ * would break CLI error hygiene; the CLI's own one-line [CODE] error carries
+ * the failure instead. Both default and `--verbose` gate the raw output so
+ * the canonical one-liner stays first; `--verbose` re-adds sanitized frames
+ * after it via failHuman/failWithCode (relative paths, no emoji).
+ */
+export declare function withGatedEngineOutput<T>(_out: GlobalOpts, fn: () => Promise<T>): Promise<T>;
+export type CliErrorCode = EngineErrorCode;
+/** Extract the engine code from an error (`.code` prop or message prefix). */
+export declare function extractCliErrorCode(err: unknown): CliErrorCode | undefined;
+/** Extract with fallback (strict: callers always name the expected code). */
+export declare function resolveCliErrorCode(err: unknown, fallback: CliErrorCode): CliErrorCode;
+/** Ensure a human message carries its `[CODE]` prefix plus remedy. */
+export declare function ensureCliErrorCodePrefix(message: string, code: CliErrorCode, remedy?: string): string;
+export declare function failWithCode(out: GlobalOpts, message: string, code: KnownCliCode, extra?: Record<string, unknown>, remedy?: string, verboseDetail?: unknown): number;
+export declare function inferBatchCode(err: unknown, fallback?: CliErrorCode): CliErrorCode;
+export interface FileReadClassification {
+    code: KnownCliCode;
+    message: string;
+    remedy: string;
+}
+/**
+ * Normalize a file-read failure to the single missing/corrupt shape the
+ * human one-liner uses (same regexes, messages, and remedies as
+ * toCliError above). Batch read sites bypass toCliError via failWithCode
+ * with the raw message, so they classify here first: without this the raw
+ * ENOENT/ADM-ZIP/EISDIR text leaks into the one-liner with the wrong
+ * remedy. Returns undefined when the error is not a read failure and the
+ * caller should keep its existing code/remedy path.
+ */
+export declare function classifyFileReadError(err: unknown, file: string): FileReadClassification | undefined;
+/**
+ * Location-aware remedy for a post-batch OOXML gate failure. Mirrors the
+ * wording and branch logic of the MCP save path
+ * (packages/mcp-server/src/lib/mcp/diff.ts remedyForValidationError) with
+ * CLI verbs (`astra inspect` / `astra batch` / retry instead of TOON /
+ * execute_batch / save_document). The fallback keeps the long-standing
+ * generic values hint byte-identical for shapes no branch names.
+ */
+export declare function remedyForPostBatchValidation(xPath: unknown, description: unknown): string;
+/** Remedy text without a leading `Remedy:` label or trailing punctuation. */
+export declare function normalizeRemedyText(raw: unknown): string | undefined;
+/** Pull an engine `Remedy: ...` out of a raw error message, if present. */
+export declare function extractEngineRemedy(rawMsg: string): string | undefined;
+/**
+ * Read an engine `.remedy` prop (tmp/sandbox throws carry the remedy ONLY on
+ * the prop — e.g. `$ASTRA_TMPDIR` symlink refusals — with no `Remedy:` text
+ * in the message, so message-only extraction loses it).
+ */
+export declare function readErrRemedyProp(err: unknown): string | undefined;

package/dist/packages/cli/src/cli/export-cmd.d.ts

@@ -0,0 +1,2 @@
+import { type GlobalOpts } from './output';
+export declare function cmdExport(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/history-cmd.d.ts

@@ -0,0 +1,5 @@
+import { type GlobalOpts } from './output';
+export declare function cmdHistory(out: GlobalOpts, args: string[]): Promise<number>;
+export declare function cmdPreviewRevert(out: GlobalOpts, args: string[]): Promise<number>;
+export declare function cmdRevert(out: GlobalOpts, args: string[]): Promise<number>;
+export declare function cmdRedo(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/history-support.d.ts

@@ -0,0 +1,38 @@
+import { DocxParser } from '@attentionform/astra-engine';
+export declare function capCommitMessage(message: string): string;
+/** Sidecar `.git` state: a real repo directory, a stray non-directory entry, or absent. */
+export type SidecarGitState = 'repo' | 'stray' | 'absent';
+/**
+ * Classify the sidecar's `.git` entry. `stray` is a refusal state: a `.git`
+ * FILE (e.g. a leftover `gitdir:` link) redirects the repository elsewhere;
+ * isomorphic-git follows it, so writes would land outside the sidecar and
+ * reads would loop back to the "no sidecar" gate — never treat it as absent.
+ * Symlinks are followed like isomorphic-git does: a link to a real directory
+ * is a usable repo; a link to a file or a broken link is stray.
+ */
+export declare function sidecarGitState(file: string): SidecarGitState;
+/** Is a valid sidecar chain present for this document? */
+export declare function hasHistorySidecar(file: string): boolean;
+/** Tracked package files (everything but document.xml) from a live snapshot. */
+export declare function trackedExtras(snapshot: Map<string, Buffer>): Map<string, Buffer>;
+export declare function extrasRecord(extras: Map<string, Buffer>): Record<string, Buffer>;
+export type BatchRevisionResult = {
+    recorded: true;
+    commit: string;
+} | {
+    recorded: false;
+    reason: string;
+} | null;
+/**
+ * Records the document just written by a command as a history revision, but only when the document
+ * already has a history repository and the command wrote the document itself (not an `--out` copy).
+ * Returns null when nothing was due. A failure is reported on stderr and in the result; the command
+ * keeps its exit code, because the file was written.
+ */
+export declare function recordBatchRevision(args: {
+    file: string;
+    target: string;
+    parser: DocxParser;
+    message: string;
+    noHistory: boolean;
+}): Promise<BatchRevisionResult>;

package/dist/packages/cli/src/cli/import-cmd.d.ts

@@ -0,0 +1,2 @@
+import { type GlobalOpts } from './output';
+export declare function cmdImport(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/inspect-cmd.d.ts

@@ -0,0 +1,3 @@
+import { type Fidelity, type GlobalOpts } from './output';
+export declare function parseFidelity(raw: string | undefined): Fidelity | undefined;
+export declare function cmdInspect(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/io.d.ts

@@ -0,0 +1,70 @@
+export declare function readDocx(file: string): Promise<Buffer>;
+/**
+ * R-44: read piped stdin fully as UTF-8 (for `batch <docx> -`).
+ * Callers check `process.stdin.isTTY` first and reject a terminal with a
+ * usage error, so this never blocks on interactive input. A closed pipe
+ * with no data (`< /dev/null`) resolves to '' and the caller rejects that
+ * as a usage error too — empty check, not a timeout, so a slow-but-live
+ * pipe still completes while empty stdin fails fast with exit 2.
+ */
+export declare function readStdinText(): Promise<string>;
+export interface ZipCeilingOverrides {
+    maxRatio?: number;
+    maxUncompressedBytes?: number;
+}
+/** Validate a `--max-ratio <n>` value: positive finite number (cap guards typos). */
+export declare function parseMaxRatioFlag(raw: string | undefined): number;
+/** Validate a `--max-uncompressed-bytes <n>` value: positive integer bytes. */
+export declare function parseMaxUncompressedBytesFlag(raw: string | undefined): number;
+export interface MacroFlagChoice {
+    allowMacros: boolean;
+    stripMacros: boolean;
+}
+export declare function macroOptsFromFlags(f: MacroFlagChoice): {
+    allowMacros: true;
+} | {
+    stripMacros: true;
+} | undefined;
+export declare function macroFlagsUsageError(): string;
+/**
+ * A package that still holds macro parts has to be saved as .docm or .dotm; Word refuses a .docx that has them.
+ * Returns the refusal text when the output name does not fit the parts that stay in the file, else null.
+ */
+export declare function macroOutputRefusal(command: string, output: string, macroParts: readonly string[], stripped: boolean): string | null;
+/**
+ * `--strip-macros` leaves a plain document, so it cannot be written under a macro-enabled name (.docm, .dotm):
+ * Word would refuse the file. Returns the refusal text for such a target, else null.
+ */
+export declare function macroStripNameRefusal(command: string, target: string, remedy: string): string | null;
+/**
+ * Scope ceiling overrides around a DocxParser load. The engine resolves
+ * ceilings from env at check time (pre-read + central-directory gates), so
+ * temporarily setting the env is the non-invasive plumb for CLI flags.
+ * Restores prior values (including unset) afterwards.
+ */
+export declare function withZipCeilingEnv<T>(ceilings: ZipCeilingOverrides, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Reproducible scoping: explicit --no-reproducible sets ASTRA_NO_REPRODUCIBLE=1
+ * around engine + save so revision/comment/cover dates see wall-clock;
+ * explicit --reproducible clears the opt-out and pins ASTRA_REPRODUCIBLE=1;
+ * undefined leaves env untouched (default deterministic unless env opts out).
+ */
+export declare function withReproducibleEnv<T>(reproducible: boolean | undefined, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Author scoping: --author <name> sets ASTRA_AUTHOR around the engine run, so the document's
+ * default author (used by every tracked change and comment that does not name one) is the
+ * caller's. undefined leaves the environment untouched.
+ */
+export declare function withAuthorEnv<T>(author: string | undefined, fn: () => T | Promise<T>): Promise<T>;
+export { computeDocStats, tableCellTextSpaced } from '@attentionform/astra-engine';
+export type { DocStats } from '@attentionform/astra-engine';
+export declare function escapeXmlText(text: string): string;
+export declare function buildSnippet(text: string, query: string, radius?: number, maxLen?: number): string;
+/**
+ * Reset the document body to a single empty paragraph, keeping styles,
+ * numbering, settings and all package props byte-identical. CLI-level only:
+ * the engine schema has no clear op, so `batch` expands `{action:'clearDoc'}`
+ * through this function before the remaining ops run.
+ */
+export declare function clearDocumentBody(buf: Buffer): Buffer;
+export declare function writeDocx(file: string, buf: Buffer): Promise<void>;

package/dist/packages/cli/src/cli/normalize-cmd.d.ts

@@ -0,0 +1,9 @@
+import { type GlobalOpts } from './output';
+/**
+ * Repair-as-action entry for legacy files: runs the engine allowlist
+ * normalizer (display-only against the core API — see the surface block at
+ * the top of this file), then the strict validation gate, then writes.
+ * Chosen over a `validate --fix` alias: `validate` is pinned read-only
+ * fail-closed by scripts, so a mutating alias would break its contract.
+ */
+export declare function cmdNormalize(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/output.d.ts

@@ -0,0 +1,98 @@
+export declare const CLI_NAME = "astra";
+export declare const CLI_VERSION: string;
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAIL = 1;
+export declare const EXIT_USAGE = 2;
+/** Fallback terminal width when --wrap cannot detect one (piped stdout). */
+export declare const INSPECT_DEFAULT_WRAP_COLUMNS = 80;
+/**
+ * Resolve the human-presentation wrap width for inspect: an explicit
+ * --width wins; --wrap auto-detects the terminal width (fallback 80 when
+ * piped or unknown); neither means no wrapping (machine 1-line-per-node
+ * default stays). `columns` is injectable for tests; callers omit it to
+ * read process.stdout.columns.
+ */
+export declare function resolveInspectWidth(opts: {
+    width?: number;
+    wrap?: boolean;
+    columns?: number | undefined;
+}): number | undefined;
+export type NormalizedRewrite = string;
+/** Display-only read of the core's own normalizer log (defensive: [] when absent). */
+export declare function readParserNormalizations(parser: unknown): NormalizedRewrite[];
+/** Display-only read of an engine result's `normalized` report (defensive: [] when absent). */
+export declare function readEngineNormalized(res: unknown): NormalizedRewrite[];
+/**
+ * Display-only would-be rewrites for dry-run: parse + rezip a copy through
+ * the core and report its log, discarding the bytes. No repair logic here —
+ * the copy is thrown away, nothing is written. Parse failures propagate to
+ * the caller so a corrupt input fails closed instead of reporting empty.
+ */
+export declare function previewNormalizedForDisplay(buf: Buffer, macroOpts?: {
+    allowMacros?: boolean;
+    stripMacros?: boolean;
+}): NormalizedRewrite[];
+/** Display-only repair entry: core parse + rezip (the hook heals), or passthrough on failure. */
+export declare function applyNormalizerForDisplay(buf: Buffer, macroOpts?: {
+    allowMacros?: boolean;
+    stripMacros?: boolean;
+}): {
+    buffer: Buffer;
+    normalized: NormalizedRewrite[];
+};
+/** Inline `normalized=N [...]` fragment for result lines (bounded to 5 shown). */
+export declare function formatNormalizedInline(list: readonly string[]): string;
+/**
+ * Merge core logs across the rezips one save performs (gate rezip + save
+ * rezip), dropping exact duplicates. The gate's internal rezip already heals
+ * and logs, so reading only the final rezip would report a dishonest zero —
+ * capture both, report every rewrite once.
+ */
+export declare function mergeNormalized(...lists: string[][]): string[];
+/**
+ * T-13: ANSI escape sequence regex — CSI (with `;` and `:` sub-params for
+ * colon truecolor `38:2::r:g:b` / `4:3`), OSC hyperlinks/titles (`ESC ] … BEL/ST`),
+ * charset designators (`ESC ( B`), and residual single-char ESC sequences.
+ * Alternation order matters: OSC first so `ESC ] …` is consumed whole instead
+ * of partially matching the CSI branch.
+ */
+export declare const ANSI_REGEX: RegExp;
+/**
+ * T-13: Strip ANSI escape sequences from text.
+ */
+export declare function stripAnsi(text: string): string;
+/**
+ * T-13: Check if color stripping is required (!process.stdout.isTTY or
+ * NO_COLOR present with a non-empty value, per https://no-color.org:
+ * empty-string NO_COLOR must NOT strip).
+ */
+export declare function shouldStripColor(stream?: 'stdout' | 'stderr' | {
+    isTTY?: boolean;
+}): boolean;
+/**
+ * T-13: Format message respecting TTY and NO_COLOR.
+ */
+export declare function formatCliOutput(message: string, stream?: 'stdout' | 'stderr' | {
+    isTTY?: boolean;
+}): string;
+/**
+ * T-13: Serialize a --json payload, stripping ANSI when color is disabled
+ * (non-TTY stdout or non-empty NO_COLOR). ANSI inside JSON string values
+ * must not leak raw escapes into piped JSON consumers.
+ */
+/**
+ * Recursively strip ANSI from JSON string values (arrays + plain objects).
+ * JSON.stringify escapes raw ESC as `\\u001b` text, so stripping must happen
+ * BEFORE serialization — a post-serialization regex would miss the escaped
+ * form. Non-plain objects pass through untouched.
+ */
+export declare function stripAnsiDeep(value: unknown): unknown;
+export declare function stringifyJsonPayload(payload: unknown, space?: string | number): string;
+export type Fidelity = 'compact' | 'standard' | 'full';
+export interface GlobalOpts {
+    json: boolean;
+    verbose: boolean;
+}
+export declare function print(out: GlobalOpts, message: string): void;
+export declare function printStderr(message: string): void;
+export declare function printJson(out: GlobalOpts, payload: unknown): void;

package/dist/packages/cli/src/cli/run.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Testable entrypoint: returns the process exit code instead of exiting.
+ * Never throws for expected failures (fail-closed codes); unexpected throws
+ * are caught and mapped to EXIT_FAIL.
+ */
+export declare function run(argv: string[]): Promise<number>;

package/dist/packages/cli/src/cli/sanitize-cmd.d.ts

@@ -0,0 +1,26 @@
+import { type GlobalOpts } from './output';
+export declare function isSanitizeBodyPartName(name: string): boolean;
+export declare function isSanitizeCommentFamilyName(name: string): boolean;
+export declare function isSanitizeStyleFamilyName(name: string): boolean;
+export declare function isSanitizeGenericTextName(name: string): boolean;
+/**
+ * Count revision/comment markup surviving in a sanitized package (count-only,
+ * never echoes values). Revisions cover w:ins/w:del/move + cell markers +
+ * range markers + *Change wrappers; comments cover range/reference elements
+ * plus comment definitions in comment parts. Used to gate the partial-flag
+ * WARNING so a clean file stays quiet.
+ */
+export declare function countSanitizeSurvivors(docxBuf: Buffer): {
+    revisions: number;
+    comments: number;
+};
+/**
+ * Structural locations of body PII that sanitize will redact (count-only,
+ * never echoes values). One entry per redaction hit (`part#p<idx>` for
+ * body/comment parts, `part#text` for generic text carriers). Bounded at
+ * 1000 entries. Falls back to part-level markers when paragraph slicing
+ * finds nothing but the whole-part count is non-zero, so a non-zero
+ * bodyRedactions count never prints with an empty location list.
+ */
+export declare function collectBodyPiiLocations(inputBuf: Buffer): string[];
+export declare function cmdSanitize(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/search-cmd.d.ts

@@ -0,0 +1,2 @@
+import { type GlobalOpts } from './output';
+export declare function cmdSearch(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/stats-cmd.d.ts

@@ -0,0 +1,2 @@
+import { type GlobalOpts } from './output';
+export declare function cmdStats(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/usage.d.ts

@@ -0,0 +1,8 @@
+import { type GlobalOpts } from './output';
+export declare function printUsage(out: GlobalOpts): number;
+export declare const USAGE_CODE = "E_USAGE";
+export declare const USAGE_REMEDY = "check arguments with `astra --help` (or `astra <command> --help`), then retry";
+export declare function usage(out: GlobalOpts, message?: string): number;
+export declare function commandHelpText(cmd: string): string | undefined;
+export declare function printCommandHelp(out: GlobalOpts, cmd: string): number;
+export declare function hasHelpFlag(args: string[]): boolean;

package/dist/packages/cli/src/cli/validate-cmd.d.ts

@@ -0,0 +1,2 @@
+import { type GlobalOpts } from './output';
+export declare function cmdValidate(out: GlobalOpts, args: string[]): Promise<number>;

package/dist/packages/cli/src/cli/visual-cmd.d.ts

@@ -0,0 +1,34 @@
+import { renderDocxToImages, type DocumentAST, type VisualImageFormat, type VisualTelemetry } from '@attentionform/astra-engine';
+import { type GlobalOpts } from './output';
+/**
+ * Single CLI visual-telemetry builder (two entry points: `visual` below and
+ * `inspect --visual` in inspect-cmd.ts — both call this, never the engine
+ * directly, so the wireframe/warnings stay identical across surfaces).
+ * `renderTotalPages` is the renderer's (LibreOffice) actual page count: the
+ * single source of truth for the `[PAGE n OF m]` marker whenever it differs
+ * from the word-layout map embedded in the structural summary.
+ */
+export declare function buildCliVisualTelemetry(ast: DocumentAST, summary: unknown, page?: number, renderTotalPages?: number): VisualTelemetry;
+/**
+ * Single CLI visual-render path (two entry points: `visual --out` below and
+ * `inspect --visual` in inspect-cmd.ts — both call this, never
+ * `renderDocxToImages` directly, so DPI/quality/page-selection stay
+ * identical: same `pages: [page]` + `format` args on every invocation).
+ */
+export declare function buildCliVisualRenderArgs(page: number, format: VisualImageFormat): {
+    pages: [number];
+    format: VisualImageFormat;
+};
+export declare function renderCliVisualPage(buf: Buffer, page: number, format: VisualImageFormat): Promise<Awaited<ReturnType<typeof renderDocxToImages>>>;
+/**
+ * Single CLI visual-telemetry printer (both entry points call this, so the
+ * wireframe/warnings/tokens lines stay identical across surfaces).
+ * Callers pass the EFFECTIVE page (the renderer's clamped pick, not the raw
+ * request) so the `[PAGE n OF m]` marker always describes the image shown,
+ * and the renderer's actual page count as `renderTotalPages` so `OF m` is
+ * the renderer's count — the image came from the renderer, the marker must
+ * name it. Divergence from the word-layout page map and any --page beyond
+ * that map warn on stderr (never silent; stdout stays JSON-clean).
+ */
+export declare function printCliVisualTelemetry(out: GlobalOpts, ast: DocumentAST, summary: unknown, page: number, renderTotalPages?: number): VisualTelemetry;
+export declare function cmdVisual(out: GlobalOpts, args: string[]): Promise<number>;