Skip to content

docs: add CLAUDE.md with build commands and architecture guide#105

Open
jaballer wants to merge 1 commit into
mainfrom
docs/add-claude-md
Open

docs: add CLAUDE.md with build commands and architecture guide#105
jaballer wants to merge 1 commit into
mainfrom
docs/add-claude-md

Conversation

@jaballer

Copy link
Copy Markdown

Summary

Adds a CLAUDE.md at the repo root to give Claude Code (and any new contributor) a fast, accurate mental model of the project. Focuses on the non-obvious things that require reading across multiple files.

What it documents

  • Commands — build/test/lint scripts, and how to run a single unit test through ts-node (no build) vs. the full integration suite.
  • Build/test coupling gotchas:
    • Integration tests shell out to the compiled ./dist/index.js and hit the live Postmark API, so they require a prior npm run build and real tokens in test/config/testing_keys.json. CI runs unit tests only.
    • preview/ isn't compiled — it's copied into dist/ by the syncPreview step, so preview edits need a rebuild.
  • Architecture:
    • Two-layer yargs commandDir routing (thin parent command via the cmd() helper → subcommand directory).
    • Token/config flow: .env('POSTMARK') mapping env vars into hidden yargs args, with validateToken() prompting as fallback; ServerClient vs AccountClient.
    • The template manifest system (one directory per template: meta.json + content.html/content.txt, layouts under _layouts/) and how pull/push/preview revolve around it.
    • Output conventions (log(), CommandResponse, fatalError).
  • Style — Prettier no-semicolons/single-quote/trailing-comma rules and strict ES5/CommonJS TypeScript.

Notes

Documentation only — no source or behavior changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant