docx-to-builder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Morrison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# docx-to-builder
+
+> Parse any `.docx` template and generate a ready-to-run JavaScript builder that reproduces it exactly.
+
+You have a branded Word template. You want to generate documents from it programmatically — with AI-written content, dynamic data, or automation pipelines. But Pandoc can't faithfully reproduce your layout, and docxtemplater requires manually adding `{placeholders}` to every field.
+
+**docx-to-builder** takes a different approach: it reads your `.docx` template's raw XML, understands every formatting decision, and writes a JavaScript file that recreates that exact layout using the [`docx`](https://docx.js.org) npm package.
+
+---
+
+## How it works
+
+```
+your-template.docx  →  [docx-to-builder]  →  your-template-builder.js
+                                                      ↓
+                                             node your-template-builder.js
+                                                      ↓
+                                             branded-output.docx  ✓
+```
+
+1. **Parse** — reads the `.docx` XML directly (no third-party Python libraries needed)
+2. **Extract** — captures colors, fonts, spacing, borders, tables, images, headers, footers
+3. **Infer** — detects `[bracketed placeholders]` and maps them to `data.fieldName` references
+4. **Generate** — writes a complete ES module with `buildDocument(data, outputPath)`
+
+---
+
+## Quick start
+
+**Requirements:** Python 3.8+ · Node.js · [`docx`](https://www.npmjs.com/package/docx) npm package
+
+```bash
+# 1. Generate a builder from your template
+python3 docx-to-builder.py my-template.docx
+
+# 2. Install docx in your project (if you haven't already)
+npm install docx
+
+# 3. Run the builder
+node my-template-builder.js
+
+# Output: my-template-output.docx
+```
+
+Or install via npm and run with npx:
+
+```bash
+npx docx-to-builder my-template.docx
+```
+
+---
+
+## Template conventions
+
+Your template can use any Word formatting. To make fields dynamic, use bracketed placeholders:
+
+| In your template | Generated JS |
+|---|---|
+| `[Client Name]` | `data.clientName` |
+| `[Proposal Title]` | `data.title` |
+| `[Month Day, Year]` | `data.date` |
+| `[Draft / Final]` | `data.status` |
+| `[Your custom field]` | `data.yourCustomField` |
+
+Any text **not** in brackets is treated as a static label and kept as-is.
+
+---
+
+## What gets extracted
+
+| Template element | Extracted |
+|---|---|
+| Body paragraphs | Text, font, size, color, bold, italic, all-caps, spacing, alignment |
+| Section headings | With red rule lines, borders, spacing |
+| Bullet lists | Level, indent, font |
+| Tables | Cell widths, shading, borders, margins, content |
+| Inline images | Size (EMU → pt), relationship to file, auto-copied to `assets/` |
+| Headers & footers | Text, tab stops, border rules, page number fields |
+| Page margins | Per-section |
+| Brand colors | Auto-named constants (`COLOR.accent`, `COLOR.body`, etc.) |
+
+---
+
+## Generated file structure
+
+```js
+// Brand colors extracted from template
+const COLOR = { accent: '2C4A6E', body: '444444', ... };
+const FONT = 'Calibri';
+const LOGO_PATH = join(__dirname, 'assets/logo.png');
+
+// Header and footer — exact replica of template
+function buildHeader(data) { ... }
+function buildFooter() { ... }
+
+// Document body — all layout hardcoded, bracketed fields wired to data object
+function buildContent(data) { ... }
+
+// Main entry point — call this from your code or pipeline
+export async function buildDocument(data, outputPath) { ... }
+
+// Data object — auto-populated from inferred placeholders
+const data = {
+  title: 'Proposal Title',
+  clientName: 'Client Name',
+  date: '...',
+};
+```
+
+---
+
+## Wiring in your own content
+
+After generation, the `data` object at the bottom of the file maps directly to the bracketed fields the generator found. Replace the example values with your real data — or import `buildDocument` and pass a data object from your own code:
+
+```js
+import { buildDocument } from './my-template-builder.js';
+
+await buildDocument({
+  title: 'Cloud Migration Proposal',
+  clientName: 'Acme Corp',
+  date: 'April 1, 2026',
+  status: 'Final',
+}, 'output/acme-proposal.docx');
+```
+
+---
+
+## Example
+
+The `examples/` folder contains:
+
+- `sample-template.docx` — a generic proposal template (Meridian Consulting)
+- `sample-builder.js` — the builder generated from that template
+
+Run the example:
+
+```bash
+cd examples
+npm install docx
+node sample-builder.js
+# → output/sample-output.docx
+```
+
+---
+
+## Limitations
+
+- **Inline images** — fully extracted. The image file is automatically copied to `assets/` next to the generated builder — no manual step needed
+- **Complex graphics** — SmartArt, shapes, charts, and WordArt use a different XML format and are skipped; the surrounding paragraph text is preserved
+- **Multi-section documents** — section breaks are noted as comments; the generated builder uses a single section (the last one's margins). Multi-section support is on the roadmap
+- **Dynamic content** — the generator wires up bracketed placeholders automatically, but long static template paragraphs become literal strings. Replace them with `data.fieldName` references for full dynamic control
+- **Table of contents** — TOC fields are not regenerated
+
+---
+
+## CLI options
+
+```bash
+python3 docx-to-builder.py <template.docx> [--output <builder.js>]
+
+# Examples:
+python3 docx-to-builder.py proposal.docx
+python3 docx-to-builder.py proposal.docx --output src/builders/proposal-builder.js
+```
+
+---
+
+## Contributing
+
+Issues and PRs welcome. If your template produces unexpected output, open an issue and attach the template (or a sanitized version of it).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * docx-to-builder CLI wrapper
+ * Calls the Python script with all arguments passed through.
+ */
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const script = join(__dirname, 'docx-to-builder.py');
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.log('Usage: npx docx-to-builder <template.docx> [--output <builder.js>]');
+  console.log('');
+  console.log('Examples:');
+  console.log('  npx docx-to-builder my-template.docx');
+  console.log('  npx docx-to-builder my-template.docx --output src/my-builder.js');
+  process.exit(0);
+}
+
+const python = process.platform === 'win32' ? 'python' : 'python3';
+const child = spawn(python, [script, ...args], { stdio: 'inherit' });
+
+child.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error(`Error: Python not found. Please install Python 3.8+ and ensure it is in your PATH.`);
+    console.error(`  Download: https://www.python.org/downloads/`);
+  } else {
+    console.error('Error:', err.message);
+  }
+  process.exit(1);
+});
+
+child.on('close', (code) => {
+  process.exit(code ?? 0);
+});