How nrjdalal/karabiner-human-config works
Project type and purpose
• This is a Node.js CLI tool (npm package) named karabiner-human-config.
• Its purpose is to take a human‐friendly JSON config (konfig.json) and generate a Karabiner-Elements JSON file (karabiner.json) with complex key-mapping rules.
File structure
• Top‐level:
• bin/ – CLI entrypoint (index.ts) and transformation libraries (lib/*.ts)
• constants/ – alias definitions (custom-aliases.ts, manipulator-keys.ts)
• examples/ – sample input (nrjdalal.json) and sample output (karabiner.json)
• config/build: tsconfig.json, tsup.config.ts
• release pipeline: .changeset/, .github/workflows/release.yml
• No frontend or database; the architecture is a simple command‐line → parser/transformer → filesystem pipeline.
README for additional insights
• Describes CLI usage, input/output defaults, aliasing system, transformation rules.
Components & interactions
a. Main components
1. User & Shell: invokes npx karabiner-human-config.
2. CLI Entrypoint (bin/index.ts → compiled JS)
3. Parser & Normalizer (bin/lib/from.ts, to.ts, helper utils)
4. Alias Resolver (constants/custom-aliases.ts, manipulator-keys.ts)
5. Transformer (bin/lib/transformer.ts)
6. File I/O module (bin/utils/index.ts)
7. Generated Artifact (karabiner.json)
8. External Consumer: Karabiner-Elements (reads the generated JSON)
b. Relationships & data flow
• CLI reads konfig.json via File I/O
• Raw config → Parser
• Parser + Alias Resolver → Abstract representation
• Abstract representation → Transformer → Karabiner JSON schema
• Transformer output → File I/O writes karabiner.json
• Karabiner-Elements imports karabiner.json at runtime
c. Architectural patterns & principles
• Single‐responsibility modules: each file in bin/lib handles one aspect of transformation
• Centralized constants for alias mapping → easy extensibility
• Pipeline pattern: input → parse → transform → output
• Decoupled I/O → pure transformation logic (eases testing)
d. Key technologies & libraries
• Node.js & TypeScript
• tsup (bundler)
• Changesets & GitHub Actions (release automation)
• Karabiner-Elements JSON schema (external target)
Detailed coverage
• Build vs. runtime separation (e.g., tsup compile step before CLI execution)
• Inputs & outputs explicitly: konfig.json → karabiner.json