@attentionform/astra 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,206 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Attentionform, the publisher of ASTra, operated by the
+                      holder of the GitHub account github.com/Userfrom1995
+                      and also identified by the GitHub organization
+                      github.com/Attentionform and the domain
+                      attentionform.com, together with its successors and
+                      assigns.
+
+Licensed Work:        ASTra: the engine, command-line tool, MCP server and
+                      OOXML validator in this repository, in each version
+                      that the Licensor makes publicly available, beginning
+                      with the first public release. Each version carries
+                      its own Change Date, below.
+                      The Licensed Work is (c) 2026 Attentionform.
+                      This License applies to all files in this repository and
+                      to the packages published from it, UNLESS another license
+                      file is present in a sub-directory, in which case that
+                      license applies to the files in that sub-directory.
+
+Additional Use Grant: You may make production use of the Licensed Work, free of
+                      charge, if Your use is Individual Use, Educational and
+                      Research Use, Non-Profit Use, Public-Sector Use or Small
+                      Business Use, each as defined below. Any other production
+                      use requires a commercial license from the Licensor.
+
+                      "Individual Use" means use by a natural person on his or
+                      her own account, including as a freelancer or consultant,
+                      either personally or through a business entity that has
+                      no employees. Contractors engaged for a specific project
+                      are not employees. Individual Use does not include use
+                      for the internal operations of an employer or of a client
+                      (for example, running the Licensed Work on a client's
+                      systems for the client's own continuing use). Using the
+                      Licensed Work to prepare documents or other deliverables
+                      for clients is Individual Use.
+
+                      "Educational and Research Use" means use by an accredited
+                      school, college or university, or by its students and
+                      staff, for teaching, learning or non-commercial academic
+                      research.
+
+                      "Non-Profit Use" means use by a Qualifying Non-Profit in
+                      furtherance of its exempt purposes, and not in connection
+                      with the sale of products or services (other than fees
+                      that only recover the cost of its charitable activities).
+                      A "Qualifying Non-Profit" is an organization that is
+                      organized and operated exclusively for charitable,
+                      educational, religious, scientific or similar
+                      public-benefit purposes, whose net earnings do not
+                      benefit any private person, and that is recognized as a
+                      charity or as exempt from income tax on that basis under
+                      the law of its jurisdiction (for example, under Section
+                      501(c)(3) of the U.S. Internal Revenue Code, or as a
+                      charity registered in the United Kingdom).
+
+                      "Public-Sector Use" means use by a government department,
+                      agency, municipality or other public authority for its
+                      governmental functions. It does not include use by a
+                      state-owned or government-controlled enterprise, or by
+                      any body that sells products or services on a commercial
+                      basis. Fees charged only to recover the cost of statutory
+                      services are not a commercial basis.
+
+                      Any organization that is not described in Individual Use,
+                      Educational and Research Use, Non-Profit Use or
+                      Public-Sector Use, including a company, partnership or
+                      other business with employees and any state-owned or
+                      government-controlled enterprise, is a "For-Profit
+                      Organization". Production use by or for a For-Profit
+                      Organization requires a commercial license unless it is
+                      Small Business Use.
+
+                      "Small Business Use" means use by a For-Profit
+                      Organization that, together with its affiliates, had
+                      total gross revenue below USD 1,000,000 and fewer than 10
+                      people working for it in its last completed fiscal year,
+                      or that has not yet completed a fiscal year and
+                      reasonably expects to meet both limits in its first one.
+                      The people working for it are its employees and the
+                      individuals who work for it on a regular basis as
+                      contractors, counted as individuals and not as
+                      companies. An "affiliate" is any entity that controls,
+                      is controlled by, or is under common control with
+                      another entity.
+
+                      Individual Use and Small Business Use include using the
+                      Licensed Work as a component of a product or service of
+                      Your own that has substantial functionality beyond that
+                      of the Licensed Work, and Your customers and users may
+                      use the Licensed Work only as part of that product or
+                      service. A product or service includes software that You
+                      make available free of charge. No category above
+                      includes a Competing Offering, which always requires a
+                      commercial license. A "Competing Offering" is a product
+                      or service offered to third parties whose value consists
+                      mainly of the functionality of the Licensed Work, for
+                      example hosting the Licensed Work as a service for others
+                      or reselling it.
+
+                      If You stop qualifying for a category above, You may
+                      continue Your existing use for 90 days (for Small
+                      Business Use, until the end of Your next fiscal year),
+                      and must then obtain a commercial license or stop.
+                      "Production use" means any use of the Licensed Work
+                      other than non-production use, including making it part
+                      of a product or service that You provide to others.
+                      Non-production use (including evaluation, development,
+                      testing and demonstration) is permitted by this License
+                      without any category. Documents and other output that You
+                      create with the Licensed Work belong to You, and this
+                      License places no restriction on them.
+
+Change Date:          Four years after the date on which a specific version of
+                      the Licensed Work is first made publicly available.
+
+Change License:       Apache License, Version 2.0
+
+For information about commercial licenses for the Licensed Work, contact:
+astra@attentionform.com
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/NOTICE

@@ -0,0 +1,12 @@
+ASTra
+Copyright 2026 Attentionform (https://attentionform.com)
+
+This product includes software developed by Attentionform and its contributors.
+
+ASTra is licensed under the Business Source License 1.1 (source-available, not open source).
+See the LICENSE file for the terms, including who may use it for free. Each version
+converts to the Apache License, Version 2.0 four years after it is first made
+publicly available. For a commercial license, write to astra@attentionform.com.
+
+Third-party software included in or used by ASTra, with its own licenses and
+copyright notices, is listed in THIRD_PARTY_NOTICES.md.

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+# @attentionform/astra
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official command-line interface for the ASTra document engine (`astra`).
+
+`@attentionform/astra` provides high-performance terminal inspection, ECMA-376 schema validation, atomic batch editing, privacy sanitization, and multi-format export for Microsoft Word (`.docx`) files. The interactive chat IDE moved to the separate `astra-agent` binary.
+
+---
+
+## Quickstart
+
+### Run with `npx` (Zero Install)
+
+Run commands immediately without installing locally:
+
+```bash
+npx -y @attentionform/astra --help
+```
+
+### Install Globally
+
+```bash
+npm install -g @attentionform/astra
+astra --help
+```
+
+### 3-Minute Tour
+
+```bash
+# 1. Create a document from an executive template
+astra create proposal.docx --template report
+
+# 2. Inspect document structure in token-compact notation
+astra inspect proposal.docx --fidelity compact
+
+# 3. Search for headings or paragraphs to find stable node IDs
+astra search proposal.docx "Executive"
+
+# 4. Append a new paragraph atomically
+astra batch proposal.docx --append "Project timeline spans 6 months."
+
+# 5. Export to PDF and Markdown
+astra export proposal.docx --format pdf -o proposal.pdf
+astra export proposal.docx --format markdown -o proposal.md
+
+# 6. Sanitize metadata before external sharing
+astra sanitize proposal.docx proposal_clean.docx
+```
+
+---
+
+## Command Overview
+
+| Command | Description | Example |
+|---|---|---|
+| `inspect` | Displays TOON outline, table grids, and node IDs | `astra inspect doc.docx --fidelity compact` |
+| `validate` | Checks ECMA-376 schema conformance and package integrity | `astra validate doc.docx` |
+| `batch` | Applies atomic operations or JSON streams with rollback | `astra batch doc.docx ops.json` |
+| `search` | Searches text across nodes with literal or regex matching | `astra search doc.docx "Revenue" --limit 5` |
+| `create` | Generates a fresh `.docx` from `report`, `memo`, or `blank` | `astra create new.docx --template memo` |
+| `import` | Compiles Markdown files directly into `.docx` | `astra import spec.md -o spec.docx` |
+| `export` | Headless export to PDF, HTML, or Markdown | `astra export doc.docx --format pdf` |
+| `sanitize` | Scrubs metadata, comments, revision history, and PII | `astra sanitize doc.docx clean.docx` |
+| `normalize` | Canonicalizes XML namespaces and fixes element ordering | `astra normalize doc.docx` |
+| `stats` | Reports word count, paragraph count, and estimated pages | `astra stats doc.docx` |
+| `visual` | Renders one saved-file page to PNG/JPEG via headless LibreOffice | `astra visual doc.docx --out render.png` |
+| `history` | Lists recorded sidecar commits, newest first (read-only) | `astra history doc.docx` |
+| `revert` | Restores the package state recorded N commits back, as a new commit | `astra revert doc.docx --steps 1` |
+| `redo` | Re-applies the state replaced by the most recent revert | `astra redo doc.docx` |
+
+---
+
+## Command Reference
+
+Each command lists its job in one line; run `astra <command> --help` for the full flag table and `--json` for scripting.
+
+### 1. Inspect Document (`astra inspect`)
+Structure, node IDs, and document stats; `--visual` adds spatial telemetry plus one headless page render.
+
+### 2. Validate Document (`astra validate`)
+ECMA-376 schema conformance and package integrity; never writes.
+
+### 3. Sanitize Document (`astra sanitize`)
+Scrubs metadata, comments, revision history, and RSIDs; `--redact-pii` also redacts body PII.
+
+### 4. Atomic Batch Operations (`astra batch`)
+Applies an ops file with rollback; supports `--stream`, `--matrix`, and shortcut flags.
+
+### 5. Repair Legacy Files (`astra normalize`)
+Canonicalizes XML namespaces and fixes element ordering.
+
+### 6. Multi-Format Export (`astra export`)
+Exports to PDF, HTML, or Markdown.
+
+### 7. Full-Text Search (`astra search`)
+Finds node IDs by literal or regex text match.
+
+### 8. Create Document (`astra create`)
+Generates a fresh `.docx` from a bundled template.
+
+### 9. Import Markdown (`astra import`)
+Compiles a Markdown file into a `.docx`.
+
+### 10. Document Statistics (`astra stats`)
+Word, paragraph, and page counts (deterministic estimate).
+
+### 11. Visual Page Rendering (`astra visual`)
+Renders one saved-file page to PNG/JPEG via headless LibreOffice (same renderer as `inspect --visual`).
+
+### 12. Document History (`astra history`)
+Lists recorded sidecar commits newest first; read-only; `--init` (alias `--track`) records the current file as the baseline when no sidecar exists yet.
+
+### 13. Revert to Recorded State (`astra revert`)
+Restores the tracked package state `--steps <n>` commits back and records the restore as a new commit (append-only); `preview-revert` previews the same change read-only.
+
+### 14. Redo Reverted State (`astra redo`)
+Re-applies the state replaced by the most recent revert (one redo per revert head).
+
+---
+
+## Global Flags
+
+These flags work across all subcommands:
+
+| Flag | Purpose |
+|---|---|
+| `--json` | Emits single-line structured JSON on `stdout` for CI/CD scripting and `jq` pipelines. |
+| `--verbose` | Emits detailed operational diagnostics on `stderr`. |
+| `--version` | Displays current CLI version and exits with `0`. |
+| `--help`, `-h` | Displays help information for any command (`astra <command> --help`). |
+
+---
+
+## Practical CLI Recipes
+
+### 1. Atomic Node Replacement (Without an Ops File)
+Quickly replace targeted text without needing to write JSON operations:
+
+```bash
+# Finds the paragraph containing "Draft Status" and updates it
+astra batch doc.docx --target-text "Draft Status" --append "Final Approved"
+```
+
+### 2. High-Throughput Batch Automation
+Pipe JSON operations directly via `stdin`:
+
+```bash
+cat operations.json | astra batch doc.docx - --out modified.docx
+```
+
+### 3. CI/CD Schema Verification
+Integrate ASTra into automated build pipelines:
+
+```bash
+# Returns exit code 0 if valid, 1 if schema violations are found
+astra validate generated_report.docx --json | jq .ok
+```
+
+### 4. Privacy Sanitization for Public Distribution
+Scrub author names, editing history, and metadata:
+
+```bash
+# Default: scrubs metadata, revision tags, and hidden RSIDs while keeping body text
+astra sanitize draft.docx public.docx
+
+# Client-Safe: scrubs metadata, redacts body PII, and accepts all tracked changes
+astra sanitize draft.docx client_final.docx --client-safe
+```
+
+### 5. Multi-Page Visual Telemetry
+Inspect layout and generate high-resolution PNG previews:
+
+```bash
+astra inspect doc.docx --visual --format png
+```
+
+---
+
+## Dates, authors and reproducible output
+
+By default ASTra writes the **current time** into tracked changes, comments and document properties, and attributes them to the author you give: an `author` on the operation, else `--author <name>` (or `ASTRA_AUTHOR`) for the run, else `ASTra`. Any revision or comment operation also takes an explicit ISO 8601 `date`.
+
+For **byte-identical output** (same input twice gives the same bytes), pass `--reproducible`, or set `ASTRA_REPRODUCIBLE=1` or `SOURCE_DATE_EPOCH`. Timestamps, ids and document properties are then pinned to `SOURCE_DATE_EPOCH`, else `1980-01-01Z`. `--no-reproducible` (or `ASTRA_NO_REPRODUCIBLE=1`) forces real values even when one of those is set.
+
+---
+
+## Exit Code Contract
+
+ASTra enforces a strict, predictable exit code contract for headless automation:
+
+| Exit Code | Meaning | Common Causes |
+|:---:|---|---|
+| `0` | **Success** | Operation completed successfully, document validated. |
+| `1` | **Operational Failure** | File not found, corrupted XML archive, schema validation failed, or batch rolled back. |
+| `2` | **Usage Error** | Unknown flag, missing required positional arguments, or file overwrite conflict without `--force`. |
+
+---
+
+## Local Development
+
+```bash
+# Build CLI bundle
+npm run build:packages
+
+# Run local CLI binary
+node packages/cli/dist/cli.js --help
+```
+
+---
+
+## License
+
+Business Source License 1.1 (`BUSL-1.1`): source-available, free for individuals, education, non-profits, public bodies and small businesses; other production use needs a commercial license. Each version converts to Apache-2.0 four years after release. See [LICENSE](LICENSE) and write to astra@attentionform.com for a commercial license.