diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..6d1301d --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# Route review requests to the existing project maintainer. +* @procoder-ji diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 5608275..d2370bd 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -5,7 +5,11 @@ labels: [bug] body: - type: markdown attributes: - value: Before submitting, check whether this problem has already been reported. + value: | + Before submitting, check whether this problem has already been reported. + For setup questions, use Discussions. Report vulnerabilities privately through + [SECURITY.md](https://github.com/procoderji-com/procoderji/blob/main/SECURITY.md), + and remove credentials or personal data from logs and screenshots. - type: textarea id: summary attributes: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 3ba13e0..e7eb66b 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1 +1,11 @@ blank_issues_enabled: false +contact_links: + - name: Questions and setup help + url: https://github.com/procoderji-com/procoderji/discussions + about: Ask how to use the project or discuss a contribution before opening a bug report. + - name: Report a security vulnerability privately + url: https://github.com/procoderji-com/procoderji/blob/main/SECURITY.md + about: Follow the security policy instead of publishing an unpatched vulnerability in an issue. + - name: Report a conduct concern + url: https://github.com/procoderji-com/procoderji/blob/main/CODE_OF_CONDUCT.md#report-a-concern + about: Use the private reporting channel in the Code of Conduct. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 5683db8..bebc1c4 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -3,6 +3,12 @@ description: Suggest an improvement for students or contributors. title: "feature: " labels: [enhancement] body: + - type: markdown + attributes: + value: | + Check the roadmap, existing issues and open pull requests first. Describe the student + problem and the smallest useful outcome. Small bug fixes or documentation corrections + can go straight to a pull request without a separate feature request. - type: textarea id: problem attributes: diff --git a/.github/dependabot.yml b/.github/dependabot.yml index cb99408..e6c500f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -11,6 +11,10 @@ updates: # Major updates keep their own pull requests so breaking changes are reviewed # one at a time. groups: + npm-security-updates: + applies-to: security-updates + patterns: + - "*" production-dependencies: dependency-type: production update-types: @@ -33,6 +37,24 @@ updates: - dependency-name: "@types/node" update-types: - version-update:semver-major + - package-ecosystem: nuget + # Dependabot expands ProCoderJi.slnx here, covering the API and test projects + # together so shared .NET packages can move in one reviewed pull request. + directory: /backend + schedule: + interval: monthly + open-pull-requests-limit: 5 + groups: + nuget-security-updates: + applies-to: security-updates + patterns: + - "*" + nuget-dependencies: + patterns: + - "*" + update-types: + - minor + - patch - package-ecosystem: github-actions directory: / schedule: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ab05ca9..7fbeb1a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,15 +1,14 @@ ## 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/backend-containers.yml b/.github/workflows/backend-containers.yml index 2c7b703..6433440 100644 --- a/.github/workflows/backend-containers.yml +++ b/.github/workflows/backend-containers.yml @@ -71,9 +71,9 @@ jobs: --health-interval 5s --health-timeout 5s --health-retries 30 steps: - name: Check out repository - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - name: Set up .NET - uses: actions/setup-dotnet@v6 + uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6 with: dotnet-version: 10.0.x - name: Restore locked backend dependencies diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bbeebd7..63e4dbb 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@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - name: Set up Node.js - uses: actions/setup-node@v7 + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7 with: node-version: 24 cache: npm @@ -49,16 +49,16 @@ jobs: timeout-minutes: 30 steps: - name: Check out repository - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - name: Set up Node.js - uses: actions/setup-node@v7 + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7 with: node-version: 24 cache: npm - name: Set up .NET for browser checks - uses: actions/setup-dotnet@v6 + uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6 with: dotnet-version: 10.0.x @@ -75,7 +75,7 @@ jobs: - name: Upload browser failure screenshots if: failure() - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7 with: name: browser-screenshots-${{ github.run_attempt }} path: e2e/.out/*.png @@ -104,10 +104,10 @@ jobs: --health-retries 5 steps: - name: Check out repository - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - name: Set up .NET - uses: actions/setup-dotnet@v6 + uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6 with: dotnet-version: 10.0.x diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 0000000..c205071 --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,31 @@ +name: Dependency review + +on: + pull_request: + +permissions: + contents: read + +concurrency: + group: dependency-review-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + dependency-review: + name: Dependency review + runs-on: ubuntu-24.04 + timeout-minutes: 5 + steps: + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + persist-credentials: false + + # Compare dependency metadata without installing or executing PR code. + - name: Review dependency changes + uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5 + with: + fail-on-severity: high + fail-on-scopes: runtime, development, unknown + license-check: false + show-openssf-scorecard: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69f4c50..dc5a1a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,10 @@ Help ProCoderJii become a useful learning and placement-practice platform for students. Code, documentation, accessibility improvements, original questions, and clear bug reports are welcome. +You can open a pull request for a focused bug fix, documentation correction, test improvement, +or other work within an agreed issue without asking the owner for permission first. Use +[Support](SUPPORT.md) when you need help choosing the right place for a question or report. + ## Find a useful change - Read the [project overview](README.md) and [documentation index](docs/README.md). @@ -13,7 +17,7 @@ documentation, accessibility improvements, original questions, and clear bug rep are larger. - Check existing [issues](https://github.com/procoderji-com/procoderji/issues) and [pull requests](https://github.com/procoderji-com/procoderji/pulls) before starting. -- Discuss larger features, paid features, data collection, or dependency changes in an issue first. +- Discuss larger features, paid features, data collection, or new runtime dependencies in an issue first. Include the student problem and the smallest useful outcome. - Use the practice-question issue form to propose a new exercise. Include the answer, explanation, audience, and authorship or source permission. @@ -22,6 +26,8 @@ documentation, accessibility improvements, original questions, and clear bug rep An issue being open does not reserve it for anyone. Leave a short comment when you start work so contributors can coordinate. Ask for clarification when an acceptance criterion is unclear. +Small fixes do not need a separate issue. Labels help maintainers organise work; contributors do +not need to add labels or request a label before submitting an issue or pull request. ## Set up your fork @@ -66,8 +72,11 @@ branches. Do not force-push over work you have not checked. - Keep a pull request about one student problem or contributor improvement. - Use TypeScript and the existing UI patterns. Keep practice rules and scoring independent of React, storage, authentication, and payment providers. -- Put new practice-domain work under `src/features/practice/`; read the +- Put question-practice domain work under `src/features/practice/`; read the [boundary decision](docs/decisions/0001-student-product-boundaries.md) before adding adapters. +- Follow the [games plan](https://github.com/procoderji-com/procoderji/issues/24) and + [shared-game foundation](https://github.com/procoderji-com/procoderji/issues/58) for new games. + Keep game-result formats separate from the existing multiple-choice progress contract. - Add original questions to `shared/practice/questions.json`, the canonical bank consumed by both runtimes. Keep the TypeScript and .NET validation behavior consistent when its shape changes. - Put authentication, account persistence, and future server-owned capabilities under @@ -89,23 +98,19 @@ payment or account requirements need an agreed scope and a documented data flow. Run the checks relevant to your change; the commands are explained in [Development](docs/development.md#checks). -```bash -npm run lint -npm run typecheck -npm test -npm run build -``` - -For backend or shared-question changes, also run: +| Change | Relevant checks | +| --- | --- | +| Documentation only | Review wording, commands and links; runtime tests are unnecessary when behavior is unchanged. | +| Frontend code | `npm run lint`, `npm run typecheck`, `npm test`, and `npm run build`. | +| Backend code | `dotnet test backend/ProCoderJi.slnx --configuration Release`; persistence changes also need the affected database contracts described in the backend guide. | +| Shared questions or portfolio validation rules | Frontend and backend tests, because both runtimes consume the contract. | +| Routes, metadata, or published learning content | `npm run launch-check`, plus the relevant code or content tests. | +| Browser interactions | `npm run e2e` with Chrome or Edge installed, plus the relevant code checks. | -```bash -dotnet test backend/ProCoderJi.slnx --configuration Release -``` - -For routes, links, or metadata, also run `npm run launch-check`. For browser interactions, run -`npm run e2e` with Chrome installed. Browser checks temporarily install synthetic content and -refuse to run if `src/data` or `src/content` has local changes. For content-only changes, use -`npm test` and `npm run launch-check` instead. +Browser checks temporarily install synthetic content and refuse to run if `src/data` or +`src/content` has local changes. Content authors should use `npm test` and +`npm run launch-check` while editing those files. List the checks you actually ran and explain +any that could not run; maintainers and CI complete the remaining validation. ## Submit the pull request @@ -116,9 +121,14 @@ git push -u origin ``` Open a pull request from your fork branch to `procoderji-com/procoderji:main`. Fill in the -template, link the related issue, explain the resulting behavior, and list the checks you ran. +template, link a related issue when one exists, explain the resulting behavior, and list the +checks you ran. Include screenshots for visible UI changes and sources or permissions for learning content. Respond to review feedback and keep the branch up to date when needed. Maintainers review student value, correctness, accessibility, and maintenance cost before merging. A proposed feature may need a smaller scope or further discussion. + +The [maintainer guide](docs/maintainer-guide.md) explains routine review, labels, dependency +updates, and decisions that need the project owner's input. Existing owner decisions remain +valid; implementing their agreed scope does not need repeated permission. diff --git a/README.md b/README.md index a719319..81a9784 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,11 @@ Questions are original learning exercises. They are independent of employer asse not predict or guarantee hiring outcomes. The first question bank is intentionally small so it can be reviewed and improved before expanding. +The expanded [placement-game catalogue](https://github.com/procoderji-com/procoderji/issues/24) +and [student portfolios](https://github.com/procoderji-com/procoderji/issues/40) are tracked as +separate work. Check those issues for delivery status; the table above describes the current +student experience. + ## Progress and optional accounts Anonymous practice saves the latest **100 completed attempts** in the current browser. The @@ -68,8 +73,8 @@ each student's own history using PostgreSQL, SQL Server, MongoDB, or local-devel See [Backend setup](backend/README.md) and [Docker setup](docs/containers.md) for local persistence, Google credentials, and production integration checks. -The hosted product uses [Neon PostgreSQL](docs/neon.md), with separate runtime and migration -connections. +[Neon PostgreSQL](docs/neon.md) is the selected hosted database, with separate runtime and +migration connections. The guide covers configuration and production verification. The free practice flow works without provider credentials. Paid plans, payment processing, and commercial account entitlements require separate product and provider decisions; this repository @@ -137,6 +142,8 @@ troubleshooting, [backend guide](backend/README.md) for accounts, and | Lint, typecheck, tests and build | TypeScript, code quality, domain/store tests, and the production build. | | Browser and SEO checks | Desktop/mobile flows, a real .NET process and frontend proxy, the Google sign-in challenge, and a crawl of links/metadata. | | Backend build and tests | The .NET solution build and tests for backend rules and access behavior. | +| Database contracts and container smoke | PostgreSQL, SQL Server and MongoDB contracts, Compose configuration, and the packaged API image. | +| Dependency review | Pull-request dependency changes checked for newly introduced high or critical vulnerabilities. | These jobs need no Google credentials or other external secrets. Browser screenshots are retained for seven days when the site-quality job fails. A deployed Google sign-in flow still @@ -154,12 +161,14 @@ src/app/ Next.js routes, metadata, and backend-for-frontend API src/features/practice/ Pure practice rules, question-bank adapter, and practice UI src/features/progress/ Validated attempt records and browser progress storage src/features/account/ Optional account-provider clients and controls +src/features/portfolio/ Shared-rule validation for portfolio fields and usernames src/components/ Shared UI and landing-page sections src/content/ Markdown and MDX learning content src/data/ Course, guide, and job catalogues src/lib/ Existing content, rendering, SEO, and game helpers -backend/ ASP.NET Core 10 API, EF persistence, and backend tests +backend/ ASP.NET Core 10 API, persistence adapters, and backend tests shared/practice/ Canonical question JSON used by TypeScript and .NET +shared/portfolio/ Portfolio validation rules and cross-runtime test fixtures e2e/ Browser checks, fixtures, and production crawl docs/ Development, architecture, content, and decision guides .github/ CI, Dependabot, issue forms, and pull-request template @@ -174,6 +183,8 @@ for the boundaries between learning rules, UI, storage, and providers. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [documentation index](docs/README.md). Check open issues before starting a larger feature and describe the student problem it solves. Contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md). +For setup questions, bug reports and private concerns, follow [Support](SUPPORT.md). +The [maintainer guide](docs/maintainer-guide.md) explains triage, review and dependency updates. | Contribution | Start here | | --- | --- | @@ -182,6 +193,7 @@ Contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md). | Saved progress behavior | [Progress feature](src/features/progress/) and its model/store tests. | | Student interface and accessibility | [Practice views](src/features/practice/client/) and shared components. | | Optional accounts, synchronization, or persistence | [Backend setup](backend/README.md), [account feature](src/features/account/), and the Next.js `/api/platform/*` proxy. | +| Portfolio field and username validation | [Shared rules](shared/portfolio/README.md) and the [portfolio roadmap](https://github.com/procoderji-com/procoderji/issues/40). | | Original notes, guides, and listings | [Content guide](docs/content-guide.md). | | Setup and contributor guidance | `docs/` and the [contribution guide](CONTRIBUTING.md). | diff --git a/SECURITY.md b/SECURITY.md index 939b20e..6297c55 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,12 +7,14 @@ 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. +Do not open a public issue for an unpatched vulnerability. Use GitHub's +[private vulnerability report](https://github.com/procoderji-com/procoderji/security/advisories/new) +to contact the maintainers. If you cannot use GitHub reporting, email **procoderji@gmail.com**. +Include the affected route or component, the impact, and steps to reproduce. Do not include real +user data or secrets in the report. + +Maintainers investigate reports and coordinate fixes and disclosure with the reporter. Response +times depend on availability. There is no bug bounty program at this time. ## Dependency checks diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..a113667 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,26 @@ +# Support + +Start with the [README](README.md), [development guide](docs/development.md) and +[backend setup](backend/README.md). Guest practice runs without production credentials or a +backend, so include whether a problem affects guest practice, local accounts or a deployed service. + +| You need to... | Where to go | +| --- | --- | +| Ask a setup or usage question, or discuss an approach | [GitHub Discussions](https://github.com/procoderji-com/procoderji/discussions) | +| Report a reproducible bug | [Bug report](https://github.com/procoderji-com/procoderji/issues/new?template=bug_report.yml) | +| Suggest a feature | [Feature request](https://github.com/procoderji-com/procoderji/issues/new?template=feature_request.yml), after checking the [roadmap](https://github.com/procoderji-com/procoderji/issues/22) | +| Propose an original practice question | [Question proposal](https://github.com/procoderji-com/procoderji/issues/new?template=practice_question.yml) | +| Correct a question, explanation or published note | Open a bug report with the page/question ID, the correction and its reasoning, or submit a focused pull request | +| Report a vulnerability | Follow [SECURITY.md](SECURITY.md) privately | +| Report harassment or another conduct concern | Follow the private channel in the [Code of Conduct](CODE_OF_CONDUCT.md#report-a-concern) | + +Search existing issues and discussions before opening another thread. Describe the page or +command, expected behavior, actual behavior, and relevant runtime/browser version. A small +reproduction is more useful than an entire project or a screenshot without context. + +Remove passwords, tokens, connection strings and private student information from public logs, +screenshots and examples. Do not use a public issue for account-specific personal data. +For a private account or data concern, use the contact details in the +[privacy policy](https://procoderji.com/privacy). + +Community help depends on maintainer and contributor availability. diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index a705be4..ed624bc 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -1,8 +1,24 @@ # 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. +The UI/UX Pro Max and SEO Audit files listed below are vendored development tools. They are not +part of the website bundle. Their upstream MIT notices are reproduced here. + +## Package dependencies + +The project's MIT license applies to its original source. Installed dependencies retain their +own licenses and notices; this file is not a complete inventory of every deployment artifact. +Examples in the current lockfile include: + +| Package family | Declared terms and upstream reference | +| --- | --- | +| `sharp` and optional `@img/sharp-*` native/WebAssembly packages | Apache-2.0, LGPL-3.0-or-later and, for the WebAssembly package, MIT components. See [platform package metadata](https://github.com/lovell/sharp/blob/main/npm/win32-x64/package.json), [libvips licensing](https://github.com/lovell/sharp-libvips#licences) and its [component notices](https://github.com/lovell/sharp-libvips/blob/main/THIRD-PARTY-NOTICES.md). | +| `next-mdx-remote` | [MPL-2.0](https://github.com/hashicorp/next-mdx-remote/blob/main/LICENSE). | +| `caniuse-lite` | [CC-BY-4.0](https://github.com/browserslist/caniuse-lite/blob/main/LICENSE). | + +Optional platform packages are alternatives; a lockfile entry does not mean every architecture +is distributed. Preserve applicable package licenses and component notices when preparing a +frontend archive or image, and inspect that actual artifact against the upstream terms. The +backend-only container does not bundle the Next.js image-processing dependencies. ## UI/UX Pro Max diff --git a/docs/README.md b/docs/README.md index bb354e0..592368c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,7 +10,10 @@ synchronization is a separate capability; paid billing is future work. | --- | --- | | Understand the product and current content | [Project README](../README.md) | | Review student value, scaling, and future monetization | [Product roadmap](product-roadmap.md) | +| Review repository readiness and remaining owner decisions | [Repository audit](repository-audit.md) | | Make your first contribution | [Contributing](../CONTRIBUTING.md) | +| Ask a question or choose a reporting channel | [Support](../SUPPORT.md) | +| Triage issues, review changes, or handle dependency updates | [Maintainer guide](maintainer-guide.md) | | Run the app and choose checks | [Development](development.md) | | Understand routes, content, and feature boundaries | [Architecture](architecture.md) | | Add original notes, guides, or career listings | [Content guide](content-guide.md) | diff --git a/docs/containers.md b/docs/containers.md index 048666d..a5761a5 100644 --- a/docs/containers.md +++ b/docs/containers.md @@ -10,8 +10,8 @@ remains available for local development without Docker. ## API and database are separate containers -The hosted product uses [Neon PostgreSQL](neon.md). Its dedicated `compose.neon.yml` override -uses a direct connection for migrations and a pooled connection for the API. +[Neon PostgreSQL](neon.md) is the selected hosted database. Its dedicated `compose.neon.yml` +override uses a direct connection for migrations and a pooled connection for the API. On a development machine or a VPS, Docker Compose runs the API and the selected database on the same Docker network. The database has its own container and a named volume. Replacing the API diff --git a/docs/deployment.md b/docs/deployment.md index 480cde1..267d779 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,146 +1,191 @@ # Deployment and launch guide -Everything in this file is a **manual step for the site owner**. The code never changes DNS or -Vercel settings, and nothing here has been done for you. State of the domains was checked -read-only on 2026-10-14. - -## Frontend and account service - -The selected hosted database is **Neon PostgreSQL**. Follow the [Neon setup](neon.md) for pooled -runtime connections, direct migration connections, and backend environment variables. - -For a container image and local/VPS stacks with PostgreSQL, SQL Server or MongoDB, follow -[Container setup](containers.md). Vercel containers still need an externally hosted database. - -Deploy the Next.js frontend with Node 24. Guest practice works on its own. To enable Google -accounts, deploy the [.NET 10 backend](../backend/README.md), run its database migrations, -and set the frontend's server-only `DOTNET_API_URL` to the reachable backend origin. Use -PostgreSQL or durable storage for account data; an ephemeral serverless filesystem is not a -production SQLite volume. Data Protection keys persist in the account database and must be -protected along with it. - -Set the backend's `PublicOrigin` to the exact HTTPS frontend origin and register -`/api/platform/signin-google` in the Google OAuth client. Google secrets -belong in the backend host's secret store. Verify Google consent, callback, cookies, progress -sync, export, and deletion in the configured deployment before opening accounts to students. -Razorpay/Paytm checkout is planned; this release does not accept payments. - -The DNS observations below are dated owner notes. Recheck them before changing a deployment. - -## 1. Environment variables +The Next.js frontend and the optional ASP.NET Core account service deploy separately. Contributors +can prepare and test changes locally; an operator with authorised hosting-project access completes +production configuration and rollout. + +## Current production observation + +Read-only checks on **2026-11-10** found: + +| Check | Observed result | +| --- | --- | +| `https://procoderji.com/` and `/about` | HTTP 200; the live About page still used the older Notes branding. | +| `/robots.txt` and `/sitemap.xml` | HTTP 200; the live sitemap contained 10 URLs. | +| `/practice`, `/learn`, and `/api/platform/auth/session` | HTTP 404, although these routes are implemented on the repository's `main` branch. | +| GitHub deployment history | The latest recorded Production deployment was dated 2026-11-02. | + +These observations establish a difference between the repository and the live site. The deployment +cause is unconfirmed: inspect the actual Vercel project's connected repository, build logs, source +commit and production assignment. GitHub deployment records alone do not establish the state of +every Vercel deployment. + +[Issue #74](https://github.com/procoderji-com/procoderji/issues/74) tracks restoring the current +frontend to production. Resolving the hosting configuration requires access to the authorised +project. Passing repository CI verifies the tested commit; verify the deployed commit and routes +separately after rollout. + +## Frontend project and Git integration + +Check the existing hosting project after the repository ownership transfer: + +| Setting | Expected configuration | +| --- | --- | +| Connected repository | `procoderji-com/procoderji` | +| Production branch | `main` | +| Root directory | Repository root; leave the field unset if that represents the root. | +| Framework | Next.js | +| Node.js | 24.x, matching `package.json`, `.nvmrc` and CI. | +| Install command | `npm ci` | +| Build command | `npm run build` | +| Output directory | Next.js framework default. | + +Use [Vercel's Git integration guide](https://vercel.com/docs/git) to inspect the connected +repository and production branch. Confirm that the GitHub integration can access the transferred +organisation repository and that the desired commit appears in deployment history. A missing +deployment, a failed build and a successful deployment assigned to the wrong domain require +different fixes. + +Check the build's source commit and logs before redeploying. Review the preview for the intended +commit, follow the project's production deployment procedure, and confirm which deployment the +production domain serves. [Vercel's Node.js documentation](https://vercel.com/docs/functions/runtimes/node-js/node-js-versions) +explains the project setting and `package.json` version override. + +## Environment variables + +Set frontend values in the hosting project's environment settings, separately for Production and +Preview. Google credentials and database connection strings belong on the backend. + +| Name | Value | Environments | Purpose | +| --- | --- | --- | --- | +| `YOUTUBE_CHANNEL_ID` | `UC74q2pzSGuoaikYwnavcGMg` | Production, and Preview when desired | Public ID for @Pro_coder_ji; enables the latest-video cards without an API key. Leave unset to hide them. | +| `NEXT_PUBLIC_SITE_URL` | Unset for the production default | Override only when needed, such as staging | The canonical origin defaults to `https://procoderji.com`. This public value is compiled into the build. | +| `DOTNET_API_URL` | Reachable backend origin | Environments with account sync enabled | Server-only; leave unset for guest-only practice. Local example: `http://localhost:5100`. | -Set these in Vercel: **Project -> Settings -> Environment Variables**. Google credentials are configured separately on the backend. +Create a new deployment after changing environment configuration, then verify the intended +environment's result. For local development, copy `.env.example` to the ignored `.env.local`. +The Privacy page discloses YouTube thumbnail requests when the channel feed is enabled. -| Name | Value | Environments | Notes | -| --- | --- | --- | --- | -| `YOUTUBE_CHANNEL_ID` | `UC74q2pzSGuoaikYwnavcGMg` | Production (and Preview if you want videos there) | Enables the "Latest videos" section. Verified against the channel feed for @Pro_coder_ji. Leave it unset to hide the section. | -| `NEXT_PUBLIC_SITE_URL` | *(do not set)* | - | The site already defaults to `https://procoderji.com`. Only set it to override, e.g. on a staging project. | -| `DOTNET_API_URL` | Your backend origin | Environments with account sync enabled | Server-only. Leave unset for guest-only practice. Local example: `http://localhost:5100`. | +Keep previews separate from production account data and secrets. A staging canonical override +does not itself provide deployment protection or prevent indexing; inspect the preview's access +and robots settings. -Steps: +## Optional account service and database -1. Open the project in Vercel, then Settings, then Environment Variables. -2. Add `YOUTUBE_CHANNEL_ID` with the value above, tick **Production** (optionally **Preview**), save. -3. **Redeploy** (Deployments, the latest one, the menu, Redeploy). Values are read at build time, so - a change only takes effect after a new deployment. -4. For local development copy `.env.example` to `.env.local` (that file is git-ignored). +**Neon PostgreSQL is the selected hosted database.** Follow [Neon setup](neon.md) for pooled +runtime connections, direct migration connections and backend settings. Selection and setup +instructions do not establish that a live Neon project or account service is configured. -The Privacy page mentions the YouTube thumbnail requests automatically while the variable is set. +Deploy the [.NET 10 backend](../backend/README.md) independently and run its migration/provisioning +command before enabling account traffic. [Container setup](containers.md) covers the API image and +database options. A frontend deployment does not start the .NET service. -## 2. Make `https://procoderji.com` the primary domain (apex), redirect `www` to it +Use PostgreSQL or other durable configured storage for account data. SQLite needs a durable +volume; an ephemeral serverless filesystem cannot preserve accounts. Protect the database's +Data Protection keys along with student data and backups. -**Why:** today `https://procoderji.com` answers with a **308 redirect to `https://www.procoderji.com`**, -but the site declares `https://procoderji.com` as its canonical address (canonical tags, Open Graph -URLs, sitemap, robots). Search engines treat a canonical that redirects elsewhere as a conflicting -signal. The two must agree. +Set the backend's `PublicOrigin` to the exact HTTPS frontend origin and register +`/api/platform/signin-google` in the Google OAuth client. Keep Google secrets in +the backend host's secret store. Verify actual consent, callback, cookies, progress sync, export +and deletion in the configured deployment before opening accounts to students. Guest practice +remains usable without those credentials. -**No DNS change is needed.** Both hosts already resolve to Vercel (checked 2026-10-14: the apex -`A` record points at Vercel, and `www` is a `CNAME` to a `vercel-dns` host). Only change DNS if the -Vercel Domains page itself shows "Invalid Configuration" for a domain, and then use exactly the -values Vercel displays there. +## Domains and canonical URLs -Steps (button names can vary slightly between Vercel UI versions): +The code's default canonical origin is `https://procoderji.com`. The apex returned HTTP 200 on +2026-11-10; the older observation that it redirected to `www` is no longer current. -1. Vercel dashboard -> your team -> the **ProCoderJii Notes** project -> **Settings -> Domains**. -2. Find **`procoderji.com`**. Click **Edit**. Make sure it is set to serve the **Production** deployment - directly and is **not** set to "Redirect to another domain". Save. -3. Find **`www.procoderji.com`**. Click **Edit**. Choose **Redirect to Another Domain**, enter - **`procoderji.com`**, and pick **308 Permanent Redirect**. Save. -4. If the page offers "Set as primary" for `procoderji.com`, choose it. -5. Wait about a minute, then verify (see below). +Inspect the live redirect chain and hosting Domains configuration before changing DNS or aliases. +The intended production setup serves the canonical HTTPS origin directly and redirects alternate +hosts to that origin while preserving paths. Compare the final served host with canonical tags, +Open Graph URLs, robots and sitemap entries. -**Verify** (run in a terminal; expected results shown): +Read-only checks: ```bash -curl -sI https://procoderji.com/ # expect: HTTP/2 200 (no Location header) -curl -sI https://www.procoderji.com/ # expect: HTTP/2 308 Location: https://procoderji.com/ -curl -sI http://procoderji.com/ # expect: 308 to https://procoderji.com/ -curl -s https://procoderji.com/robots.txt # expect: ... Sitemap: https://procoderji.com/sitemap.xml +curl -sSI https://procoderji.com/ +curl -sSI https://www.procoderji.com/ +curl -sSI http://procoderji.com/ +curl -sS https://procoderji.com/robots.txt +curl -sS https://procoderji.com/sitemap.xml ``` -**Alternative (not recommended):** keep `www` as primary instead. Then set -`NEXT_PUBLIC_SITE_URL=https://www.procoderji.com` in Vercel, redeploy, and update the apex to redirect -to `www`. The default in the code, the tests and the docs all assume the apex. - -## 3. Other domains +In Windows PowerShell, use `curl.exe` when `curl` is an alias for another command. Investigate +unexpected responses before changing settings. Apply DNS values only when the authorised hosting +project identifies a configuration problem and supplies the required records. Other domains and +separate portfolio sites need their own verified scope. -- **`procoderji.xyz`** (checked 2026-10-14): its DNS points at Vercel, but HTTPS fails (no valid - certificate), so it does not serve a working site. The code no longer links to it. Choose one: - leave it as it is; or in Vercel add it to this project and set it to redirect to - `procoderji.com` (Vercel will tell you if DNS verification is needed); or remove its DNS records. -- **`satyam.procoderji.com`** is a separate portfolio site. Nothing in this project touches it. +## Checks before rollout -## 4. Before you merge and deploy - -Run these locally; all must pass: +Use the [contribution checks](../CONTRIBUTING.md#check-your-change) and inspect CI for the final +commit. For a frontend release: ```bash npm ci -npm run typecheck && npm run lint && npm test -npm run launch-check # builds the real site and crawls it -npm run e2e # real-Chrome browser tests (needs Chrome installed) -``` - -To also run the latest-videos checks (three cards on phones, six on desktop), set the channel for that -run, for example `YOUTUBE_CHANNEL_ID=UC74q2pzSGuoaikYwnavcGMg npm run e2e` (they need internet access -to YouTube's feed and are reported as skipped otherwise). - -**Decide before launch: the dashboard background image.** `public/bg.jpg` (9.8 MB, used faintly behind -the dashboard) is a stock illustration from Rawpixel Ltd. ("Graduating in the time of covid-19 -background", 2020). Its embedded metadata marks it copyright-protected and links -`rawpixel.com/services/licenses`; nothing in the repository shows a licence for it. Unless you can show a -Rawpixel licence that covers this use, replace it (for example with a plain CSS background, which also -removes 9.8 MB of page weight) or delete it, and note that it already exists in the repository history. - -Then merge the branch via a pull request and let Vercel build it. Review the preview deployment -first (Vercel normally keeps preview URLs out of search results, but confirm in your project settings). - -## 5. Complete the legal pages (they are Drafts until you do) - -Open `src/lib/legal.ts` and set the two remaining fields: - -```ts -courtsLocation: "City, State", // whose courts have jurisdiction, e.g. where you live -effectiveDate: "YYYY-MM-DD", // the date you publish the pages +npm run lint +npm run typecheck +npm test +npm run launch-check +npm run e2e ``` -Both are required. While either is missing every legal page shows a "Draft" banner, is `noindex` -and stays out of the sitemap; once both are set the banner disappears, the pages become indexable -and are added to the sitemap automatically. Have a qualified adviser review the texts first. - -## 6. After the first production deploy - -1. Confirm the four `curl` checks in section 2 and open `https://procoderji.com/` in a private window. -2. In Google Search Console add the property (a **Domain** property verified with a DNS TXT record - covers apex, `www` and `https`), then submit `https://procoderji.com/sitemap.xml`. -3. Check the social preview of the home page and one inner page with a share-preview tool (the card - should show the ProCoderJii badge from `/og.png`). -4. Check the "Latest videos" section shows recent uploads from the channel. -5. Empty sections (`/guides`, `/jobs`, semesters without notes) stay `noindex` and unlinked until you - add genuine content; nothing else is required for that. - -## 7. Hosting plan - -The free Vercel Hobby plan is, as far as I know, limited to non-commercial use. A site that carries -advertising is commercial, so check Vercel's current terms and plans before you apply for AdSense. -This repository does not change or choose a plan. +`launch-check` builds and crawls the real content. Browser checks use synthetic fixtures and +refuse to run when `src/data` or `src/content` has local changes. Use `E2E_DOTNET=1` for the +full-stack checks described in [Development](development.md#browser-checks). Backend or shared-rule +changes also need their .NET tests and relevant database contracts. + +Latest-video browser checks require internet access and +`YOUTUBE_CHANNEL_ID=UC74q2pzSGuoaikYwnavcGMg`; they report a skip when it is unset. Run those checks +when verifying the channel integration. Review the licences and notices for newly added assets +and content as part of the release. + +## Legal metadata and launch decisions + +The required owner-provided fields in `src/lib/legal.ts` are currently populated. Verify their +accuracy with the owner, including the effective/publication date and jurisdiction wording, +instead of replacing them with guessed values or today's date. + +The code checks whether required values are present and whether the date is valid. That check +controls the legal pages' draft/indexing state; it does not constitute review of the wording. +The owner reviews changes to legal text and public-data policy, with qualified advice where +appropriate. See [ADR 0002](decisions/0002-student-portfolios.md) and +[issue #48](https://github.com/procoderji-com/procoderji/issues/48) for the outstanding portfolio +privacy, terms and age decisions. + +Razorpay/Paytm checkout and paid entitlements remain future work. Keep public-portfolio and +monetization launch decisions separate from deploying the current guest practice experience. + +## Verify the deployed release + +Record the production deployment URL, source commit and verification date. Test a private +browser window and a mobile viewport, and check: + +| Route or flow | Expected behavior for the current frontend | +| --- | --- | +| `/`, `/about` | HTTP 200 with the intended release's content and branding. | +| `/practice` and a topic session | HTTP 200; a guest can answer questions and read explanations. | +| `/learn` | HTTP 200; guest progress is visible after a session, and the page remains `noindex`. | +| `/games/pattern-sprint`, `/games/digit-recall` | Both existing games can complete without login. | +| `/api/platform/auth/session` | Session JSON; a guest-only deployment returns HTTP 200 with `configured: false`. | +| `/account` | Optional account controls or an understandable unconfigured state; free practice remains available. | +| `/robots.txt`, `/sitemap.xml` | HTTP 200, correct canonical origin, current public routes and no private workspace/account URLs in the sitemap. | +| Legal pages | Owner-approved details, no unintended placeholders, and indexing consistent with configuration. | + +If accounts are enabled, separately complete the live Google and account-data checks in the +backend guide. Check the latest-video cards when configured and the social preview image +(`/og.png`). Verify internal links and an unknown route's 404 behavior. + +Once the intended release is live, submit the current sitemap through the site's authorised +Google Search Console property. Keep empty content sections out of indexing until reviewed +material is published. Recheck these results after later deployments rather than relying on an +old screenshot or GitHub status. + +## Hosting plan and funding configuration + +Before adding advertising or paid features, check the hosting provider's current plan terms and +limits. Vercel's [Hobby plan documentation](https://vercel.com/docs/plans/hobby) restricts that plan +to personal, non-commercial use. The owner chooses the appropriate plan and approves any new +spending commitment before a monetized rollout. + +The owner is keeping [`.github/FUNDING.yml`](../.github/FUNDING.yml) for future sponsorship links. +Recipients are not configured yet; add only the owner-selected accounts when ready. diff --git a/docs/images/about-desktop.png b/docs/images/about-desktop.png new file mode 100644 index 0000000..db83a67 Binary files /dev/null and b/docs/images/about-desktop.png differ diff --git a/docs/images/about-mobile.png b/docs/images/about-mobile.png new file mode 100644 index 0000000..1e81624 Binary files /dev/null and b/docs/images/about-mobile.png differ diff --git a/docs/maintainer-guide.md b/docs/maintainer-guide.md new file mode 100644 index 0000000..ab5a515 --- /dev/null +++ b/docs/maintainer-guide.md @@ -0,0 +1,117 @@ +# Maintainer guide + +Use this guide with [Contributing](../CONTRIBUTING.md), the [Code of Conduct](../CODE_OF_CONDUCT.md) +and [Security policy](../SECURITY.md). Repository access and the active GitHub branch rules +determine who can merge. + +[CODEOWNERS](../.github/CODEOWNERS) routes review requests to the project account, +[`procoder-ji`](https://github.com/procoder-ji). It does not grant repository access; the active +branch rules determine whether an approval is required. + +## Work that can proceed without another owner decision + +Contributors can investigate and prepare focused fixes, documentation, tests, accessibility +improvements and work within an agreed issue. Maintainers can triage reports, apply labels, +organise existing issues and prepare pull requests. Routine dependency fixes can proceed when +their compatibility and behavior are understood. + +These steps do not need repeated owner permission. Existing decisions, including the .NET +backend and selected Neon PostgreSQL deployment, remain valid. A person implementing that +approved scope should continue through a reviewable change and its relevant checks. + +Use the pull-request workflow for changes to `main`, and satisfy the repository's active review +and status-check rules before merging. Maintainers can merge routine changes within their +authorised scope once the relevant checks and review are complete. Production rollout and +private-credential access follow the separately agreed operating scope. + +## Decisions to take to the owner + +Prepare the proposed change and explain its impact before asking for a decision. Continue +unrelated work while a decision is pending. Owner input is needed for changes such as: + +- Legal wording, licensing terms, public-data policies and the portfolio age requirement. +- New pricing, paid access, payment providers, funding recipients or spending commitments. +- New production credentials, external account enrolment, DNS/domain changes or a production + data migration that affects existing students. +- Repository visibility, access grants, or changes to the intended branch-protection policy. +- Unresolved product boundaries, such as portfolio username changes and the public-page domain. + +Check the existing issue, session instruction or architecture decision first. Do not ask again +for an action already authorised within the same scope. Record durable product/architecture +decisions in an ADR; the open portfolio decisions remain in +[ADR 0002](decisions/0002-student-portfolios.md). + +## Triage issues + +1. Search for an existing issue or pull request, reproduce a bug where possible, and confirm + that a request fits the student product. Link related work instead of duplicating it. +2. Ask for the smallest missing detail that prevents useful work. Keep secrets, private data + and vulnerability reproduction details out of public issues. +3. State a useful scope and observable acceptance criteria. Link dependencies and the relevant + code/docs so contributors can start without guessing. +4. Apply the labels that help. Labels are maintained by the project and are optional for authors; + their absence does not make a report or pull request invalid. + +Use `bug`, `documentation`, `enhancement` and `dependencies` for the type of work, and `games` or +`portfolio` for those feature areas. `help wanted` invites contributions. Use `good first issue` +for a small, self-contained task with clear starting files and checks, rather than an unresolved +architecture or security change. + +An open issue does not reserve the task. A short starting comment and a linked pull request +help people coordinate. When closing an issue, explain the outcome or link the fix; do not +silently close useful reports just because they have been quiet. + +## Review pull requests + +- Confirm the actual problem, final scope and resulting behavior. Check for overlap with open + work and for changes that need a recorded product decision. +- Check correctness, student usefulness, account/data boundaries, accessibility and maintenance + cost. Review original question answers and explanations, not only whether JSON parses. +- Require meaningful tests for changed scoring, validation, persistence and access rules. + Documentation-only edits need accurate wording and working links, not tests that mirror prose. +- Check the relevant frontend/backend/shared-data contracts. Persistence work must pass the + affected provider contracts; browser behavior needs appropriate browser checks. +- Preserve licences and third-party notices. Remove secrets, generated output and unrelated edits. +- Keep the title and description about the final change. A short description is enough for a + simple fix if it explains the outcome and relevant validation. +- Resolve review findings and check the final commit's CI before merging. A green build does + not replace reviewing the actual change. Update the branch when base changes make checks stale. + +Describe human and automated reviews accurately. Request manual review when a change's impact +needs another maintainer's judgement, and follow any review requirement in the active branch rules. + +The database/container workflow runs only when its configured paths change. Keep the required +checks for every pull request aligned with checks that always run; a conditional workflow must +not leave unrelated pull requests waiting for a check that will never be reported. The +pull-request Dependency review check inspects newly introduced high/critical vulnerabilities; +it complements the dependency audits in the security guide. + +## Handle dependency pull requests + +Dependabot branches are normal maintenance work. Review updates by impact rather than by PR +number or the order branches appear: + +1. Assess security fixes first, considering production exposure and the advisory's impact. +2. Review compatible grouped patch/minor updates, checking manifests, lockfiles, peer dependencies + and relevant CI. Review runtime and development changes according to what they affect. +3. Handle major or breaking updates separately, with release notes and a migration plan. Resolve + an existing compatibility issue before merging the dependent major update. + +Merge one overlapping dependency change at a time. Let remaining branches refresh, then recheck +their current diff and CI. Close a superseded update only after confirming that its changes are +already included. Keep security updates visible; fewer routine PRs should not hide an urgent fix. + +Follow [Security notes](security.md) for current known findings. Do not use `npm audit fix --force`, +unrelated downgrades or broad overrides just to obtain a clean summary. New runtime dependencies +need a concrete use and a discussion of their maintenance cost. + +## Publish and operate + +The current security-support target is `main`; no versioned release or long-term support schedule +is promised. Deployment remains an operator step using the [deployment](deployment.md), +[container](containers.md) and [Neon](neon.md) guides. + +Describe merged, locally tested and production-verified behavior accurately. A selected hosting +provider or a passing test does not establish that a live account service has been deployed. +Keep portfolio publishing, paid access and other launch-sensitive capabilities gated until +their documented owner decisions and operating requirements are complete. diff --git a/docs/product-roadmap.md b/docs/product-roadmap.md index b8e4d64..ab089d6 100644 --- a/docs/product-roadmap.md +++ b/docs/product-roadmap.md @@ -4,12 +4,13 @@ ProCoderJii starts with a complete learning loop: choose a placement topic, answ review explanations, and decide what to practise next. Coursework stays available under `/dashboard`; `/learn` is the learner workspace. Track product work in [#22](https://github.com/procoderji-com/procoderji/issues/22). -## Available in this change +## Available now - Four topic sets with 24 original introductory questions and answer explanations. - Self-paced sessions, topic-level progress, and a suggested three-session weekly routine. - Guest progress on the current device, with export and deletion. - Optional Google sign-in and private cloud sync through the ASP.NET Core 10 backend. +- Pattern Sprint and Digit Recall, available free without login. - Separate feature boundaries and contributor instructions for extending questions and product behavior. This is a starter practice bank, not a calibrated placement assessment. Repeated questions count @@ -20,7 +21,8 @@ as practice; accuracy is an aid to learning rather than an employability score. 1. Ask students which placement stages and topics are hardest to prepare for. Observe whether they can complete a session, understand a missed answer, and choose a useful next activity. 2. Expand the reviewed question bank and worked explanations before adding more topic landing pages. -3. Introduce question versions before changing answer keys or retiring IDs used by saved attempts. +3. [Introduce question versions](https://github.com/procoderji-com/procoderji/issues/72) before + changing answer keys or retiring IDs used by saved attempts. 4. Design longer mock sessions, richer review history, and personal study goals from student feedback. 5. Publish original coursework and practical guides through the existing content-review workflow. @@ -28,6 +30,19 @@ Useful measures include session completion, voluntary return practice, explanati and correction reports. Choose a privacy-conscious measurement approach explicitly; this release does not add analytics or track students across sites. +## Tracked feature work + +- [Placement games #24](https://github.com/procoderji-com/procoderji/issues/24) groups the planned + game families, shared session lifecycle, browser history and mixed practice sessions. Build + the common foundation first, then gather student feedback on the first games before expanding. +- [Student portfolios #40](https://github.com/procoderji-com/procoderji/issues/40) tracks the + editor, public pages and supporting backend work. Shared validation rules are merged; the + remaining implementation and launch decisions are recorded in the linked issues and + [ADR 0002](decisions/0002-student-portfolios.md). + +Recheck the linked issues and merged pull requests before updating product copy or enabling +a planned capability. + ## Monetization after value is established Free topic practice should remain a useful standalone experience. Possible paid additions include @@ -40,7 +55,7 @@ support, and accessible cancellation. Paid access must be checked on the server. need verified signatures, idempotent processing, and a durable audit trail. Never grant access from a client-side success redirect or expose provider secrets to the browser. -No checkout, subscription, or paid entitlement is enabled in this change. +No checkout, subscription, or paid entitlement is currently enabled. ## Grow the architecture when a measured need appears diff --git a/docs/repository-audit.md b/docs/repository-audit.md new file mode 100644 index 0000000..49fa26d --- /dev/null +++ b/docs/repository-audit.md @@ -0,0 +1,116 @@ +# Repository audit — 2026-11-10 + +This review covers the canonical `procoderji-com/procoderji` repository: public metadata, +contributor guidance, issue and pull-request workflows, branch rules, CI, dependencies, +source boundaries, content safety and deployment documentation. The starting `main` commit +was `7d20d370269f938ee42058f6b9364b4e0351115e`. + +The existing Next.js frontend, feature modules, shared rules and .NET backend provide useful +contribution boundaries. A monorepo migration, new contributor agreement or mandatory commit +format is not needed for the current project. + +## Findings and changes + +| Finding | Action | +| --- | --- | +| About copy still described a notes-only project; repository metadata included unpublished study notes | Describe implemented practice, explanations, games and optional progress accurately. Refresh GitHub About/topics and the website's About page. | +| README omitted database/container CI and merged portfolio validators | Document the actual feature paths and all CI jobs; keep planned public portfolios separate from shipped behavior. | +| No clear support or maintainer workflow | Add [Support](../SUPPORT.md) and the [maintainer guide](maintainer-guide.md), with issue routing, relevant checks and dependency merge order. | +| Main's active ruleset had an empty required-check list and no PR requirement | Require the PR path and the always-running CI checks, preserving deletion/force-push protection and the existing zero mandatory-review count. | +| Vulnerability alerts, security-update PRs and private reporting were disabled | Enable them; retain existing secret scanning, push protection and read-only workflow defaults. | +| Backend packages had no Dependabot version coverage | Add monthly grouped NuGet maintenance alongside npm and Actions, plus security-update groups. | +| Actions used movable version refs and PR dependency changes had no dedicated check | Pin official actions to verified commits and add read-only Dependency review for newly introduced high/critical advisories. | +| Reviewer routing and branch cleanup were implicit | Route requests to the existing `procoder-ji` maintainer with CODEOWNERS and enable deletion of merged repository branches. | +| Deployment guide retained obsolete domain, asset and legal-completion instructions | Use current observations, add transfer/reconnection checks and distinguish repository validation from a deployed service. | + +The conditional **Database contracts and container smoke** workflow must not be required for +every pull request: it does not run for unrelated paths. The always-running checks are +**Lint, typecheck, tests and build**, **Browser and SEO checks**, **Backend build and tests**, +and the PR-only **Dependency review** check. Add a new required check only after verifying its +actual name and successful execution. + +CODEOWNERS routes requests; it does not establish an independent human review team. Follow +the active GitHub rules and review changes according to their impact. + +## Dependency and source review + +- Production npm audit: **0 known vulnerabilities** on the review date. +- Full npm audit: **9 moderate findings** in the development-only ESLint/TypeScript-ESLint + `minimatch` chain. They are documented in [Security notes](security.md); current compatible + parent ranges do not remove every finding. No blind major override or forced downgrade was applied. +- NuGet API/test projects: **no known vulnerable packages**, including transitive dependencies. +- GitHub reported **0 open secret-scanning alerts**. Existing ignored credential files and + checked-in environment examples retain their roles. +- Inspected account identity, Origin/CSRF checks, progress isolation, backend proxy allowlists, + Markdown rejection and filesystem path boundaries had no blocking finding in this review. + +The MIT copyright notice and vendored-tool notices remain intact. The +[third-party notice guide](../THIRD_PARTY_NOTICES.md) now distinguishes vendored tools from +package licenses, including MPL, LGPL/native-image components and CC-BY data. Concrete frontend +distribution artifacts need their own notice review; a lockfile is not a bundle inventory. +`package.json` stays +`private: true` to prevent accidental npm publication; this does not change the public repository +or its MIT license. `FUNDING.yml` is retained for the owner to fill with funding links later. + +## Engineering follow-ups + +- [#72: question-history compatibility](https://github.com/procoderji-com/procoderji/issues/72): + preserve saved attempts when reviewed questions are corrected or retired. +- [#73: duplicate legacy readers](https://github.com/procoderji-com/procoderji/issues/73): + retire unreachable implementations while preserving `/courses` redirects and active readers. +- [#76: MDX renderer maintenance](https://github.com/procoderji-com/procoderji/issues/76): + assess a maintained rendering path now that the current upstream is archived, preserving + content rejection and sanitization. Archival is not an advisory or evidence of an exploit. +- Existing [games](https://github.com/procoderji-com/procoderji/issues/24) and + [portfolio](https://github.com/procoderji-com/procoderji/issues/40) plans remain separate work. + Portfolio API [PR #71](https://github.com/procoderji-com/procoderji/pull/71) was open during + this review; it is not presented here as a public portfolio launch. + +## Production observations + +On 2026-11-10, HTTPS `/about`, `/robots.txt` and `/sitemap.xml` returned 200. About still had the +old notes-only title, and `/practice`, `/learn` and `/api/platform/auth/session` returned 404, +although those routes exist on canonical main. The latest Production entry recorded by this +repository's GitHub deployments API was dated 2026-11-02. These observations indicate a +deployment gap; they do not establish the precise hosting configuration or running commit. + +[#74](https://github.com/procoderji-com/procoderji/issues/74) records the evidence and the +existing-project reconnection/deployment checks. Completing that work needs authorized access +to the existing hosting project. Repository CI, local screenshots and a selected Neon setup +do not prove a successful production rollout. Search Console indexing and real-user Core Web +Vitals were not available for this review. + +## Work that needs no repeated owner permission + +Within an agreed scope, routine fixes, documentation, tests, accessibility improvements, +issue triage/labels, compatible maintenance, pull-request preparation and routine merges can +proceed through the normal checks and review. Labels are optional for authors. Reuse existing +account, database and product decisions instead of asking for them again. + +Owner decisions remain necessary for new legal/licensing terms, public-portfolio age and data +policies, unresolved username/domain choices, pricing/provider selection, spending commitments, +new private credentials/access grants, and changes to the intended visibility or protection policy. +See [ADR 0002](decisions/0002-student-portfolios.md) and the [maintainer guide](maintainer-guide.md). +An independent conduct-report fallback contact should be appointed by the owner rather than invented. + +## Validation + +Local lint and typecheck passed. Unit tests passed **159 tests**, with **2 Windows symlink +checks skipped**. Full-stack desktop/mobile browser checks reported **0 findings**. The real +production build/link/metadata crawl checked **38 pages** and reported **no problems**. + +Rendered About-page captures are available for [desktop](images/about-desktop.png) and +[mobile](images/about-mobile.png); both have one H1, the canonical `/about` URL and no horizontal +overflow. Owner-provided legal metadata remains unchanged. + +CI also runs backend tests, provider/container contracts when their paths change, and Dependency review. +Workflow YAML, pinned action refs, relative documentation links and the final GitHub settings +are checked separately. Passing these checks describes repository behavior; use the deployment +guide for production verification. + +## Primary references + +- [GitHub community profiles](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories) +- [Dependabot options](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference) +- [Dependency review action](https://github.com/actions/dependency-review-action) +- [Skipped workflows and required checks](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs) diff --git a/docs/security.md b/docs/security.md index 0162691..fea88c7 100644 --- a/docs/security.md +++ b/docs/security.md @@ -15,6 +15,18 @@ To report a vulnerability privately, follow the repository's [security policy](. update rather than forcing a major override or unrelated ESLint downgrade. Audit findings change over time; rerun both commands before a release. - `playwright-core` (browser tests) is a dev dependency only. +- The API and test projects reported **no known vulnerable NuGet packages** on 2026-11-10, + including transitive dependencies. This is an advisory check, not a guarantee against unknown + vulnerabilities. + +Repository security alerts, Dependabot security updates and private vulnerability reporting are +enabled. Version-update PRs are scheduled monthly and grouped; security updates can arrive +between those runs. NuGet maintenance covers the backend solution as well as npm and GitHub +Actions maintenance. + +The pull-request **Dependency review** check blocks newly introduced high/critical dependency +vulnerabilities using GitHub's dependency data. It complements the full audits above; it does +not remove existing advisories or replace review of compatibility and lockfile changes. ## Accounts and saved progress diff --git a/src/app/about/page.tsx b/src/app/about/page.tsx index 1683126..2027a3c 100644 --- a/src/app/about/page.tsx +++ b/src/app/about/page.tsx @@ -1,38 +1,72 @@ +import Link from "next/link"; import { EmailLink, H2, LegalLayout, Operator, P, UL, legalMetadata } from "@/components/legal/legal-layout"; export const metadata = legalMetadata( "About", - "What ProCoderJii Notes is, who runs it and how its content is made.", + "Learn about ProCoderJii, an open-source student platform for placement practice, explanations, free games and saved progress, and how to contribute.", "/about" ); export default function AboutPage() { return ( - +

- ProCoderJii Notes is a study site that goes with the ProCoderJii YouTube channel. It is operated by{" "} - . The aim is to give engineering students clear, unit-wise notes - organised by branch, semester and subject. + ProCoderJii is an open-source learning and campus-placement practice project for students. + It is operated by and grows through reviewed community contributions.

-

Where the project stands

+

Practise and understand your answers

+
    +
  • + Placement practice covers + quantitative aptitude, logical reasoning, verbal ability and programming foundations. + Each session includes correct answers and explanations. +
    • +
  • + Free practice games include + Pattern Sprint for number patterns and Digit Recall for short-term memory. +
    • +
  • + The learner workspace shows + question-practice history, topic progress and a suggested next step. +
    • +
+ +

Free practice and your progress

+

+ Practice is free and works without an account. Question-practice history is saved in this + browser; clearing site data removes it. Optional Google sign-in can synchronize that + history when account services are available. Game scores are shown at the end of a round + and are not yet saved. +

+ +

Learning content in development

- The branch and semester structure is in place, and notes are being added subject by subject. Semesters - that have no published notes yet are marked “Coming soon” and are not listed in search - results. We would rather publish a small amount of good material than a large amount of thin pages. + Course, branch and semester navigation is in place. Reviewed course notes, guides and job + listings are awaiting publication. The current learning exercises are independent practice + for building skills; they do not predict or guarantee a placement result.

-

How content is made

+

How to contribute

+

+ Students and developers can help with original questions, explanations, accessibility, + documentation and code. Visit the{" "} + + GitHub repository and contribution guide + {" "} + to find a focused task and the checks it needs. +

    -
  • Notes are written and reviewed by the ProCoderJii team before they are published.
    • +
  • Learning material is reviewed for correctness and clarity before publication.
  • Where an official syllabus or question paper exists, we link to the university's own page instead of copying it.
  • We do not republish other people's notes, papers or PDFs without permission.

Corrections and requests

- Found a mistake, or want a subject covered? Email . See the Disclaimer for the limits of - what these notes can be relied on for. + Found a mistake, or want a subject covered? Email or open a reproducible issue + in the repository. See the Disclaimer{" "} + for the limits of the learning material.

); diff --git a/src/components/legal/legal-layout.tsx b/src/components/legal/legal-layout.tsx index 3026dff..d08774b 100644 --- a/src/components/legal/legal-layout.tsx +++ b/src/components/legal/legal-layout.tsx @@ -66,10 +66,10 @@ export function LegalLayout({ title, children }: { title: string; children: Reac
- ProCoderJii Notes + ProCoderJii - - Browse notes + + Start practice
diff --git a/src/components/note-body.tsx b/src/components/note-body.tsx index 7543a60..e7cb489 100644 --- a/src/components/note-body.tsx +++ b/src/components/note-body.tsx @@ -2,7 +2,7 @@ import { MDXRemote } from "next-mdx-remote/rsc"; import { mdxComponents } from "@/components/mdx-components"; import { SAFE_MDX_OPTIONS } from "@/lib/mdx-safe"; -/** A note or guide rendered from Markdown: raw HTML/JSX and expressions are removed first. */ +/** A note or guide rendered from Markdown: raw HTML/JSX and expressions are rejected at compile time. */ export function NoteBody({ source }: { source: string }) { return ( // overflow-wrap:anywhere keeps long URLs and unbroken words inside the card on small screens. diff --git a/src/lib/env-example.test.ts b/src/lib/env-example.test.ts index e8261e6..a19232f 100644 --- a/src/lib/env-example.test.ts +++ b/src/lib/env-example.test.ts @@ -32,10 +32,8 @@ test(".env.example contains only public, non-secret settings", () => { assert.ok(!/secret|password|api[_-]?key|token/i.test(Object.keys(example).join(" "))); }); -test("the deployment guide documents the same channel id and the apex-primary steps", () => { +test("the deployment guide matches the public channel and canonical site configuration", () => { const doc = fs.readFileSync("docs/deployment.md", "utf8"); - assert.ok(doc.includes("UC74q2pzSGuoaikYwnavcGMg")); - assert.match(doc, /Redirect to Another Domain/); - assert.match(doc, /308/); - assert.ok(doc.includes("https://procoderji.com")); + assert.ok(doc.includes(example.YOUTUBE_CHANNEL_ID)); + assert.ok(doc.includes(DEFAULT_SITE_URL)); });