docx-cli: Instructions file for Claude Code

docx-cli

CLI for AI agents to read, edit, and comment on .docx files. JSON-AST output, locator-based addressing, full format fidelity via in-place XML mutation.

Bun, not Node. Use Bun.file, Bun.write, Bun.env, Bun.$. Bun loads .env automatically — no dotenv.

Subsystem-specific guidance lives in nested CLAUDE.md files that load when you edit those folders. If you need to add a new CLAUDE.md to describe a new practice for a part of the system, do so.

Conventions

These conventions are NOT SUGGESTIONS. These are rules.

• All stdout goes through respond() (JSON ack) or writeStdout() (text) from src/cli/respond.ts — never process.stdout.write. The production sinks use lazy Bun.stdout.writer() / Bun.stderr.writer() FileSinks and await each write and flush before exit. Never switch these to Bun.write(Bun.stdout, ...) or Bun.stdout.write(...): large OS-pipe writes can repeat bytes or hang after a dependency accesses process.stdout (issue #8). Stderr goes through writeStderr() for the same reason. A reader that closes early (docx read … | head) is the consumer's choice, not a command failure: the sink swallows EPIPE, drops later writes, and the command exits with its own code — never rethrow it (main's catch-all would write the error to the same dead pipe and crash with a stack trace).
• File naming: kebab-case, named after the primary export (xml-node.ts → XmlNode).
• Newspaper ordering. The entry point (primary export) goes at the top; its dependencies follow in the order it uses them, then their dependencies, and so on — a file reads top-to-bottom like a newspaper. Use hoisted function declarations for internal helpers so this works at runtime; arrow functions only for inline callbacks and short utilities. Types are usually not the primary exports and should go below the functions/classes that are.
• Feature nesting When a file accumulates too many dependencies to be read well with newspaper ordering (> 300 lines), split them into a separate folder/file named after the feature they're working on. It should be a folder if it is going to represent a logical feature of dependencies. This nesting can continue indefinitely if subfeatures have subfeatures of their own.
• JSX is for emitters only. Files that construct fresh XML can be .tsx; readers/locators/analysis stay .ts. Components are PascalCase, accept props, may return NullableXmlNode (null skipped by flatten). Attribute names with colons use the hyphen shortcut (w-val="x" → w:val="x") or JSX spread.
• Component vs view vs lens vs free function vs transient cursor: five shapes, one decision tree.
  • A pure props → XmlNode builder is a PascalCase component — destructure its props in the signature (no props.x access), and don't take a Document (or any package state).
  • Stateful OOXML state lives in tree-owning views, embedded as fields on Document: Body, plus one view per OPC part — StylesView, NumberingView, CommentsView, NotesView, RelationshipsView, ContentTypesView, SettingsView, CorePropertiesView, MarginalsView. Each owns its part's XmlNode tree and any maps keyed to it, and exposes a fromPackage/fromXml/writeTo lifecycle (register too, for the lazily-provisioned ones). MarginalsView is the one that owns MANY parts (every word/header{N}.xml / word/footer{N}.xml) keyed by part name rather than one — so it has no single register; the Marginals lens mints each part's rel + content-type as it allocates it. Cross-view dependencies (e.g., NotesView.ensureNoteStyles(stylesView)) are passed as method arguments — no view reaches up to Document.
  • Cross-cutting lenses (Images, Hyperlinks, Equations, TrackChanges, Comments, Fonts, Marginals) are NOT fields on Document — they're stateless, constructed at the call site: new Images(document).add(source), new TrackChanges(document).accept(["tc0"]), new Marginals(document).set(sectPrs, "footer", "default", spec), await new Fonts(document).setDefault("Times New Roman"). They hold only a back-reference; the embedded views are the state they reach through. Marginals is the header/footer authoring lens — the noun pair docx headers/docx footers share it via MarginalKind the way footnotes/endnotes share Note — reaching through MarginalsView (part trees) + relationships/content-types (part registration) + settings (the even/odd toggle) + the live <w:sectPr> reference nodes (see src/core/marginals). Fonts is the one that also touches an UNMODELED part — the document font lives in BOTH word/styles.xml <w:docDefaults> (owned by StylesView) and word/theme/theme1.xml's <a:fontScheme> (not a view: read/mutated/staged through Pkg only when set-default-font runs, so unrelated saves never re-serialize the theme blob).
  • Free functions are reserved for: pure builders (the components above), the AST reader (src/core/ast/read.ts — Document's construction pass; populates the embedded views from XML and is the sole assigner of tcN ids), and emitter helpers in src/core/blocks/table/sections that thread a Document because they touch many slices in one call. If a free function's body operates on one slice of document, make it a method on that slice's view instead.
  • Transient cursors are the one stateful shape that is NEITHER a view nor a lens: a short-lived object holding position state over a SINGLE node's child list, valid only within one mutation pass (today CellInsertionCursor in src/core/table, which keeps a batch's inserts into one <w:tc> in entry order). It holds no Document, isn't embedded on one, and dies with the pass — so don't file it as a lens. It lives beside the primitives it sequences, and the CLI constructs one per target and calls it.
• JSX.Element = XmlNode (single, not nullable). Fragment returns a #fragment sentinel unwrapped in flatten() and serialize(). Components return null to render nothing; jsx() converts that to an empty fragment. The jsx/jsxs/jsxDEV runtime exports are distinct functions, not = jsx aliases (knip flags aliased re-exports as duplicates) — don't collapse them.
• Path aliases: @core → src/core/index.ts, @core/* → src/core/*. Use these in src/cli/*; src/core itself uses relative sibling imports. Import the body emitters from the @core/blocks and @core/table subpaths, not the @core barrel — ast/types already exports Paragraph/Table/TableCell/TableRow as types, and barrel-merging the same-named value emitters is confusing.
• Variable names: descriptive, no single/two-letter (paragraph not p). Exception: regex-match destructuring (const [, prefix, idx] = match).
• Inline props in the signature. When a component's props type is used only by that component, write it inline (function HeadingStyle({ styleId }: { styleId: BaselineStyleId; … })) rather than declaring a separate named Props type. Extract a named type only when it's shared.
• knip runs strict (bun run check, no rule overrides in knip.json). An unused export is dead code — delete it (this is a CLI app, not a library; there are no external @core consumers). The one exception: an export staged for a named upcoming tier with no caller yet gets a @public JSDoc tag whose comment names the future consumer (knip honors @public) — e.g. HorizontalRule (S8) and the r/a/wp/pic image namespaces (S5). Don't silence knip by re-adding rule suppressions.
• Style: tabs, double quotes (Biome enforced). Early returns over else-if chains.