From 47fd7c40aba122d210646e6003f628c2fc1822f7 Mon Sep 17 00:00:00 2001 From: Satyam Yadav <114805086+Coding-Professional@users.noreply.github.com> Date: Fri, 30 Oct 2026 20:11:12 +0530 Subject: [PATCH 1/4] docs: prepare repository for community contributions --- .github/ISSUE_TEMPLATE/bug_report.yml | 40 +++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 24 +++ .github/dependabot.yml | 14 ++ .github/pull_request_template.md | 15 ++ .github/workflows/ci.yml | 44 ++++++ CODE_OF_CONDUCT.md | 50 +++++++ CONTRIBUTING.md | 65 ++++++++ README.md | 165 ++++++++++----------- SECURITY.md | 20 +++ THIRD_PARTY_NOTICES.md | 65 ++++++++ docs/agent-tools.md | 31 ++++ docs/architecture.md | 66 +++++++++ docs/content-guide.md | 12 +- docs/security.md | 13 +- 15 files changed, 521 insertions(+), 104 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/dependabot.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/ci.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 THIRD_PARTY_NOTICES.md create mode 100644 docs/agent-tools.md create mode 100644 docs/architecture.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..5608275 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,40 @@ +name: Bug report +description: Report a reproducible problem with the site. +title: "bug: " +labels: [bug] +body: + - type: markdown + attributes: + value: Before submitting, check whether this problem has already been reported. + - type: textarea + id: summary + attributes: + label: What happened? + description: Describe the problem in a few sentences. + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + placeholder: "1. Open ...\n2. Select ...\n3. See the error" + validations: + required: true + - type: textarea + id: expected + attributes: + label: What did you expect to happen? + validations: + required: true + - type: input + id: environment + attributes: + label: Browser and device + placeholder: Chrome on Android, Firefox on Windows, etc. + - type: checkboxes + id: privacy + attributes: + label: Before submitting + options: + - label: I removed passwords, tokens and personal information from this report. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3ba13e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..5683db8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,24 @@ +name: Feature request +description: Suggest an improvement for students or contributors. +title: "feature: " +labels: [enhancement] +body: + - type: textarea + id: problem + attributes: + label: What problem should this solve? + description: Explain who is affected and what they need to do. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: What would you like to happen? + description: Describe a possible solution. Screenshots or examples are welcome. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Other options or context + description: Add any alternatives, constraints or related issues. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..4a36204 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,14 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: / + schedule: + interval: weekly + day: monday + open-pull-requests-limit: 5 + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + day: monday + open-pull-requests-limit: 5 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..ab05ca9 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## Summary + + + +## Checks + +- [ ] `npm run lint` +- [ ] `npm run typecheck` +- [ ] `npm test` +- [ ] `npm run build` +- [ ] Browser checks, when the change affects routes or interactions + +## Review notes + + diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..64d0466 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,44 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + verify: + name: Lint, typecheck, tests and build + runs-on: ubuntu-24.04 + timeout-minutes: 15 + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + + - name: Install dependencies + run: npm ci + + - name: Lint + run: npm run lint + + - name: Typecheck + run: npm run typecheck + + - name: Unit tests + run: npm test + + - name: Production build + run: npm run build diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..504ffea --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,50 @@ +# Contributor Covenant Code of Conduct + +## Our pledge + +We are committed to making participation in this project a respectful experience for everyone, +regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, +gender identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, +and healthy community. + +## Our standards + +Examples of behavior that contributes to a positive environment include: + +- Showing empathy and kindness toward other people. +- Giving and accepting constructive feedback respectfully. +- Taking responsibility, apologizing to those affected, and learning from mistakes. +- Focusing on what is best for the community. + +Examples of unacceptable behavior include: + +- Sexualized language or imagery, and unwelcome sexual attention. +- Trolling, insulting or derogatory comments, and personal or political attacks. +- Public or private harassment, including deliberate intimidation or stalking. +- Publishing another person's private information without permission. +- Other conduct that would reasonably be considered inappropriate in a professional setting. + +## Enforcement responsibilities + +Project maintainers are responsible for clarifying and enforcing these standards and may remove, +edit or reject comments, commits, code, issue reports and other contributions that do not align +with this Code. Maintainers may temporarily or permanently restrict participation for behavior +they consider inappropriate, threatening, offensive or harmful. + +## Scope + +This Code applies within project spaces and when someone is officially representing the project +in public spaces. + +## Reporting + +Report unacceptable behavior to **procoderji@gmail.com**. Reports will be reviewed and handled +confidentially. Maintainers will communicate the response to the reporter when appropriate. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.1, available at . diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e4715f4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contributing + +Thanks for helping improve ProCoderJii Learning Hub. This guide explains how to set up the +project, check a change and open a pull request. + +## Before you start + +- Check existing issues and pull requests to avoid duplicate work. +- For a large change, open an issue first so the scope can be discussed. +- Follow the [Code of Conduct](CODE_OF_CONDUCT.md). +- For a security vulnerability, use the private reporting instructions in [SECURITY.md](SECURITY.md), + not a public issue. + +## Set up the project + +Use Node.js 22.18 or newer and npm: + +```bash +git clone https://github.com/Coding-Professional/procoderji.git +cd procoderji +npm ci +npm run dev +``` + +Copy `.env.example` to `.env.local` only if you want to test the optional latest-video section. +The documented values are public; do not add credentials or private tokens to the example file. + +## Make a change + +- Keep each pull request focused on one problem or feature. +- Use TypeScript and the existing component and utility patterns. +- Keep controls usable with a keyboard and on a phone. Give form fields labels and interactive + elements visible focus states. +- Add or update a unit test for new data validation or reusable logic. +- Keep study material original. See [docs/content-guide.md](docs/content-guide.md) before adding + notes, guides or job listings. +- Do not add secrets, private user data, generated build output or unlicensed assets. + +## Check your change + +Run the checks that match the files you changed: + +```bash +npm run lint +npm run typecheck +npm test +npm run build +``` + +For route, link and metadata changes, also run `npm run launch-check`. For browser interaction +changes, run `npm run e2e` with Chrome installed. The E2E runner refuses to run if `src/data` or +`src/content` has uncommitted changes because it temporarily installs synthetic fixtures. For +content changes, run `npm test` and `npm run launch-check` instead. + +## Open a pull request + +1. Create a branch from `main` with a short, descriptive name. +2. Make focused commits with clear messages. +3. Open a pull request against `main` and fill in the provided template. +4. Explain the user-facing change and list the checks you ran. Include screenshots for visual + changes when useful. +5. Keep the pull request up to date and respond to review feedback. + +The maintainer reviews contributions before merging. Opening a pull request does not guarantee +that a proposed feature will be accepted; project scope and maintenance cost are part of review. diff --git a/README.md b/README.md index 92622ab..6b51352 100644 --- a/README.md +++ b/README.md @@ -1,110 +1,95 @@ -# ProCoderJii Notes +# ProCoderJii Learning Hub -A small Next.js site that goes with the ProCoderJii YouTube channel. Visitors pick a -branch and semester and read unit-wise notes online. +A learning site for engineering students. It brings together course notes, guides, career +listings and short browser-based practice games in one place. -> **Status:** the browsing structure (B.Tech → CSE / AIML → Semesters 1-8) is in place, -> but no subjects or notes are published yet. Empty semesters show a "Notes coming soon" -> page. The sample MDX files under `src/content` are placeholders and are -> intentionally **not** registered in the catalogue. +> **Current content status:** the course browser is ready, but the notes catalogue has no +> published subjects yet. The sample files under `src/content` are intentionally unregistered. +> Guides and job listings are also empty until reviewed content is added. -## What it is (and is not) +## What is included -- A statically-built notes site with browser-based practice games: Next.js App Router, - React 19, Tailwind CSS 4, Framer Motion, `next-mdx-remote` for rendering notes. -- Content lives in the repository (MDX files + `src/data/courses.json`). -- There is **no database, no user accounts, no admin panel, no PDF downloads, no search - and no chatbot.** Older versions of this README described those; they do not exist. -- `/games` offers two free browser-based practice games: Pattern Sprint and Digit Recall. - They do not require login or save scores; each session's result lasts until the page is refreshed. -- The contact form opens the visitor's email app with a pre-filled message to the team - address. Nothing is stored or sent by the server. +- A Next.js site for browsing course notes by course, branch and semester. +- A content pipeline that validates Markdown notes and keeps unsafe HTML out of published pages. +- Two free games at `/games`: Pattern Sprint and Digit Recall. They need no account and do not + save scores between visits. +- Optional latest-video cards using the channel's public YouTube feed. +- Hand-curated guides and job listings, shown only when reviewed items are available. -## Requirements +There are no accounts, database, admin panel, PDF downloads or chatbot. The contact form opens +the visitor's email app; the site does not store contact submissions. -- Node.js **20.9 or newer** to run and build the site (required by Next.js 16). -- Node.js **22.18 or newer** (24 recommended) to run `npm test`, `npm run e2e` and - `npm run launch-check`: the tests import TypeScript directly through Node's built-in type - stripping, which older versions do not have. -- npm (a `package-lock.json` is committed; use `npm ci`). +The site uses Next.js 16, React 19, TypeScript, Tailwind CSS 4 and MDX. The `private` flag in +`package.json` prevents npm package publishing; it does not set GitHub repository visibility. -## Getting started +## Run locally + +### Requirements + +- Node.js 22.18 or newer for the full test suite; Node.js 24 is also supported. +- npm. The repository commits `package-lock.json`, so use `npm ci`. ```bash +git clone https://github.com/Coding-Professional/procoderji.git +cd procoderji npm ci -npm run dev # http://localhost:3000 +npm run dev ``` -### Scripts - -| Script | What it does | -| ------------------- | ---------------------------------------------------- | -| `npm run dev` | Start the dev server | -| `npm run build` | Production build | -| `npm start` | Serve the production build | -| `npm run lint` | ESLint | -| `npm run typecheck` | TypeScript (`tsc --noEmit`) | -| `npm test` | Unit tests (Node's built-in test runner, no extra deps) | -| `npm run e2e` | Browser tests in real Chrome (desktop + mobile); see below | -| `npm run launch-check` | Builds the real site and crawls it: links, anchors, sitemap, robots, canonicals, noindex rules | - -Run `npm run lint && npm run typecheck && npm test && npm run build` before opening a PR. - -**Browser tests (`npm run e2e`)** build the site with temporary *synthetic* notes, guides and jobs, -drive Google Chrome (`E2E_CHANNEL=msedge` for Edge) over every page at desktop and phone size, check -navigation, menus, forms, 404s, heading structure, landmarks, accessible names, overflow, SEO tags -and that hostile note content is neutralised, then restore your data. It refuses to run if -`src/data` or `src/content` has uncommitted changes, so it cannot overwrite real content. The -latest-videos checks run only when `YOUTUBE_CHANNEL_ID` is set (they need the live feed). - -### Configuration - -| Variable | Purpose | -| ---------------------- | ----------------------------------------------------------------------- | -| `NEXT_PUBLIC_SITE_URL` | Canonical site origin. Optional; defaults to `https://procoderji.com`. | -| `YOUTUBE_CHANNEL_ID` | Public channel id for the "Latest videos" section. Optional; the section is hidden while unset. See `.env.example`. | - -The primary domain is `https://procoderji.com`. Canonical links, Open Graph URLs, -`sitemap.xml` and `robots.txt` all use it. Set `NEXT_PUBLIC_SITE_URL` only to override -it (for example on a staging build) in your hosting provider's environment settings or a -local, git-ignored `.env.local`. An unset or malformed value falls back to the default. -The value is inlined at build time, so redeploy after changing it. - -**Launching?** See [docs/deployment.md](docs/deployment.md) for the exact manual steps: environment -variables, making the apex domain primary and redirecting `www` to it, completing the legal pages, and -the post-deploy checklist. - -## Adding notes - -Notes are Markdown files registered in `src/data/courses.json`. Each registered unit gets -its own indexable page at `/dashboard/////`, with -breadcrumbs, previous/next links, reading time, an optional "updated" date and structured -data. Only publish reviewed, original content, and never register placeholders. +Open . To enable the latest-video section locally, copy `.env.example` +to `.env.local`; its example channel ID is public and no API key is needed. The app also works +without this setting. + +## Common commands + +| Command | Purpose | +| --- | --- | +| `npm run dev` | Start the local development server | +| `npm run lint` | Check code style and common mistakes | +| `npm run typecheck` | Run TypeScript checks | +| `npm test` | Run unit and content validation tests | +| `npm run build` | Create the production build | +| `npm run launch-check` | Build and crawl the real site, checking links and SEO metadata | +| `npm run e2e` | Run browser checks in Chrome on desktop and mobile | + +The unit tests and browser tests need Node.js 22.18 or newer. Browser tests also need Google +Chrome installed; use `E2E_CHANNEL=msedge` if you have Microsoft Edge instead. The E2E runner +uses temporary synthetic content, refuses to run when `src/data` or `src/content` has local +changes, and restores its fixtures when it exits. + +## Where things live + +```text +src/app/ Routes and page layouts (Next.js App Router) +src/components/ Shared UI and landing-page sections +src/content/ Markdown and MDX content +src/data/ Course, guide and job catalogues +src/lib/ Catalogues, validation, rendering, SEO and game logic +docs/ Architecture, content, security and deployment guides +e2e/ Browser tests, test fixtures and production crawl checks +.github/ CI, issue forms and pull-request templates +.agents/ Optional SEO and UI/UX instructions for coding agents +.claude/ Pointers to the canonical agent skill copies +seo/ Site-specific search and editorial planning notes +``` -See **[docs/content-guide.md](docs/content-guide.md)** for the catalogue fields, the rules -for notes (Markdown only: raw HTML/JSX, expressions and imports are removed for safety) and -the checks to run. +Read [the architecture guide](docs/architecture.md) for how routes, data and content fit +together. To publish notes, see [the content guide](docs/content-guide.md). -## Project structure +## Contributing -``` -src/ -├── app/ -│ ├── page.tsx # landing page -│ ├── dashboard/ # reader: branch → semester → subject → ?note=unit -│ ├── courses/ # legacy reader, unreachable: /courses/* redirects to /dashboard/* -│ ├── robots.ts, sitemap.ts # use the site URL + the catalogue -├── components/ # landing sections, sidebar, cards, empty state -├── content/ # note files (only placeholders for now, not registered) -├── data/courses.json # catalogue: the single source of truth -└── lib/ # catalogue helpers, markdown parser, mailto, SEO (tested) -``` +Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), follow the +[Code of Conduct](CODE_OF_CONDUCT.md), and use the issue forms for bugs or ideas. Please submit +original learning content or link to official sources; do not copy notes, job descriptions, +papers or images without permission. -## Contributing +For security issues, see [SECURITY.md](SECURITY.md). Deployment and environment configuration +are documented in [docs/deployment.md](docs/deployment.md). -Issues and pull requests are welcome. Keep changes focused, add or update a test where -practical, and don't add placeholder or invented study content. +The optional coding-agent tools and their upstream notices are explained in +[docs/agent-tools.md](docs/agent-tools.md) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). ## License -MIT - see [LICENSE](LICENSE). +The project is licensed under the [MIT License](LICENSE). Vendored agent tools retain their +separate upstream notices; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a13e713 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,20 @@ +# Security policy + +## Supported versions + +Security fixes are made on the current `main` branch. Please use the latest version from that +branch. + +## Report a vulnerability + +Do not open a public issue for an unpatched vulnerability. Email **procoderji@gmail.com** with +the affected route or component, the impact, and steps to reproduce. Do not include real user +data or secrets in the report. + +The maintainer will acknowledge the report, investigate it and coordinate a fix before public +disclosure. There is no bug bounty program at this time. + +## Dependency checks + +Run `npm audit` before a release or dependency update. Review advisories and compatible fixes; +avoid force-upgrading or downgrading unrelated packages to silence an audit finding. diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..a705be4 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,65 @@ +# Third-party notices + +The files listed below are vendored development tools. They are not part of the website bundle. +Each upstream project's MIT notice is reproduced here; see the linked repository for the source +and any later updates. + +## UI/UX Pro Max + +Source: [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) + +Included under `.agents/skills/ui-ux-pro-max/`. + +```text +MIT License + +Copyright (c) 2024 Next Level Builder + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + +## SEO Audit + +Source: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) + +Included under `.agents/skills/seo-audit/`. + +```text +MIT License + +Copyright (c) 2025 Corey Haines + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` diff --git a/docs/agent-tools.md b/docs/agent-tools.md new file mode 100644 index 0000000..bfd6e2b --- /dev/null +++ b/docs/agent-tools.md @@ -0,0 +1,31 @@ +# AI agent tools + +The repository includes optional instruction packs for contributors who use compatible coding +agents. They are development aids; the Next.js application does not load or run them. + +## Included skills + +| Path | Purpose | Upstream project | +| --- | --- | --- | +| `.agents/skills/seo-audit/` | Guides an agent through a site SEO audit | [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) | +| `.agents/skills/ui-ux-pro-max/` | UI/UX guidance and local design-data search scripts | [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | + +The corresponding `.claude/skills/` entries are plain-text path pointers to these canonical +copies; they avoid keeping a second copy of the full skill data. If an agent cannot follow those +pointers, open the `.agents/skills/` version directly. + +## Use and maintenance + +- These files are not required to install, build, test or run the website. +- They are vendored snapshots and are not synced automatically. The original upstream commit is + not recorded, so check the source repository before refreshing them. +- The UI/UX search scripts require Python 3 and use the data bundled under that skill's `data/` + directory. +- Treat agent instructions and search results as guidance. Project instructions, security + requirements and maintainer decisions still control changes. +- When updating a skill, record its upstream URL and version or commit, preserve its notices, and + review any data or assets with their own attribution or licence metadata. +- The upstream skills are MIT-licensed. Their notices are reproduced in + [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md). Font and icon data may have additional + terms recorded in the bundled metadata; check those terms before redistributing individual + assets. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..5528e7f --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,66 @@ +# Architecture + +This project is a content-driven Next.js App Router site. Most pages are generated from files in +the repository at build time. There is no database or account system. + +## Request and content flow + +```mermaid +flowchart TD + Browser --> App[Next.js routes in src/app] + App --> Catalog[src/data catalogues] + Catalog --> Notes[src/content Markdown and MDX] + App --> UI[src/components] + App --> Lib[src/lib validation and rendering] + Lib --> Safe[Rendered page content] + Notes --> Lib +``` + +Course notes, guides and jobs use JSON catalogues that point to content files. Only entries in a +catalogue are published. Validation checks slugs, dates and file paths before content is used. +The note renderer accepts a safe Markdown subset; it rejects raw HTML, JSX, expressions and +imports. See [the content guide](content-guide.md) for authoring details. + +## Main areas + +| Path | Responsibility | +| --- | --- | +| `src/app/` | Routes, metadata, page layouts and sitemap/robots endpoints | +| `src/components/` | Shared site shell, landing-page sections, cards and reader UI | +| `src/content/` | Note and guide files | +| `src/data/courses.json` | Course, branch, semester, subject and unit catalogue | +| `src/data/guides.json` | Guide catalogue | +| `src/data/jobs.json` | Hand-curated job and internship catalogue | +| `src/lib/` | Validation, safe paths, Markdown parsing, dates, metadata and game logic | +| `e2e/` | Browser interactions, temporary fixtures and production crawl checks | +| `docs/` | Contributor, content, security and deployment documentation | +| `.agents/` | Optional coding-agent skills; see [agent tools](agent-tools.md) | +| `.claude/` | Pointers to the canonical copies under `.agents/skills/` | + +The old `/courses/*` routes are retained as redirects to `/dashboard/*`; new course work should +use the dashboard routes. + +## Games + +The games hub and individual games live under `src/app/games/`. Game components own their +temporary round state in the browser. Shared question data and digit generation live in +`src/lib/games.ts`; unit tests cover the generated content. Scores are not sent to a server or +saved between visits. + +## Rendering and search indexing + +- Content pages are included in the sitemap only when their referenced file can be read. +- Empty course sections are marked `noindex` and are omitted from the sitemap. +- Site-wide metadata and canonical URLs are built from `NEXT_PUBLIC_SITE_URL`, which defaults to + `https://procoderji.com`. +- Latest videos are fetched from YouTube's public RSS feed only when `YOUTUBE_CHANNEL_ID` is set. + +## Tests + +- `npm test` checks pure helpers, catalogues, file boundaries and content rules. +- `npm run launch-check` builds the real content and crawls routes, links, metadata and sitemap. +- `npm run e2e` installs synthetic content, checks desktop/mobile pages and interactions, then + restores the original files. It needs Chrome or Edge installed. + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for setup and the recommended checks. +For optional agent instructions, see [the agent tools guide](agent-tools.md). diff --git a/docs/content-guide.md b/docs/content-guide.md index 241f9be..493f6a5 100644 --- a/docs/content-guide.md +++ b/docs/content-guide.md @@ -31,8 +31,8 @@ In `src/data/courses.json`, find the branch and semester and add a subject: "title": "Unit 1 - Arrays and Linked Lists", "desc": "Optional short summary shown on the card and in search results.", "path": "content/courses/btech/cse/sem3/data-structures/unit-1.mdx", - "addedAt": "2026-11-01", - "updatedAt": "2026-11-01" + "addedAt": "2026-10-01", + "updatedAt": "2026-10-02" } ] } @@ -124,7 +124,7 @@ registered in `src/data/guides.json` and written as Markdown under `src/content/ "category": "dsa", "level": "beginner", "path": "content/guides/dsa-roadmap.mdx", - "addedAt": "2026-11-01" + "addedAt": "2026-10-01" } ``` @@ -149,9 +149,9 @@ by hand after checking the employer's own careers page. "eligibility": { "degrees": ["B.Tech"], "batches": [2026], "skills": ["..."] }, "summary": "Short summary in YOUR OWN words (max 400 characters).", "applyUrl": "https://the-employer.example/careers/123", - "postedAt": "2026-11-01", - "deadline": "2026-11-30", - "lastVerifiedAt": "2026-11-02" + "postedAt": "2026-10-01", + "deadline": "2026-10-30", + "lastVerifiedAt": "2026-10-02" } ``` diff --git a/docs/security.md b/docs/security.md index 2b8094a..39ba5a8 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,17 +1,14 @@ # Security notes -Last reviewed: 2026-10-14. This is a static, content-driven site: no accounts, no database, no +Last reviewed: 2026-10-30. This is a static, content-driven site: no accounts, no database, no user uploads and no server-side secrets. +To report a vulnerability privately, follow the repository's [security policy](../SECURITY.md). + ## Dependencies -- `npm audit --omit=dev` (what ships to production): **0 vulnerabilities**. -- `npm audit` reports 5 high findings, all one advisory chain in the **linter** dependencies - (`eslint-config-next` -> `@next/eslint-plugin-next` -> `fast-glob` -> `micromatch` -> `braces`; - GHSA-vfj7-8cjw-p6xm, a denial of service on deeply nested glob patterns). None of it is - installed in production, and no patched `braces` release exists yet (3.0.3 is the latest). - Do not run `npm audit fix --force`: it would downgrade `eslint-config-next` to 14.x. Re-check - after each `eslint-config-next` release. +- `npm audit` reported **0 vulnerabilities** on 2026-10-30 after updating Next.js and its matching + ESLint config to 16.4.3. Audit findings change over time; run the command again before a release. - `playwright-core` (browser tests) is a dev dependency only. ## Notes and guides (content pipeline) From 5ff41bf2ba71411627528e0a651f8bb1d553cde2 Mon Sep 17 00:00:00 2001 From: Satyam Yadav <114805086+Coding-Professional@users.noreply.github.com> Date: Fri, 30 Oct 2026 20:12:34 +0530 Subject: [PATCH 2/4] ci: use supported Node 24 for verification --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 64d0466..c59a330 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,7 +25,7 @@ jobs: - name: Set up Node.js uses: actions/setup-node@v4 with: - node-version: 22 + node-version: 24 cache: npm - name: Install dependencies From fc69a8a18e8194c32f8f84ba0594ac3717c6fe7c Mon Sep 17 00:00:00 2001 From: Satyam Yadav <114805086+Coding-Professional@users.noreply.github.com> Date: Fri, 30 Oct 2026 20:13:45 +0530 Subject: [PATCH 3/4] ci: use Node 24 compatible GitHub actions --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c59a330..4fecfa2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,10 +20,10 @@ jobs: timeout-minutes: 15 steps: - name: Check out repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Set up Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v5 with: node-version: 24 cache: npm From 32d480b2719eeab098a8c4f2fa8047a23b21a52c Mon Sep 17 00:00:00 2001 From: Satyam Yadav <114805086+Coding-Professional@users.noreply.github.com> Date: Fri, 30 Oct 2026 20:40:24 +0530 Subject: [PATCH 4/4] docs: improve project README --- README.md | 157 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 100 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 6b51352..b306851 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,75 @@ +
+ +ProCoderJii logo + # ProCoderJii Learning Hub -A learning site for engineering students. It brings together course notes, guides, career -listings and short browser-based practice games in one place. +### A focused learning space for engineering students. + +Browse course resources, learn from practical guides, explore career opportunities, and take a short break with free coding games. + +[Visit the website](https://procoderji.com) · [Report a bug](https://github.com/Coding-Professional/procoderji/issues/new?template=bug_report.yml) · [Request a feature](https://github.com/Coding-Professional/procoderji/issues/new?template=feature_request.yml) + +[![CI](https://github.com/Coding-Professional/procoderji/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Coding-Professional/procoderji/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org/) +[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?logo=typescript)](https://www.typescriptlang.org/) + +
+ +> [!NOTE] +> The course browser is in place, but no course subjects or notes are published yet. Guides and job listings are also awaiting reviewed content. The two games are playable now. See [Current content](#current-content) for details. + +## Contents + +- [About](#about) +- [Features](#features) +- [Current content](#current-content) +- [Getting started](#getting-started) +- [Commands](#commands) +- [Project structure](#project-structure) +- [Contributing](#contributing) +- [Security and privacy](#security-and-privacy) +- [License and attributions](#license-and-attributions) + +## About -> **Current content status:** the course browser is ready, but the notes catalogue has no -> published subjects yet. The sample files under `src/content` are intentionally unregistered. -> Guides and job listings are also empty until reviewed content is added. +ProCoderJii is a learning hub for engineering students. The project brings course material, practical learning guides, career listings, and small browser games together in one Next.js website. It is built to make useful, reviewed resources easier to browse and to give contributors a clear path for adding them. -## What is included +The repository is organized for community contributions: start with the guides below, open an issue to discuss a larger change, and submit a pull request when you are ready. -- A Next.js site for browsing course notes by course, branch and semester. -- A content pipeline that validates Markdown notes and keeps unsafe HTML out of published pages. -- Two free games at `/games`: Pattern Sprint and Digit Recall. They need no account and do not - save scores between visits. -- Optional latest-video cards using the channel's public YouTube feed. -- Hand-curated guides and job listings, shown only when reviewed items are available. +## Features -There are no accounts, database, admin panel, PDF downloads or chatbot. The contact form opens -the visitor's email app; the site does not store contact submissions. +- **Course browser:** organize learning material by course, branch, and semester. +- **Games:** Pattern Sprint and Digit Recall are free to play at [`/games`](https://procoderji.com/games). No login is required and scores are not saved between visits. +- **Guides and jobs:** curated sections for practical guides and career opportunities. Only reviewed entries are shown. +- **Optional video cards:** show recent videos from a public YouTube channel feed when configured. +- **Content validation:** validate Markdown and MDX content and prevent unsafe HTML from being rendered. +- **Responsive interface:** browse the site on desktop and mobile. -The site uses Next.js 16, React 19, TypeScript, Tailwind CSS 4 and MDX. The `private` flag in -`package.json` prevents npm package publishing; it does not set GitHub repository visibility. +There are currently no user accounts, database, admin panel, PDF downloads, or chatbot. The contact form opens the visitor's email app; the site does not store submissions. -## Run locally +## Current content + +| Section | Status | +| --- | --- | +| Course browser | Course, branch, and semester navigation is available; no subjects or notes are published yet. | +| Games | Pattern Sprint and Digit Recall are playable without an account. | +| Guides | No reviewed guides published yet. | +| Jobs | No reviewed listings published yet. | +| Videos | Optional; requires a public YouTube channel ID. | + +Sample files under `src/content` are intentionally not registered as published notes. Please follow the [content guide](docs/content-guide.md) before adding learning material. + +## Getting started ### Requirements -- Node.js 22.18 or newer for the full test suite; Node.js 24 is also supported. -- npm. The repository commits `package-lock.json`, so use `npm ci`. +- Node.js 22.18 or newer for the full test suite (Node.js 24 is used in CI). +- npm. +- Google Chrome for browser tests. Microsoft Edge can be used with `E2E_CHANNEL=msedge`. + +Clone the repository and install its locked dependencies: ```bash git clone https://github.com/Coding-Professional/procoderji.git @@ -36,60 +78,61 @@ npm ci npm run dev ``` -Open . To enable the latest-video section locally, copy `.env.example` -to `.env.local`; its example channel ID is public and no API key is needed. The app also works -without this setting. +Open . The site works without environment variables. To show recent videos locally, copy `.env.example` to `.env.local` and configure the public YouTube channel ID. -## Common commands +### Environment + +| Variable | Required | Purpose | +| --- | --- | --- | +| `YOUTUBE_CHANNEL_ID` | No | Enables the latest-video section using the channel's public feed. | +| `NEXT_PUBLIC_SITE_URL` | No | Overrides the canonical site URL, such as for a staging deployment. | + +See [deployment documentation](docs/deployment.md) for hosting and environment details. Never commit secrets or personal credentials. + +## Commands | Command | Purpose | | --- | --- | -| `npm run dev` | Start the local development server | -| `npm run lint` | Check code style and common mistakes | -| `npm run typecheck` | Run TypeScript checks | -| `npm test` | Run unit and content validation tests | -| `npm run build` | Create the production build | -| `npm run launch-check` | Build and crawl the real site, checking links and SEO metadata | -| `npm run e2e` | Run browser checks in Chrome on desktop and mobile | +| `npm run dev` | Start the local development server. | +| `npm run lint` | Run ESLint. | +| `npm run typecheck` | Check TypeScript types. | +| `npm test` | Run unit and content validation tests. | +| `npm run build` | Create the production build. | +| `npm run launch-check` | Build and crawl the site, checking links and SEO metadata. | +| `npm run e2e` | Run browser checks in Chrome on desktop and mobile. | -The unit tests and browser tests need Node.js 22.18 or newer. Browser tests also need Google -Chrome installed; use `E2E_CHANNEL=msedge` if you have Microsoft Edge instead. The E2E runner -uses temporary synthetic content, refuses to run when `src/data` or `src/content` has local -changes, and restores its fixtures when it exits. +Browser checks use temporary synthetic content and restore their fixtures when they exit. They refuse to run if `src/data` or `src/content` has local changes. The runner and fixtures are documented in [`e2e/run.mjs`](e2e/run.mjs) and the [`e2e/` directory](e2e/). -## Where things live +## Project structure ```text src/app/ Routes and page layouts (Next.js App Router) -src/components/ Shared UI and landing-page sections -src/content/ Markdown and MDX content -src/data/ Course, guide and job catalogues -src/lib/ Catalogues, validation, rendering, SEO and game logic -docs/ Architecture, content, security and deployment guides -e2e/ Browser tests, test fixtures and production crawl checks -.github/ CI, issue forms and pull-request templates -.agents/ Optional SEO and UI/UX instructions for coding agents -.claude/ Pointers to the canonical agent skill copies +src/components/ Shared UI and page sections +src/content/ Markdown and MDX learning content +src/data/ Course, guide, and job catalogues +src/lib/ Content validation, rendering, SEO, and game logic +e2e/ Browser tests, fixtures, and production crawl checks +docs/ Architecture, content, security, and deployment guides +.github/ CI workflow, issue forms, and pull-request template +.agents/ Optional coding-agent instructions +.claude/ Pointers to canonical agent-tool documentation seo/ Site-specific search and editorial planning notes ``` -Read [the architecture guide](docs/architecture.md) for how routes, data and content fit -together. To publish notes, see [the content guide](docs/content-guide.md). +For the system overview, read [Architecture](docs/architecture.md). To add or update published notes, read the [Content guide](docs/content-guide.md). ## Contributing -Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), follow the -[Code of Conduct](CODE_OF_CONDUCT.md), and use the issue forms for bugs or ideas. Please submit -original learning content or link to official sources; do not copy notes, job descriptions, -papers or images without permission. +Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. For larger changes, open an issue first so the scope can be discussed. Bug reports and feature ideas can use the repository's issue forms. + +Contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md). Submit original learning content or link to official sources; do not copy notes, job descriptions, papers, or images without permission. + +## Security and privacy -For security issues, see [SECURITY.md](SECURITY.md). Deployment and environment configuration -are documented in [docs/deployment.md](docs/deployment.md). +Please report vulnerabilities using the private reporting instructions in [SECURITY.md](SECURITY.md). The site's data handling is described in its [privacy policy](https://procoderji.com/privacy). For local setup and deployment, see [docs/deployment.md](docs/deployment.md). -The optional coding-agent tools and their upstream notices are explained in -[docs/agent-tools.md](docs/agent-tools.md) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). +## License and attributions -## License +The project is available under the [MIT License](LICENSE). Optional coding-agent tools and their upstream license notices are documented in [docs/agent-tools.md](docs/agent-tools.md) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). -The project is licensed under the [MIT License](LICENSE). Vendored agent tools retain their -separate upstream notices; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). +The `private` setting in `package.json` prevents publishing this app as an npm package; it does not control GitHub repository visibility.