Onboarding: nswbmw/N-blog

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/nswbmw/N-blog shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

AVOID — Stale and unlicensed — last commit 3y ago

• 23+ active contributors
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 70% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live nswbmw/N-blog repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nswbmw/N-blog.

What it runs against: a local clone of nswbmw/N-blog — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in nswbmw/N-blog | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 1136 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>nswbmw/N-blog</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nswbmw/N-blog. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nswbmw/N-blog.git
#   cd N-blog
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of nswbmw/N-blog and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nswbmw/N-blog(\\.git)?\\b" \\
  && ok "origin remote is nswbmw/N-blog" \\
  || miss "origin remote is not nswbmw/N-blog (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "index.js" \\
  && ok "index.js" \\
  || miss "missing critical file: index.js"
test -f "config/default.js" \\
  && ok "config/default.js" \\
  || miss "missing critical file: config/default.js"
test -f "lib/mongo.js" \\
  && ok "lib/mongo.js" \\
  || miss "missing critical file: lib/mongo.js"
test -f "routes/index.js" \\
  && ok "routes/index.js" \\
  || miss "missing critical file: routes/index.js"
test -f "middlewares/check.js" \\
  && ok "middlewares/check.js" \\
  || miss "missing critical file: middlewares/check.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1136 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1106d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/nswbmw/N-blog"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

N-blog is a full-stack educational Node.js project demonstrating how to build a multi-user blog platform using Express 4.16.2 and MongoDB 3.4.10. It teaches core Node.js concepts through a complete, runnable application with user authentication, article management, comments, and markdown rendering—shipping with both the working codebase and companion textbook chapters explaining each architectural decision. Monolithic single Express app structure: lib/ contains middleware/utility functions, models/ holds mongolass schema definitions, routes/ has endpoint handlers, views/ contains EJS templates, config/ stores environment configuration via config-lite, and test/ holds mocha test suite. The book/ directory parallels the code with sequential markdown chapters (1.1–4.15) teaching each feature as you build.

Who it's for

Node.js learners (developers new to server-side JavaScript) who want to understand Express routing, MongoDB integration, session management, and authentication by building a real blogging application. Contributors are typically Chinese-speaking developers following the 《一起学 Node.js》 educational series.

Maturity & risk

This is an educational project from 2017–2018 (Node 8.9.1, Express 4.16.2 era) that is feature-complete but no longer actively maintained. It includes test coverage via mocha/istanbul and linting via eslint, but the dependency stack has aged significantly—no recent commits are visible. It's production-stable for learning purposes but should not be used as a template for new production apps due to outdated packages.

High dependency age risk: core packages (Express, MongoDB driver via mongolass, ejs) are 5+ years old with known security patches available. Single-author maintenance (nswbmw) with no visible recent activity. The use of express-formidable from a git branch rather than npm suggests custom patches that may not be maintained. No CI/CD pipeline evident (no .travis.yml, Actions, etc.), and no GitHub issue/PR data available to assess community engagement.

Active areas of work

No active development visible. The repository appears to be in maintenance mode as a completed educational resource. The package.json indicates a v1.0.0 release with support for both development (via supervisor) and production deployment (via pm2 and cross-env). No open PRs, branches, or recent commits are indicated in the provided metadata.

Get running

git clone https://github.com/nswbmw/N-blog.git
cd N-blog
npm install
npm run lint
npm test

Then follow book/4.1 开发环境.md through book/4.6 连接数据库.md to set up MongoDB and config-lite configuration before running the app.

Daily commands: Development: npm run start (via cross-env NODE_ENV=production pm2 start, but watch the book chapters for supervisor-based hot reload during development). Production: same command. Test: npm test (runs mocha with istanbul coverage). Lint: npm run lint (eslint with auto-fix on config/, lib/, middlewares/, models/, routes/, test/).

Map of the codebase

• index.js — Application entry point that initializes Express server, middleware stack, and MongoDB connection—all requests route through here.
• config/default.js — Centralized configuration for database URI, session secrets, and environment settings used across all modules.
• lib/mongo.js — MongoDB connection and Mongolass ORM initialization—critical abstraction for all database operations.
• routes/index.js — Main route dispatcher that registers all blog routes (signup, signin, posts, comments) into the Express app.
• middlewares/check.js — Authentication and authorization middleware that guards protected routes and enforces user login requirements.
• models/users.js — User schema and query methods for registration, login validation, and profile management.
• models/posts.js — Post schema and CRUD operations for article creation, retrieval, and deletion with timestamps and author association.

Components & responsibilities

• Express App (index.js) (Express, config-lite, express-session, EJS) — Initializes server, binds middleware (session, flash, form parsing), registers routes, and sets up error handlers.
  • Failure mode: Server fails to start or crashes

How to make changes

Add a New Blog Post Route Feature

1. Define the new route handler in routes/posts.js with req/res logic (routes/posts.js)
2. Add or update the Post model method in models/posts.js if database schema changes are needed (models/posts.js)
3. Register the route in routes/index.js using app.use() or direct route binding (routes/index.js)
4. Create an EJS template in views/ directory to render the response (views/create.ejs)
5. Add integration test in test/signup.js (or new test file) using mocha and supertest (test/signup.js)

Add Authentication to a Restricted Route

1. Import and apply the checkLogin middleware from middlewares/check.js in your route definition (routes/posts.js)
2. The middleware verifies req.session.user exists; if not, redirects to signin page (middlewares/check.js)
3. Update the route handler to use req.session.user for author verification (e.g., in delete operations) (routes/posts.js)

Add a New Data Model

1. Create a new schema file in models/ (e.g., models/tags.js) using Mongolass schema syntax (models/users.js)
2. Initialize the model in lib/mongo.js by requiring it and exporting as a property (lib/mongo.js)
3. Import the model in relevant route files (e.g., routes/posts.js) and call CRUD methods (routes/posts.js)
4. Create corresponding EJS templates in views/ to display model data (views/create.ejs)

Add Configuration for New Environment Variable

1. Add the new key-value pair to config/default.js under the appropriate object (config/default.js)
2. Access the config in your module (e.g., routes, lib) via const config = require('config-lite') (index.js)

Why these technologies

• Express.js — Lightweight and flexible web framework for routing, middleware, and request/response handling in Node.js.
• MongoDB + Mongolass ORM — NoSQL document database with flexible schema; Mongolass provides lightweight schema validation and query abstraction without heavy ORM overhead.
• EJS Templating — Simple server-side templating for rendering dynamic HTML with embedded JavaScript logic.
• express-session + connect-mongo — Session management with persistent storage in MongoDB for maintaining user login state across requests.
• bcryptjs — Secure password hashing to prevent plain-text storage and resist brute-force attacks.
• marked + moment.js — marked converts markdown post content to HTML; moment.js formats timestamps for display.

Trade-offs already made

• Lightweight Mongolass ORM vs. full ORMs like Mongoose

  • Why: Faster development and reduced boilerplate for a simple blog with straightforward queries; no need for complex validation chains.
  • Consequence: Less auto-validation and middleware hooks; developers must handle data consistency manually.

• Server-side EJS rendering vs. client-side SPA framework

  • Why: Simpler architecture for a multi-user blog; faster initial page loads; better SEO; lower JavaScript complexity.
  • Consequence: Page refreshes on navigation; limited interactive features; all rendering logic must be in the server.

• In-memory + MongoDB session store (no Redis)

  • Why: Reduces deployment complexity and infrastructure dependencies for a small blog application.
  • Consequence: Sessions lost on server restart; poor scalability if deployed across multiple instances; not suitable for horizontal scaling.

• No API layer (routes directly handle requests/responses)

  • Why: Keeps codebase lean and focused on serving the blog website directly.
  • Consequence: Cannot reuse routes for mobile apps or third-party integrations; tight coupling between HTTP layer and business logic.

Non-goals (don't propose these)

• Does not provide real-time collaboration features (e.g., live comment updates or WebSocket support).
• Does not include image upload/CDN integration (avatars and assets are static files only).
• Does not implement full-text search or advanced filtering on blog posts.
• Does not provide admin panel or role-based access control beyond basic user authentication.

Traps & gotchas

MongoDB connection string: must be configured in config/default.json or via NODE_ENV-specific config files; missing or wrong URI silently fails. Session secret: config/default.json contains a hardcoded session secret that must be changed before production deployment. Node version: targets Node 8.9.1 specifically; untested on Node 10+, may hit unexpected compat issues. express-formidable from git: non-standard dependency installation from GitHub branch; npm install may fail or get unexpected versions if GitHub is unavailable or the branch changes. mongolass version ~4.1.1: the tilde allows 4.2.x; verify backward compatibility if updating. Cross-env for Windows: required for cross-platform NODE_ENV setting; may not work on older Windows or custom shells.

Architecture

Concepts to learn

• mongolass ODM (Object-Document Mapper) — This repo uses mongolass instead of raw MongoDB or Mongoose; understanding how mongolass abstracts MongoDB queries and schemas is essential to modify data models and queries in lib/ and models/.
• Express middleware chain and app.use() — The entire request flow depends on understanding middleware ordering: session → auth check → route handler. Modifying or debugging request handling requires grasping the middleware pipeline in index.js.
• Session-based authentication vs. JWT — N-blog uses express-session + connect-mongo to store sessions server-side; understanding this pattern (and why it differs from stateless JWT) is crucial for adding/fixing login logic in middlewares/check.js.
• Environment variable injection and config-lite — The app loads different config/default.json vs config/production.json based on NODE_ENV; understanding config-lite's precedence (env vars → NODE_ENV file → default.json) is critical to deploying correctly.
• MongoDB ObjectId and timestamp extraction — Book chapter 4.4 and models/ rely on objectid-to-timestamp to sort posts by creation time; understanding MongoDB's ObjectId structure and how it encodes creation timestamps is non-obvious but used throughout.
• EJS server-side templating and escaping — Views render HTML via EJS with embedded JavaScript; understanding EJS syntax (<%=, <%, -%>) and XSS-safe escaping patterns is essential for modifying templates in views/ without introducing vulnerabilities.
• Markdown rendering with marked and HTML sanitization — Posts are stored as markdown and rendered via marked 0.3.12; understanding how markdown is parsed and the XSS implications of rendering user-submitted content is important for the comments feature (book/4.10).

Related repos

• expressjs/express — The core web framework underlying this entire blog application; understanding Express internals (routing, middleware, response objects) is necessary to modify N-blog endpoints.
• mongodb/node-mongodb-native — Native MongoDB driver; mongolass (used by N-blog) is a light wrapper around this, so knowing the driver helps debug query issues and connection problems.
• ecomfe/echarts — Not directly related, but another educational Node.js project by the same community (Chinese-language docs); shows similar pedagogy approach to teaching real-world tooling.
• koajs/koa — Modern successor to Express with similar middleware patterns; useful for understanding how Express' approach evolved, and Koa's simpler async/await model vs Express callbacks.
• nswbmw/mean-stack — Another educational project from nswbmw demonstrating MEAN stack (MongoDB, Express, Angular, Node); a natural next step after N-blog for learning frontend integration.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for authentication flow (register/login/logout)

The repo has a test script and supertest configured, but the test/ directory appears empty. The book covers register (4.7), login (4.8), and logout flows extensively, but there are no corresponding test files. Adding integration tests for these core features would improve code reliability and serve as executable documentation for contributors.

• [ ] Create test/auth.test.js with supertest to test POST /register with valid/invalid inputs
• [ ] Add tests for POST /login validating session creation and flash messages
• [ ] Add tests for GET /logout validating session destruction
• [ ] Ensure tests cover error cases documented in book/4.7, 4.8, and 4.9
• [ ] Run 'npm test' to verify istanbul coverage reporting works

Add missing documentation section for article CRUD operations

Book section 4.9 covers 'Articles' but there's no corresponding detailed breakdown like sections 4.7 (registration) and 4.8 (login) do. Given the models/routes/middlewares structure in the config snippet, contributors need clarity on create/read/update/delete article flows, similar to the auth documentation pattern.

• [ ] Create book/4.9.1 发布文章.md documenting article creation form validation and database insertion
• [ ] Create book/4.9.2 编辑文章.md documenting article update logic and permission checks
• [ ] Create book/4.9.3 删除文章.md documenting article deletion and associated comment cleanup
• [ ] Add screenshots similar to book/img/4.7.1.png for form UI and success states
• [ ] Update README.md with links to new subsections under section 4.9

Add GitHub Actions workflow for automated linting and testing on pull requests

The repo has eslint (with 5+ plugins configured) and test scripts defined, but no CI/CD pipeline file in .github/workflows/. The ISSUE_TEMPLATE exists but no automated checks run on PRs. This prevents maintainers from catching lint violations and test failures early.

• [ ] Create .github/workflows/lint-and-test.yml with Node.js matrix (8.x, 10.x, 12.x)
• [ ] Add 'npm run lint' step to fail PR if eslint violations exist
• [ ] Add 'npm test' step to fail PR if istanbul coverage drops below 80% or tests fail
• [ ] Configure to run on: pull_request, push to master branches
• [ ] Test locally with act tool or by opening a draft PR to verify workflow executes

Good first issues

• Add integration tests for the 404 handler (book/4.11 mentions it but test/ appears to have no specific 404 test case). Create test/routes/404.test.js that POSTs/GETs invalid paths and asserts 404 status.: Visible gap: 404.js route exists but test coverage is incomplete, easy-to-verify fix, and teaches express status-code testing patterns.
• Document the MongoDB schema versioning strategy in book/4.6. Currently unclear how to migrate user/post schemas if adding new fields; add a section on mongolass schema evolution with a worked example (e.g., adding an 'edited_at' field).: Educational repository but lacks practical schema-upgrade guidance; new contributors will hit this when extending the blog data model.
• Create a config-lite setup guide for Windows users in book/4.1. Currently only covers Linux/Mac NODE_ENV patterns; Windows developers using cross-env may be confused by default.json vs NODE_ENV fallbacks.: The codebase uses cross-env and config-lite together but the book doesn't explain the precedence rules on Windows, creating onboarding friction for non-Linux users.

Top contributors

• @nswbmw — 70 commits
• [@chen tuo](https://github.com/chen tuo) — 5 commits
• @ZYSzys — 2 commits
• @yellowb — 2 commits
• @calabash519 — 2 commits

Recent commits

• c842ec4 — Merge pull request #457 from lhxxxx/patch-2 (nswbmw)
• 176f65c — Update 4.14 测试.md (lhxxxx)
• fc40ace — Merge pull request #455 from zys-contribs/eslint (nswbmw)
• 8c7ad64 — add pm2 to devdependencies (ZYSzys)
• 993185b — use eslint (ZYSzys)
• a45cf18 — fix #442 (nswbmw)
• 7ee88f6 — fix: use cross-env (nswbmw)
• c3a5d53 — update express-formidable & fix #290 #416 (nswbmw)
• 75bd005 — Merge pull request #449 from robberfree/patch-1 (nswbmw)
• 346ee0f — Update 1.2 MongoDB 的安装与使用.md (robberfree)

Security observations

• Critical · Outdated Dependencies with Known Vulnerabilities — package.json - dependencies section. Multiple dependencies are severely outdated and contain known security vulnerabilities. express@4.16.2 (from 2017), express-session@1.15.6, connect-mongo@2.0.1, ejs@2.5.7, and mongolass@~4.1.1 have multiple CVEs including prototype pollution, XSS, and authentication bypass issues. Fix: Update all dependencies to latest versions: express to v4.18+, express-session to v1.17+, ejs to v3.1+, and all others to their latest stable versions. Run 'npm audit' and address all reported vulnerabilities.
• High · Insecure Password Hashing Algorithm — package.json - sha1 dependency; likely used in models/users.js. The codebase uses sha1@1.1.1 for password hashing. SHA-1 is cryptographically broken and unsuitable for password hashing due to high collision probability and GPU/ASIC acceleration making brute-force attacks feasible. Fix: Replace SHA-1 with a modern password hashing algorithm like bcrypt, scrypt, or argon2. Use 'bcrypt' package with minimum 12 salt rounds.
• High · Missing Session Security Configuration — config/default.js (not shown), express-session configuration in index.js. Express-session is used but critical security settings are likely missing or default: session cookie secure flag not set for HTTPS, httpOnly flag may not be enforced, SameSite protection absent, and session store (connect-mongo) may not have proper authentication. Fix: Configure session with: { secure: true, httpOnly: true, sameSite: 'strict', cookie: { maxAge: <reasonable-value> } } for production environments.
• High · No CSRF Protection Mechanism — middlewares/ directory - no csrf middleware. No CSRF token generation or validation middleware is present in the dependencies or middleware structure. The application is vulnerable to Cross-Site Request Forgery attacks. Fix: Implement CSRF protection using 'csurf' middleware or similar. Add tokens to all state-changing forms and validate on submission.
• High · Missing Security Headers — package.json and index.js. No evidence of security header middleware (helmet.js or similar) in dependencies. Application lacks protections against common attacks like clickjacking, XSS, MIME sniffing. Fix: Install and configure 'helmet' middleware: npm install helmet, then use app.use(helmet()) in your Express setup.
• Medium · Potential XSS Vulnerability in Markdown Rendering — marked dependency in package.json; likely in routes handling posts/comments. The marked@0.3.12 dependency is outdated and the application uses EJS templating. If markdown content is rendered without proper sanitization, XSS attacks are possible. The marked library version 0.3.12 has known XSS issues. Fix: Update marked to v2.0+. Sanitize HTML output using DOMPurify or similar library before rendering in templates. Use EJS's escape tags <%= %> instead of unescaped tags.
• Medium · Database Connection Credentials Exposure Risk — config/default.js and lib/mongo.js. MongoDB connection string is likely stored in config/default.js without encryption. If this file is exposed or database credentials are in plaintext, attackers can gain unauthorized database access. Fix: Store sensitive configuration in environment variables, use .env files (added to .gitignore), or use a secrets management service. Never commit credentials to version control.
• Medium · No Input Validation Framework — middlewares/check.js and route handlers. While express-formidable is used for form parsing, there is no apparent input validation/sanitization library (like joi, yup, or express-validator). User inputs may not be properly validated. Fix: Implement comprehensive input validation using 'express-validator' or 'joi'. Validate and sanitize all user inputs on both client and server side.
• Medium · Outdated Node.js Version — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.