feat: map Markdown YAML front matter to content properties

[pchuri]

Closes #260

Problem

Content properties such as page width (content-appearance-published) can only be changed one page at a time with property-set. Users who keep pages as Markdown files want to keep selected properties in each file, change them with search and replace, review the change in git, and apply it through the normal upload workflow.

Changes

Writes (create, create-child, update)

• New opt-in --front-matter flag, valid only with --format markdown. Without it, a leading --- stays part of the body (a thematic break), exactly as today.

• Only the properties map is applied; other top-level keys are ignored:

  ---
  properties:
    content-appearance-published: full-width
  ---

• Front matter is parsed and validated before any network call, so invalid YAML uploads nothing. create-child now resolves the parent page after this check.

• Properties not listed are left untouched. A property whose stored value already matches (deep equality) is not rewritten.

• A block without a properties map prints a warning. --front-matter is rejected with --type folder.

• A document without front matter is uploaded as-is and sets no properties.

Partial failure

• The body is saved first, then each property in order. A failing key does not stop the remaining keys.
• If any key fails, the command prints the normal success output, then reports that the body was saved and which keys failed (with HTTP status and Confluence's error message), and exits 1.
• With --json, stdout carries the usual result plus properties: { applied, unchanged, failed }, and stderr carries an error with code PARTIAL_FAILURE and the same properties in details.
• Re-running update is safe: properties that already match are skipped. For create and create-child, the error names the update ... --front-matter command that retries the properties on the new page, since re-running create would try to make another page.

Reads

• read --format markdown --front-matter key1,key2 prepends the listed properties that exist, in the given order. Missing keys are omitted. If none exist, no block is emitted, unless the body itself starts with ---; then an empty properties: {} block is emitted so a later --front-matter upload cannot mistake the body for front matter.
• Keys keep the requested order, including integer-like keys.
• Round trips are stable and normalized rather than byte-identical, since the Markdown conversion can normalize formatting.
• The README notes that Cloud also keeps content-appearance-draft, so both keys should be set for page width.

Guards

• update --front-matter with a document that has front matter but no body is refused instead of emptying the page. Blank content without front matter behaves as it does without the flag. Use property-set to change only properties.
• A bare key: (top-level null) is rejected as a likely mistake. Nulls nested inside a value are kept, so existing JSON properties round-trip.
• YAML is loaded with the core schema, so 2026-10-05 stays a string instead of becoming a date. On output, date-like strings are quoted.

Dependency

• js-yaml becomes a direct dependency. The top-level override now uses "$js-yaml", because an override that differs from a direct dependency spec makes npm pack fail with EOVERRIDE. js-yaml and argparse are included in the generated production shrinkwrap.

Not included

• export does not emit front matter yet.
• The Pi extension tools do not expose --front-matter.

Testing

• tests/front-matter.test.js: parsing (no front matter, CRLF, BOM, ... closing, ignored keys, empty block, later thematic breaks, nested nulls, dates), rejections (unterminated, invalid YAML, non-mapping root or properties, bare null, non-finite numbers), serialization order and round trip, the thematic-break guard, and key list parsing.
• tests/confluence-client.test.js: syncProperties creates missing keys, increments the version of changed keys, skips matching keys, and keeps going after a failure; getPropertyValues keeps the requested order, omits 404s, and propagates other errors.
• tests/front-matter-cli.test.js: body stripping and property application for all three write commands, pass-through without the flag, validation before any network call, the --format markdown and body requirements, the empty-body guard, text and --json partial failure output, read output, and a read → update round trip.
• npm test (1812 tests) and npm run lint pass.
• A separate review ran the real CLI against a mock Confluence HTTP server (real axios, interceptors, and request gate): read --front-matter → update --front-matter reproduced the same storage body and left matching properties untouched, and invalid front matter made no HTTP requests.
• Not yet verified against a live Confluence instance. Feedback from a real run (Cloud or Data Center) would be very welcome.

[github-actions]

🎉 This PR is included in version 2.28.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀