build_sop.py

skills/sop-author/scripts/build_sop.py

1. #!/usr/bin/env python3
2. """
3. Meridian SOP Builder
5. Takes a Python dict describing an SOP and produces a styled .docx file matching
6. the Meridian Display Co. company SOP template.
8. Usage:
9. from build_sop import build_sop
10. build_sop({
11. "title": "Mockup File Naming Convention",
12. "owner": "Matt Guerra",
13. "initials": "MG",
14. "category": "Operations",
15. "effective_date": "04/2026",
16. "folder_context": "07 - Mockup Artwork Files",
17. "sections": [
18. {"type": "purpose", "text": "..."},
19. {"type": "scope", "text": "..."},
20. {"type": "h1", "text": "Folder Structure"},
21. {"type": "body", "text": "..."},
22. {"type": "code", "text": "07 - Mockup Artwork Files\n├── ..."},
23. {"type": "accent_subhead", "text": "Versioning"},
24. {"type": "bullet", "text": "Start at v1 for every new job."},
25. {"type": "components_table", "rows": [["Component", "Value", "Description"], ["v[#]", "v1, v2...", "Version number"]]},
26. {"type": "examples_table", "rows": [["Folder", "Sub DIR", "File Name(s)"], ["NORTHWIND ACADEMY", "H4A", "Mockup_v1_04/2026_RG"]]},
27. {"type": "note", "text": "Note: This applies to ... only."},
28. {"type": "quick_ref", "text": "Mockup Format:\nMockup_v[#]_..."},
29. ],
30. "output_path": "/path/to/output.docx",
31. })
33. Run as a CLI:
34. python3 build_sop.py --validate /path/to/file.docx
35. """
37. import argparse
38. import os
39. import re
40. import shutil
41. import sys
42. from pathlib import Path
44. from docx import Document
45. from docx.shared import Pt, Inches, RGBColor, Emu
46. from docx.enum.text import WD_ALIGN_PARAGRAPH
47. from docx.oxml.ns import qn
48. from docx.oxml import OxmlElement
51. MERIDIAN_NAVY = RGBColor(0x1F, 0x3A, 0x5F)
52. WARN_RED = RGBColor(0xFF, 0x00, 0x00)
53. BODY_BLACK = RGBColor(0x00, 0x00, 0x00)
54. GRAY = RGBColor(0x43, 0x43, 0x43)
56. BODY_FONT = "Arial"
57. CODE_FONT = "Courier New"
59. TEMPLATE_PATH = Path(__file__).parent.parent / "assets" / "template.docx"
62. def _set_cell_background(cell, hex_color):
63. tc_pr = cell._tc.get_or_add_tcPr()
64. shd = OxmlElement('w:shd')
65. shd.set(qn('w:fill'), hex_color)
66. shd.set(qn('w:val'), 'clear')
67. tc_pr.append(shd)
70. def _apply_table_borders(table, color="B0B0B0", size="4"):
71. """Apply thin gray borders to every cell of a table via raw XML."""
72. tbl_pr = table._element.find(qn('w:tblPr'))
73. if tbl_pr is None:
74. tbl_pr = OxmlElement('w:tblPr')
75. table._element.insert(0, tbl_pr)
76. tbl_borders = OxmlElement('w:tblBorders')
77. for edge in ('top', 'left', 'bottom', 'right', 'insideH', 'insideV'):
78. b = OxmlElement(f'w:{edge}')
79. b.set(qn('w:val'), 'single')
80. b.set(qn('w:sz'), size)
81. b.set(qn('w:color'), color)
82. tbl_borders.append(b)
83. # Remove any existing borders block
84. existing = tbl_pr.find(qn('w:tblBorders'))
85. if existing is not None:
86. tbl_pr.remove(existing)
87. tbl_pr.append(tbl_borders)
90. def _style_run(run, font=BODY_FONT, size=11, bold=False, italic=False, color=BODY_BLACK):
91. run.font.name = font
92. run.font.size = Pt(size)
93. run.bold = bold
94. run.italic = italic
95. if color is not None:
96. run.font.color.rgb = color
99. def _add_styled_para(doc, text, *, style=None, font=BODY_FONT, size=11, bold=False,
100. italic=False, color=BODY_BLACK, alignment=None):
101. p = doc.add_paragraph(style=style) if style else doc.add_paragraph()
102. if alignment is not None:
103. p.alignment = alignment
104. run = p.add_run(text)
105. _style_run(run, font=font, size=size, bold=bold, italic=italic, color=color)
106. return p
109. def _filename(title, mm_yyyy, initials, draft=False, template=False):
110. """Build the Meridian SOP filename. mm_yyyy uses '/' inside; filename uses '-'."""
111. safe_title = title.strip()
112. # Filename uses dash between month and year
113. mm_dash_yyyy = mm_yyyy.replace("/", "-")
114. name = f"SOP_{safe_title}_{mm_dash_yyyy}_{initials}"
115. if template:
116. name = f"SOP_{safe_title}_TEMPLATE_{mm_dash_yyyy}_{initials}"
117. if draft:
118. name = f"DRAFT_{name}"
119. return f"{name}.docx"
122. def _build_title_bar(doc, title, folder_context):
123. """1-cell table at the top: 'SOP | <Title>' on line 1, folder context on line 2."""
124. table = doc.add_table(rows=1, cols=1)
125. table.autofit = True
126. cell = table.cell(0, 0)
127. _set_cell_background(cell, "EAF2F8") # very light blue tint
128. # Wipe the default paragraph
129. cell.text = ""
130. p1 = cell.paragraphs[0]
131. r1 = p1.add_run(f"SOP | {title}")
132. _style_run(r1, font=BODY_FONT, size=16, bold=True, color=MERIDIAN_NAVY)
133. if folder_context:
134. p2 = cell.add_paragraph()
135. r2 = p2.add_run(folder_context)
136. _style_run(r2, font=CODE_FONT, size=10, bold=False, color=MERIDIAN_NAVY)
137. return table
140. def _build_metadata_table(doc, filename, category, owner, effective_date):
141. """4-column header metadata table."""
142. table = doc.add_table(rows=2, cols=4)
143. _apply_table_borders(table)
144. headers = ["File Name", "Category", "Owner", "Effective Date"]
145. values = [filename.replace(".docx", ""), category, owner, effective_date]
146. for ci, (h, v) in enumerate(zip(headers, values)):
147. hcell = table.cell(0, ci)
148. hcell.text = ""
149. hp = hcell.paragraphs[0]
150. hr = hp.add_run(h)
151. _style_run(hr, font=BODY_FONT, size=11, bold=True, color=BODY_BLACK)
152. _set_cell_background(hcell, "D6EAF8")
153. vcell = table.cell(1, ci)
154. vcell.text = ""
155. vp = vcell.paragraphs[0]
156. vr = vp.add_run(v)
157. _style_run(vr, font=BODY_FONT, size=11, bold=False, color=BODY_BLACK)
158. return table
161. def _add_blank(doc):
162. doc.add_paragraph()
165. def _render_section(doc, sec):
166. t = sec.get("type")
167. text = sec.get("text", "")
169. if t == "purpose":
170. h = doc.add_heading("Purpose", level=1)
171. _add_styled_para(doc, text, font=BODY_FONT, size=11)
173. elif t == "scope":
174. h = doc.add_heading("Scope & Responsibility", level=1)
175. _add_styled_para(doc, text, font=BODY_FONT, size=11)
177. elif t == "h1":
178. doc.add_heading(text, level=1)
180. elif t == "h2":
181. doc.add_heading(text, level=2)
183. elif t == "h3":
184. doc.add_heading(text, level=3)
186. elif t == "body":
187. _add_styled_para(doc, text, font=BODY_FONT, size=11)
189. elif t == "accent_subhead":
190. _add_styled_para(doc, text, font=BODY_FONT, size=12, bold=True, color=MERIDIAN_NAVY)
192. elif t == "bullet":
193. p = doc.add_paragraph()
194. p.paragraph_format.left_indent = Inches(0.25)
195. r = p.add_run(f"• {text}")
196. _style_run(r, font=BODY_FONT, size=11)
198. elif t == "numbered":
199. # Number gets auto-incremented within a 'numbered' run via state attached to the doc
200. n = getattr(doc, "_sop_num_counter", 0) + 1
201. setattr(doc, "_sop_num_counter", n)
202. p = doc.add_paragraph()
203. p.paragraph_format.left_indent = Inches(0.25)
204. r = p.add_run(f"{n}. {text}")
205. _style_run(r, font=BODY_FONT, size=11)
207. elif t == "code":
208. # Multi-line code or path block, monospace blue
209. for line in text.split("\n"):
210. p = doc.add_paragraph()
211. r = p.add_run(line if line else " ")
212. _style_run(r, font=CODE_FONT, size=10, color=MERIDIAN_NAVY)
214. elif t == "format_spec":
215. # 1-cell table with the format pattern, monospace blue bold
216. table = doc.add_table(rows=1, cols=1)
217. _apply_table_borders(table)
218. cell = table.cell(0, 0)
219. _set_cell_background(cell, "EAF2F8")
220. cell.text = ""
221. for i, line in enumerate(text.split("\n")):
222. if i == 0:
223. p = cell.paragraphs[0]
224. else:
225. p = cell.add_paragraph()
226. r = p.add_run(line)
227. _style_run(r, font=CODE_FONT, size=11, bold=True, color=MERIDIAN_NAVY)
229. elif t == "components_table":
230. rows = sec["rows"]
231. table = doc.add_table(rows=len(rows), cols=len(rows[0]))
232. _apply_table_borders(table)
233. for ri, row in enumerate(rows):
234. for ci, val in enumerate(row):
235. cell = table.cell(ri, ci)
236. cell.text = ""
237. p = cell.paragraphs[0]
238. r = p.add_run(str(val))
239. is_header = (ri == 0)
240. if is_header:
241. _style_run(r, font=BODY_FONT, size=11, bold=True, color=BODY_BLACK)
242. _set_cell_background(cell, "D6EAF8")
243. else:
244. # First column often holds the code-style identifier; render second column as code
245. if ci == 1:
246. _style_run(r, font=CODE_FONT, size=10, color=MERIDIAN_NAVY)
247. else:
248. _style_run(r, font=BODY_FONT, size=11, color=BODY_BLACK)
250. elif t == "examples_table":
251. rows = sec["rows"]
252. table = doc.add_table(rows=len(rows), cols=len(rows[0]))
253. _apply_table_borders(table)
254. for ri, row in enumerate(rows):
255. for ci, val in enumerate(row):
256. cell = table.cell(ri, ci)
257. cell.text = ""
258. p = cell.paragraphs[0]
259. r = p.add_run(str(val))
260. is_header = (ri == 0)
261. last_col = (ci == len(row) - 1)
262. if is_header:
263. _style_run(r, font=BODY_FONT, size=11, bold=True, color=BODY_BLACK)
264. _set_cell_background(cell, "D6EAF8")
265. else:
266. if last_col:
267. _style_run(r, font=CODE_FONT, size=10, color=MERIDIAN_NAVY)
268. else:
269. _style_run(r, font=BODY_FONT, size=11, color=BODY_BLACK)
271. elif t == "note":
272. # Italic gray note, full-width 1-cell table
273. table = doc.add_table(rows=1, cols=1)
274. cell = table.cell(0, 0)
275. _set_cell_background(cell, "FCF3CF") # light yellow note tint
276. cell.text = ""
277. p = cell.paragraphs[0]
278. r = p.add_run(text)
279. _style_run(r, font=BODY_FONT, size=10, italic=True, color=GRAY)
281. elif t == "warning":
282. # Red bold callout
283. _add_styled_para(doc, text, font=BODY_FONT, size=12, bold=True, color=WARN_RED)
285. elif t == "quick_ref":
286. # 1-cell table styled like a reference card. Monospace, multi-line.
287. table = doc.add_table(rows=1, cols=1)
288. cell = table.cell(0, 0)
289. _set_cell_background(cell, "EAF2F8")
290. cell.text = ""
291. for i, line in enumerate(text.split("\n")):
292. if i == 0:
293. p = cell.paragraphs[0]
294. else:
295. p = cell.add_paragraph()
296. r = p.add_run(line if line else " ")
297. _style_run(r, font=CODE_FONT, size=10, color=MERIDIAN_NAVY)
299. elif t == "blank":
300. _add_blank(doc)
302. else:
303. # Unknown type: render as plain body but flag in console
304. print(f"WARN: unknown section type '{t}', rendering as body", file=sys.stderr)
305. _add_styled_para(doc, text, font=BODY_FONT, size=11)
308. def build_sop(spec):
309. """
310. Build a Meridian SOP .docx from a spec dict.
312. Required keys:
313. title (str) : the process title
314. owner (str) : full name of the owner
315. initials (str) : author initials, e.g. "MG"
316. category (str) : Operations / Design / etc.
317. effective_date (str) : "MM/YYYY"
318. folder_context (str) : the Shared Drive path / scope, e.g. "00 - SOPs > 02 - Operations"
319. sections (list[dict]) : the body, see section schemas above
320. output_path (str|Path) : where to save the .docx
322. Optional keys:
323. draft (bool) : prefix filename with DRAFT_
324. template (bool) : insert _TEMPLATE before the date
325. page_margin_inches (float) : defaults to 1.0
326. """
327. if TEMPLATE_PATH.exists():
328. # Copy template to a scratch path, then open
329. doc = Document(str(TEMPLATE_PATH))
330. # Wipe everything in the template body: we want the styles, not the content
331. for element in list(doc.element.body):
332. doc.element.body.remove(element)
333. # Re-add a sectPr at the end (required by Word)
334. from docx.oxml import OxmlElement
335. sectPr = OxmlElement("w:sectPr")
336. doc.element.body.append(sectPr)
337. else:
338. doc = Document()
340. margin = Inches(spec.get("page_margin_inches", 1.0))
341. for section in doc.sections:
342. section.top_margin = margin
343. section.bottom_margin = margin
344. section.left_margin = margin
345. section.right_margin = margin
347. title = spec["title"]
348. owner = spec["owner"]
349. initials = spec["initials"]
350. category = spec["category"]
351. effective_date = spec["effective_date"] # MM/YYYY
352. folder_context = spec.get("folder_context", "")
353. sections = spec.get("sections", [])
355. filename = _filename(
356. title, effective_date, initials,
357. draft=spec.get("draft", False),
358. template=spec.get("template", False),
359. )
361. _build_title_bar(doc, title, folder_context)
362. _add_blank(doc)
363. _build_metadata_table(doc, filename, category, owner, effective_date)
364. _add_blank(doc)
366. for sec in sections:
367. _render_section(doc, sec)
369. out = spec.get("output_path")
370. if out is None:
371. out = filename
372. out_path = Path(out)
373. if out_path.is_dir():
374. out_path = out_path / filename
375. elif not str(out_path).endswith(".docx"):
376. out_path = Path(str(out_path) + ".docx")
377. # If the user passed a directory or generic name, override with the canonical filename
378. if out_path.name != filename and spec.get("force_filename", True):
379. out_path = out_path.parent / filename
381. doc.save(str(out_path))
382. return str(out_path)
385. def validate(path):
386. """Quick structural check of a Meridian SOP."""
387. doc = Document(path)
388. findings = []
389. # Filename check
390. fn = Path(path).name
391. if not re.match(r"^(DRAFT_)?SOP_.+_(TEMPLATE_)?\d{2}-\d{4}_[A-Z]{2,3}\.docx$", fn):
392. findings.append(f"FAIL: filename '{fn}' does not match SOP_<Title>_<MM-YYYY>_<Initials>.docx pattern")
393. # Title bar (first table, 1 cell, contains 'SOP |')
394. if not doc.tables:
395. findings.append("FAIL: no tables found, title bar missing")
396. else:
397. first = doc.tables[0]
398. if first.rows[0].cells[0].text.startswith("SOP |") or first.rows[0].cells[0].text.startswith("SOP|"):
399. findings.append("PASS: title bar present")
400. else:
401. findings.append(f"FAIL: first table is not a title bar (content: {first.rows[0].cells[0].text[:60]!r})")
402. # Metadata table (4-col, headers File Name / Category / Owner / Effective Date)
403. meta_ok = False
404. for table in doc.tables[:3]:
405. if len(table.columns) == 4 and len(table.rows) >= 2:
406. headers = [c.text.strip() for c in table.rows[0].cells]
407. if headers == ["File Name", "Category", "Owner", "Effective Date"]:
408. meta_ok = True
409. break
410. findings.append("PASS: metadata table present" if meta_ok else "FAIL: metadata table missing or wrong shape")
411. # Required Heading 1 sections
412. h1_texts = [p.text for p in doc.paragraphs if p.style and p.style.name == "Heading 1"]
413. for required in ("Purpose", "Scope & Responsibility"):
414. if any(required in t for t in h1_texts):
415. findings.append(f"PASS: '{required}' section present")
416. else:
417. findings.append(f"FAIL: '{required}' section missing")
418. # Quick Reference Card
419. if any("Quick Reference" in t for t in h1_texts):
420. findings.append("PASS: Quick Reference Card present")
421. else:
422. findings.append("WARN: Quick Reference Card missing (recommended but not strictly required)")
423. return findings
426. def _cli():
427. parser = argparse.ArgumentParser(description="Meridian SOP builder")
428. parser.add_argument("--validate", metavar="FILE", help="Validate an existing .docx against Meridian SOP shape")
429. args = parser.parse_args()
430. if args.validate:
431. findings = validate(args.validate)
432. for f in findings:
433. print(f)
434. fails = [f for f in findings if f.startswith("FAIL")]
435. sys.exit(1 if fails else 0)
436. else:
437. parser.print_help()
440. if __name__ == "__main__":
441. _cli()