Feat/path traversal article (#34)

* feat: first draft of new article

* chore: work in progress

* chore: work in progress

* chore: improve content style and instructions for LLMs

* chore: progress on article

* chore: good progress on article

* chore: other improvements

Author: lmammino

.claude/article-brief-template.md

@@ -60,6 +60,17 @@ Use this template when planning new blog articles for Node.js Design Patterns.
 
 ---
 
+### Writing Style Checklist
+
+- [ ] No em dashes (—) used anywhere
+- [ ] Context provided before diving into implementation details
+- [ ] Explains "why" not just "how" for each concept
+- [ ] Friendly, conversational tone throughout
+- [ ] Sections connected with transitions (forward/backward references)
+- [ ] Technical explanations start with the problem/use case
+
+---
+
 ### Internal Links
 
 Link to related existing articles:

.claude/constitution.md

@@ -41,6 +41,34 @@ We adhere to a set of coding standards to ensure code quality and maintainabilit
 
 The repository uses well-defined formatting rules through [Prettier](https://prettier.io/) and linting through [ESLint](https://eslint.org/).
 
+### Content Writing Style
+
+When creating or editing written content (blog articles, documentation, tutorials), follow these style guidelines:
+
+#### Tone and Readability
+- Use a **friendly, approachable tone** - almost colloquial, as if explaining to a colleague
+- Write in a conversational style while maintaining technical accuracy
+- Avoid overly formal or academic language
+
+#### Punctuation and Formatting
+- **Never use em dashes (—)** - use commas, parentheses, or separate sentences instead
+- Use short paragraphs and clear sentence structure
+- Break up long explanations with code examples, lists, or callouts
+
+#### Structure and Flow
+- **Always provide context first** - explain the "what" and "why" before diving into "how"
+- **Emphasize the "why"** - readers should understand not just how something works, but why it matters and why it works that way
+- **Connect sections smoothly** using:
+  - Forward references: "In the next section, we'll see how to handle errors"
+  - Backward references: "As we saw earlier, streams provide memory efficiency"
+  - Brief previews of what's coming: "Before we implement this, let's understand the underlying concept"
+
+#### Technical Explanations
+- Start with the problem or use case before introducing the solution
+- Explain concepts progressively - simple version first, then edge cases and advanced usage
+- Use real-world analogies when explaining abstract concepts
+- Include practical examples that readers can relate to their own projects
+
 ## Deployment
 
 The website is automatically deployed to GitHub Pages through a GitHub Actions workflow. The deployment process is triggered on every push to the `main` branch. The workflow builds the static site and publishes it to GitHub Pages, making it accessible to users. Contributors do not need to manually handle deployment - focus on code quality and the automated pipeline will handle the rest.

.claude/content-calendar.md

@@ -11,6 +11,7 @@
 1. **Node.js Core APIs & Built-ins** - High-volume foundational topics
 2. **Modern Node.js Features** - New capabilities (22+, 23+) with early-mover SEO advantage
 3. **Node.js Patterns & Architecture** - Advanced patterns (light connection to book)
+4. **Node.js Security** - Security best practices and vulnerability prevention
 
 ---
 
@@ -52,12 +53,21 @@
 | 15  | NOT STARTED | Import maps in Node.js        | "node js import maps"  | 1,000+      | Modern    |
 | 16  | NOT STARTED | Encrypting files with Node.js | "node js encrypt file" | 1,500+      | Core APIs |
 
-### Month 9-12: Advanced & Experimental
+### Month 9-10: Security
+
+| #   | Status   | Article                           | Primary Keyword                   | Est. Volume | Pillar   |
+| --- | -------- | --------------------------------- | --------------------------------- | ----------- | -------- |
+| 17  | COMPLETE | **Path Traversal Security Guide** | "node js path traversal"          | 1,000+      | Security |
+| 18  | NOT STARTED | Input Validation in Node.js    | "node js input validation"        | 2,000+      | Security |
+| 19  | NOT STARTED | Secure File Uploads             | "node js secure file upload"      | 1,500+      | Security |
+| 20  | NOT STARTED | OWASP Top 10 for Node.js        | "node js security best practices" | 3,000+      | Security |
+
+### Month 11-12: Advanced & Experimental
 
 | #   | Status      | Article                        | Primary Keyword | Notes                 |
 | --- | ----------- | ------------------------------ | --------------- | --------------------- |
-| 17+ | NOT STARTED | Rust/Zig + Node.js integration | niche           | Thought leadership    |
-| 18+ | NOT STARTED | TBD based on analytics         | TBD             | Iterate based on data |
+| 21+ | NOT STARTED | Rust/Zig + Node.js integration | niche           | Thought leadership    |
+| 22+ | NOT STARTED | TBD based on analytics         | TBD             | Iterate based on data |
 
 ---
 
@@ -69,6 +79,7 @@
 | Stream consumers         | COMPLETE | /blog/node-js-stream-consumer                            |
 | Async iterators          | COMPLETE | /blog/javascript-async-iterators                         |
 | Race conditions          | COMPLETE | /blog/node-js-race-conditions                            |
+| Path traversal security  | COMPLETE | /blog/nodejs-path-traversal-security                     |
 | Checking Node.js version | COMPLETE | /blog/checking-node-js-version                           |
 | Installing Node.js       | UPDATED  | /blog/5-ways-to-install-node-js                          |
 | Docker development       | COMPLETE | /blog/node-js-development-with-docker-and-docker-compose |
@@ -88,6 +99,7 @@ Environment Variables
 Files & Paths
     └── links to → Reading/Writing Files (existing)
     └── links to → Hashing Files
+    └── links to → Path Traversal Security (existing)
     └── links to → Encrypting Files
 
 Streams Guide
@@ -102,6 +114,20 @@ Event Emitter
 Installing Node.js
     └── links to → Checking Node.js version (existing)
     └── links to → Docker development (existing)
+
+Path Traversal Security (NEW)
+    └── links to → Reading/Writing Files (existing)
+    └── links to → Race Conditions (existing)
+    └── links to → 5 Ways to Install Node.js (existing)
+    └── links to → Input Validation (future)
+    └── links to → Secure File Uploads (future)
+    └── links to → OWASP Top 10 for Node.js (future)
+
+Security Cluster (future)
+    └── Path Traversal Security (hub for file security)
+    └── Input Validation
+    └── Secure File Uploads
+    └── OWASP Top 10 for Node.js (potential hub)
 ```
 
 ---
@@ -112,8 +138,11 @@ Installing Node.js
 - [x] Update "5 Ways to Install Node.js" with fnm, Volta, Docker
 - [x] Cross-link existing articles
 - [x] Add CTAs for free chapter download to all posts
+- [x] Publish path traversal security article (new security pillar)
+- [x] Add link to path traversal article from Reading/Writing Files guide
 - [ ] Monitor keyword rankings for existing content
 - [ ] A/B test CTA placements
+- [ ] Promote path traversal article on security forums (r/netsec, HN)
 
 ---
 
@@ -123,3 +152,6 @@ Installing Node.js
 - Most competing articles still recommend axios/got first - opportunity to differentiate
 - New Node.js features (22+, 23+) have early-mover advantage
 - Light book excerpts where relevant (Ch 6 streams, Ch 10 testing)
+- **Security content** differentiates us from typical tutorial sites and builds trust/authority
+- Path traversal article targets developers building file servers, image handlers, and upload systems
+- Security topics have strong CVE/news hooks for promotion and backlinks

.claude/instructions.md

@@ -9,6 +9,7 @@ Key principles to remember:
 - Maintain accessibility standards (semantic HTML, ARIA, keyboard navigation)
 - Use data-driven approach with strongly typed content collections
 - Follow established coding standards with ESLint and Prettier
+- Follow content writing style guidelines (friendly tone, context-first, explain the "why")
 - All changes are automatically deployed via GitHub Actions to GitHub Pages
 
 Always read the constitution file when starting work to ensure alignment with project principles.

.claude/settings.local.json

@@ -43,7 +43,8 @@
       "mcp__playwright__browser_network_requests",
       "mcp__playwright__browser_close",
       "mcp__playwright__browser_resize",
-      "mcp__playwright__browser_run_code"
+      "mcp__playwright__browser_run_code",
+      "Skill(marketing-skills:seo-audit)"
     ]
   }
 }

AGENTS.md

@@ -0,0 +1,122 @@
+# AGENTS.md
+
+This file provides guidance to AI coding assistants when working with code in this repository.
+
+## Project Overview
+
+Official website for the book "Node.js Design Patterns" by Mario Casciaro and Luciano Mammino. Built with Astro as a minimal static site, deployed to GitHub Pages at https://nodejsdesignpatterns.com.
+
+## Commands
+
+```bash
+pnpm dev          # Start dev server at localhost:4321
+pnpm build        # Build production site to ./dist/
+pnpm preview      # Preview production build locally
+pnpm lint         # Run ESLint
+pnpm lint:fix     # Fix auto-fixable ESLint issues
+pnpm format       # Format with Prettier
+pnpm format:check # Check formatting
+pnpm typecheck    # TypeScript type checking
+```
+
+## Architecture
+
+### Core Stack
+
+- **Astro 5** - Static site generator (ESM, TypeScript)
+- **Tailwind CSS 4** - Styling via Vite plugin
+- **React** - Used sparingly for interactive components only
+- **pnpm** - Package manager
+
+### Content Collections (`src/content/`)
+
+Strongly typed via Zod schemas in `src/content.config.ts`:
+
+- `authors/` - Author JSON files with profile pics
+- `blog/` - Blog posts (markdown with frontmatter, each in its own folder)
+- `chapters/` - Book chapter descriptions
+- `faq/` - FAQ entries
+- `quotes/` - Testimonials
+- `reviews/` - Book reviews
+
+### Key Directories
+
+- `src/components/` - Astro components (`.astro`) and React components (`.tsx`)
+- `src/components/blog/` - Blog-specific components including `BlogLayout.astro`
+- `src/components/ui/` - Reusable UI components (badge, button, card)
+- `src/pages/` - Astro routes (index, blog, RSS, 404)
+- `src/plugins/` - Remark plugins (admonitions for tip/note/warning/etc.)
+- `src/lib/` - Utilities, constants, theme configuration
+- `src/images/` - Images optimized by Astro
+
+### Markdown Features
+
+Blog posts support admonitions via remark-directive:
+
+```markdown
+:::tip[Custom Title]
+Content here
+:::
+```
+
+Types: `tip`, `note`, `important`, `caution`, `warning`
+
+## Development Principles
+
+1. **Astro-first**: Prefer Astro components over React. Use React only for interactive features that require client-side JS.
+
+2. **Mobile-first responsive**: Use Tailwind breakpoint prefixes (`sm:`, `md:`, `lg:`) starting from mobile layouts.
+
+3. **Accessibility required**: Semantic HTML, proper heading hierarchy, ARIA labels, keyboard navigation, WCAG AA contrast.
+
+4. **Data-driven content**: Separate data from templates. Use content collections with Zod schemas.
+
+5. **Lean and fast**: Optimize images, minimize JS, pre-build everything possible.
+
+## Spec-Driven Development Workflow
+
+This project uses a spec-driven development workflow:
+
+1. **Specify** - Create feature branch and specification
+2. **Plan** - Generate implementation plan from spec
+3. **Tasks** - Break plan into executable tasks
+
+Templates are in `templates/` and helper scripts in `scripts/`.
+
+## Blog Article Creation
+
+New blog articles should:
+
+- Follow the template in `.claude/article-brief-template.md`
+- Use modern ESM syntax and async/await
+- Include FAQ section for schema markup
+- Place each article in its own folder under `src/content/blog/<slug>/`
+
+### Content Writing Style
+
+When writing or editing content, follow these guidelines:
+
+**Tone and Readability**
+
+- Use a friendly, approachable tone, almost colloquial, as if explaining to a colleague
+- Write conversationally while maintaining technical accuracy
+- Avoid overly formal or academic language
+
+**Punctuation**
+
+- Never use em dashes (—). Use commas, parentheses, or separate sentences instead
+
+**Structure and Flow**
+
+- Always provide context first: explain "what" and "why" before diving into "how"
+- Emphasize the "why": readers should understand not just how something works, but why it matters
+- Connect sections smoothly using:
+  - Forward references: "In the next section, we'll see how to handle errors"
+  - Backward references: "As we saw earlier, streams provide memory efficiency"
+  - Previews: "Before we implement this, let's understand the underlying concept"
+
+**Technical Explanations**
+
+- Start with the problem or use case before the solution
+- Explain progressively: simple version first, then edge cases
+- Use real-world analogies for abstract concepts

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md