@attentionform/astra 0.1.0 → 0.2.1

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

@@ -43,6 +43,10 @@ export interface RunBatchJobCtx {
     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;
@@ -112,6 +116,8 @@ export interface StreamCmdArgs {
     outPath: string | undefined;
     sequential: boolean | undefined;
     skipValidate: boolean;
+    strict: boolean;
+    noHistory: boolean;
     flagCeilings: ZipCeilingOverrides;
     dryRun: boolean;
     backupGiven: boolean;
@@ -139,6 +145,8 @@ export interface StreamSessionOpts {
     target: string;
     sequential: boolean | undefined;
     skipValidate: boolean;
+    strict?: boolean;
+    noHistory?: boolean;
     flagCeilings: ZipCeilingOverrides;
     backupState: BackupState;
     backupSource: Buffer;

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

@@ -1,4 +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/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/io.d.ts

@@ -26,6 +26,16 @@ export declare function macroOptsFromFlags(f: MacroFlagChoice): {
     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

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

@@ -33,7 +33,10 @@ export declare function previewNormalizedForDisplay(buf: Buffer, macroOpts?: {
     stripMacros?: boolean;
 }): NormalizedRewrite[];
 /** Display-only repair entry: core parse + rezip (the hook heals), or passthrough on failure. */
-export declare function applyNormalizerForDisplay(buf: Buffer): {
+export declare function applyNormalizerForDisplay(buf: Buffer, macroOpts?: {
+    allowMacros?: boolean;
+    stripMacros?: boolean;
+}): {
     buffer: Buffer;
     normalized: NormalizedRewrite[];
 };

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

@@ -4,13 +4,13 @@
  *
  * 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]
+ *   validate <docx> [--max-errors <n>] [--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] [--force]
  *     (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>]
+ *   batch    <docx> [<ops.json|->] [--target-text <needle> --append <text>] [--append <text>] [--out <docx>] [--sequential|--no-sequential] [--no-validate] [--strict] [--no-history] [--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)
+ *   normalize <docx> [--out <docx>] [--dry-run] [--strict] [--no-history] [--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>]

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

@@ -14,5 +14,11 @@ export interface ExportOptions {
     imageMode?: 'embed' | 'file';
     /** Markdown file mode: relative folder for image files (default media). */
     assetPrefix?: string;
+    /** Macro choice for the HTML and Markdown paths (the PDF path never opens the package for editing). */
+    macroOpts?: {
+        allowMacros: true;
+    } | {
+        stripMacros: true;
+    };
 }
 export declare function executeExport(docxPath: string, formatInput?: string, outPath?: string, options?: ExportOptions): Promise<ExportResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attentionform/astra",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Command-line tool for OOXML (.docx) document engineering",
   "main": "dist/cli.js",
   "types": "dist/packages/cli/src/cli.d.ts",
@@ -43,8 +43,8 @@
     "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
   },
   "dependencies": {
-    "@attentionform/astra-engine": "^0.1.0",
-    "@attentionform/ooxml-validator": "^0.1.0",
+    "@attentionform/astra-engine": "^0.2.1",
+    "@attentionform/ooxml-validator": "^0.2.1",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",
     "isomorphic-git": "^1.25.0",