Skip to main content
Contributions are welcome. Please follow the Code of Conduct in issues, pull requests, and discussions.

​
Development setup

1

Clone the repository

git clone https://github.com/UseJunior/safe-docx.git
cd safe-docx
2

Install dependencies

npm ci
3

Build all packages

npm run build

​
Dev commands

Run from the repo root:
CommandDescription
npm run buildBuild all packages
npm run lint:workspacesRun TypeScript type-check across all packages
npm run test:runRun all tests (Vitest)
npm run check:spec-coverageValidate OpenSpec traceability coverage
npm run test:coverage:packagesRun tests with coverage reports
All checks must pass locally before pushing. The pre-submit checklist:
  1. npm run build passes
  2. npm run lint:workspaces passes
  3. npm run test:run passes
  4. npm run check:spec-coverage passes

​
Running tests for a specific package

# Core library only
npm run test:run -w @usejunior/docx-core

# MCP server only
npm run test:run -w @usejunior/docx-mcp

# Build a single package
npm run build -w @usejunior/docx-core

​
Repository layout

packages/
  docx-core/   # OOXML comparison + primitives
  docx-mcp/    # MCP server and editing tools
openspec/      # Specs and change deltas

​
Branch naming

Create a branch for every change — never commit directly to main.
Branch typeFormatExample
Issue work{issue}-{description}-{YYYYMMDD}42-add-redline-support-20260221
Minor fixestweak-{description}tweak-fix-typo-in-readme

​
Commit format

Use Conventional Commits: 
type(scope): imperative subject

Body explaining WHY this change was made, not just what changed.
Context, trade-offs, and alternatives considered are all welcome here.
Longer is better.

Fixes: #42
Valid types: feat, fix, refactor, test, docs, chore, ci, perf, style Scope to the affected package: 
fix(docx-core): correct bookmark ID collision in inplace reconstruction
feat(docx-mcp): add delete_comment tool
docs(contributing): clarify branch naming rules
Reference issues in the commit body with Fixes: #N (closes) or Ref: #N (related).

​
Pull request guidelines

  • Keep PRs small and focused — one concern per PR
  • Include test evidence for behavior changes
  • Include screenshots or gifs for any PR that touches visible output (diff rendering, formatting)
  • For new capabilities or behavior shifts, include an OpenSpec change
  • Before review begins: interactive rebase to clean up history is encouraged
  • After review begins: do not force push — reviewers need to see incremental changes
  • After review completes: squash merge or rebase to produce a clean history on main

​
Issues and discussions

Open issues at github.com/UseJunior/safe-docx/issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us