@attentionform/astra 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,169 @@
+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;
+    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;
+    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;
+    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,4 @@
+import { type GlobalOpts } from './output';
+export declare const CREATE_TEMPLATES: readonly ["report", "memo", "blank"];
+export type CreateTemplate = (typeof CREATE_TEMPLATES)[number];
+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/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,60 @@
+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;
+/**
+ * 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,95 @@
+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): {
+    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>;

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * @attentionform/astra — Track-B command line (`astra` bin).
+ *
+ * Commands (all fail-closed — any operational failure exits non-zero):
+ *   inspect  <docx> [--fidelity compact|standard|full] [--section <id>] [--max-text <n>] [--width <n>] [--wrap] [--visual] [--format png|jpeg] [--max-ratio <n>] [--max-uncompressed-bytes <n>]
+ *   validate <docx> [--max-ratio <n>] [--max-uncompressed-bytes <n>] [--style-guide <name|path>]
+ *   sanitize <in.docx> <out.docx> [--client-safe] [--redact-pii] [--zero-retention] [--replacement-author <name>] [--accept-all-revisions] [--strip-comments] [--metadata-only]
+ *     (bare sanitize = metadata preset: zero-retention + accept-all-revisions + strip-comments + neutral author, body text kept; --redact-pii/--client-safe also redact body PII)
+ *   batch    <docx> [<ops.json|->] [--target-text <needle> --append <text>] [--append <text>] [--out <docx>] [--sequential|--no-sequential] [--no-validate] [--schema] [--max-ratio <n>] [--max-uncompressed-bytes <n>] [--dry-run] [--backup[=<path>]] [--matrix <vars.csv>] [--reproducible|--no-reproducible] [--stream [--on-error abort|continue] [--max-errors <n>]] [--style-guide <name|path>]
+ *     (ops path `-` reads ops JSON from stdin; see `batch --help`)
+ *     (ops support CLI-level `insert type:heading level:1..3` and `{action:'clearDoc'}`; see `batch --schema`)
+ *   normalize <docx> [--out <docx>] [--dry-run] [--backup[=<path>]] (repair-as-action for legacy files; `validate` stays read-only, no --fix alias)
+ *   export   <docx> [--format html|markdown|md|pdf] [-o <outPath>]
+ *   search   <docx> <query> [--limit <n>]
+ *   create   <out.docx> [--template report|memo|blank] [--force] [--from-md <file.md>] [--allowed-dir <dir>] [--dollar-math] [--style-guide <name|path>]
+ *   import   <file.md> [-o <out.docx>] [--template report|memo|blank] [--force] [--allowed-dir <dir>] [--dollar-math]
+ *   stats    <docx>
+ *
+ * Exit codes: 0 ok · 1 operational failure (invalid docx, bad ops, batch
+ * failure/rollback, failed validation — never writes corruption) · 2 usage.
+ *
+ * Engine wiring:
+ *   imports resolve to the `@attentionform/astra-engine` package.
+ *   CLI command names, flags and exit-code contract stay identical
+ *   across refactors (scripts pin them).
+ */
+export * from './cli/output';
+export * from './cli/errors';
+export * from './cli/usage';
+export * from './cli/io';
+export * from './cli/inspect-cmd';
+export * from './cli/validate-cmd';
+export * from './cli/sanitize-cmd';
+export * from './cli/batch-cmd';
+export * from './cli/normalize-cmd';
+export * from './cli/export-cmd';
+export * from './cli/search-cmd';
+export * from './cli/create-cmd';
+export * from './cli/import-cmd';
+export * from './cli/stats-cmd';
+export * from './cli/visual-cmd';
+export * from './cli/history-cmd';
+export * from './cli/run';

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

@@ -0,0 +1,18 @@
+export interface ExportResult {
+    ok: boolean;
+    path: string;
+    format: 'html' | 'markdown' | 'pdf';
+    bytes: number;
+    assets?: string[];
+}
+export interface ExportOptions {
+    /** Render untagged PDF (default false = tagged render). */
+    untagged?: boolean;
+    /** Fail closed on preflight blockers (default false = warn-only). */
+    strict?: boolean;
+    /** Markdown only: embed data URLs (default) or write folder references. */
+    imageMode?: 'embed' | 'file';
+    /** Markdown file mode: relative folder for image files (default media). */
+    assetPrefix?: string;
+}
+export declare function executeExport(docxPath: string, formatInput?: string, outPath?: string, options?: ExportOptions): Promise<ExportResult>;

package/dist/packages/ooxml-validator/src/index.d.ts

@@ -0,0 +1,33 @@
+export { resolveEmbeddedBinary, resolveBinaryDetails } from './resolve-binary.js';
+import { OFFICE_VERSIONS, type OfficeVersion, type ValidateOptions, type ValidationError, type ValidationResult, type ValidatorPoolOptions, type BackendInfo, type ValidatorInstance, type ErrorNode, type ValidationErrorClass } from './types.js';
+export { OFFICE_VERSIONS };
+export type { OfficeVersion, ValidateOptions, ValidationError, ValidationResult, ValidatorPoolOptions, BackendInfo, ValidatorInstance, ErrorNode, ValidationErrorClass, };
+/**
+ * Validates a single OOXML file from disk.
+ * Defaults to 'Microsoft365' to match standard ECMA-376 / ISO-29500 behavior.
+ */
+export declare function validateFile(filePath: string, options?: ValidateOptions): Promise<ValidationResult>;
+/**
+ * Convenience helper returning a boolean indicating if the document is valid.
+ */
+export declare function isValid(filePath: string, options?: ValidateOptions): Promise<boolean>;
+/**
+ * Validates an in-memory DOCX buffer without creating temporary files.
+ * Defaults to 'Office2019' matching the ASTra engine's standard validation target.
+ */
+export declare function validateBuffer(bytes: Buffer | Uint8Array, options?: ValidateOptions): Promise<ValidationResult>;
+/**
+ * Creates an isolated validator worker client instance.
+ */
+export declare function createValidator(opts?: ValidatorPoolOptions): ValidatorInstance;
+/**
+ * Returns diagnostic metadata about the resolved binary and platform package.
+ */
+export declare function backendInfo(): Promise<BackendInfo>;
+/**
+ * Runs a self-diagnostic validating an embedded known-good and known-bad document.
+ */
+export declare function selfTest(): Promise<{
+    ok: boolean;
+    details: string;
+}>;

package/dist/packages/ooxml-validator/src/one-shot.d.ts

@@ -0,0 +1,2 @@
+import { type ValidateOptions, type ValidationResult } from './types.js';
+export declare function runValidatorOneShot(file: string, options?: ValidateOptions): Promise<ValidationResult>;