@attentionform/astra 0.0.0-stage → 0.2.0

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-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] [--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] [--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>]
+ *   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,24 @@
+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;
+    /** 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/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>;

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

@@ -0,0 +1,30 @@
+import type { OfficeVersion, ValidationError } from './types.js';
+export interface WorkerRequestHeader {
+    id: number;
+    op?: 'validate' | 'ping' | 'version' | 'shutdown' | string;
+    kind?: 'docx' | 'pptx' | 'xlsx' | string;
+    office?: OfficeVersion | string;
+    size?: number;
+    maxErrors?: number;
+    maxDocBytes?: number;
+}
+export interface WorkerResponse {
+    id: number | null;
+    ok: boolean;
+    pong?: boolean;
+    sdkVersion?: string;
+    office?: string;
+    durationMs?: number;
+    errorCount?: number;
+    truncated?: boolean;
+    fatal?: boolean;
+    error?: string;
+    errors?: ValidationError[];
+}
+export declare function encodeRequest(header: WorkerRequestHeader, bytes?: Uint8Array | Buffer): Buffer;
+export declare class JsonLineDecoder {
+    private decoder;
+    private buffer;
+    push(chunk: Buffer | Uint8Array): WorkerResponse[];
+    end(): WorkerResponse[];
+}

package/dist/packages/ooxml-validator/src/resolve-binary.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveBinaryDetails(): {
+    binaryPath: string;
+    platformPackage: string;
+};
+export declare function resolveEmbeddedBinary(): string;

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

@@ -0,0 +1,65 @@
+export declare const OFFICE_VERSIONS: readonly ["Office2007", "Office2010", "Office2013", "Office2016", "Office2019", "Office2021", "Microsoft365"];
+export type OfficeVersion = (typeof OFFICE_VERSIONS)[number];
+export interface ErrorNode {
+    localName?: string | null;
+    namespaceUri?: string | null;
+}
+export type ValidationErrorClass = 'schema' | 'semantic' | 'markup-compat' | 'package' | 'exception' | string;
+export interface ValidationError {
+    /** Human-readable description of the problem. */
+    description?: string | null;
+    /** Package part the error was found in, e.g. `/word/document.xml`. `null` for `errorType: 'Exception'`. */
+    path?: string | null;
+    /** XPath of the offending element. `null` for `errorType: 'Exception'`. */
+    xPath?: string | null;
+    /** Open XML SDK error id, e.g. `Sch_UnexpectedElementContentExpectingComplex`. `null` for `errorType: 'Exception'`. */
+    id?: string | null;
+    /** `Schema`, `Semantic`, `Package`, `MarkupCompatibility`, or `Exception` when the file could not be opened at all. */
+    errorType?: string | null;
+    /** Part URI string (e.g. `/word/document.xml`). */
+    part?: string | null;
+    /** Error classification: 'schema' | 'semantic' | 'markup-compat' | 'package' | 'exception'. */
+    class?: ValidationErrorClass | null;
+    /** Offending XML element information when present. */
+    node?: ErrorNode | null;
+    /** Related XML element information when present. */
+    relatedNode?: ErrorNode | null;
+    [key: string]: unknown;
+}
+export interface ValidationResult {
+    file: string;
+    ok: boolean;
+    errors: ValidationError[];
+    sdkVersion?: string;
+    office?: string;
+    durationMs?: number;
+    truncated?: boolean;
+    errorCount?: number;
+    [key: string]: unknown;
+}
+export interface ValidateOptions {
+    /** Open XML schema version to validate against. Defaults to `Microsoft365` for one-shot, `Office2019` for buffer. */
+    officeVersion?: OfficeVersion;
+    maxErrors?: number;
+    timeoutMs?: number;
+    maxDocBytes?: number;
+}
+export interface ValidatorPoolOptions {
+    workers?: number;
+    recycleAfter?: number;
+    timeoutMs?: number;
+    maxDocBytes?: number;
+    maxErrors?: number;
+}
+export interface BackendInfo {
+    platformPackage: string;
+    binaryPath: string;
+    sdkVersion: string;
+    binarySha256: string;
+    workerSupported: boolean;
+}
+export interface ValidatorInstance {
+    validate(bytes: Buffer | Uint8Array, opts?: ValidateOptions): Promise<ValidationResult>;
+    validateFile(path: string, opts?: ValidateOptions): Promise<ValidationResult>;
+    close(): Promise<void>;
+}

package/dist/packages/ooxml-validator/src/worker-client.d.ts

@@ -0,0 +1,38 @@
+import { type WorkerRequestHeader, type WorkerResponse } from './protocol.js';
+import type { ValidatorPoolOptions } from './types.js';
+export declare class WorkerClient {
+    private binaryPath;
+    private recycleAfter;
+    private timeoutMs;
+    private maxDocBytes;
+    private maxErrors;
+    private child;
+    private liveChildren;
+    private queue;
+    private current;
+    private nextId;
+    private requestsHandled;
+    private closed;
+    private _spawnCount;
+    private _spawnedPids;
+    constructor(opts?: ValidatorPoolOptions & {
+        binaryPath?: string;
+    });
+    get pid(): number | undefined;
+    get spawnCount(): number;
+    get spawnedPids(): number[];
+    private ensureWorker;
+    private refChild;
+    private unrefChild;
+    send(header: Omit<WorkerRequestHeader, 'id'>, bytes?: Uint8Array | Buffer, overrideTimeoutMs?: number): Promise<WorkerResponse>;
+    private processQueue;
+    private handleResponse;
+    private handleTimeout;
+    private handleWriteError;
+    private handleProcessError;
+    private handleProcessExit;
+    private retryOrReject;
+    private recycleWorker;
+    private killWorker;
+    close(): Promise<void>;
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@attentionform/astra",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Command-line tool for OOXML (.docx) document engineering",
+  "main": "dist/cli.js",
+  "types": "dist/packages/cli/src/cli.d.ts",
+  "bin": {
+    "astra": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "!dist/packages/engine",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "BUSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Attentionform/astra.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "cli",
+    "astra",
+    "ooxml",
+    "docx",
+    "word",
+    "terminal",
+    "document",
+    "automation"
+  ],
+  "type": "commonjs",
+  "scripts": {
+    "build": "node ../../scripts/check-adm-zip-imports.mjs && tsc --noEmit -p tsconfig.json && esbuild src/cli.ts --bundle --packages=external --platform=node --target=node22 --format=cjs --outfile=dist/cli.js --log-level=warning && tsc -p tsconfig.dts.json && node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "start": "node dist/cli.js",
+    "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
+  },
+  "dependencies": {
+    "@attentionform/astra-engine": "^0.2.0",
+    "@attentionform/ooxml-validator": "^0.2.0",
+    "@xmldom/xmldom": "0.8.15",
+    "adm-zip": "0.6.1",
+    "isomorphic-git": "^1.25.0",
+    "marked": "18.0.5",
+    "p-limit": "^3.1.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.2.2",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "homepage": "https://attentionform.com",
+  "bugs": {
+    "url": "https://github.com/Attentionform/astra/issues"
+  },
+  "author": {
+    "name": "Attentionform",
+    "url": "https://attentionform.com"
+  }
+}