@vpnsin/devkit 0.1.3

package/templates/github/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported versions
+
+The latest released version on the default branch receives security updates.
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for security problems.**
+
+Report privately through GitHub's
+[private vulnerability reporting](https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
+(repository **Security** tab → **Report a vulnerability**), or email
+**<security@example.com>**. <!-- TODO: set your security contact -->
+
+Please include:
+
+- affected version(s) and environment,
+- steps to reproduce / proof of concept,
+- impact assessment.
+
+We aim to acknowledge reports within **48 hours** and to share a remediation
+timeline after triage. Please give us a reasonable window to fix the issue
+before any public disclosure.

package/templates/github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint, type-check & build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Free dependency vulnerability check — works on public and private repos,
+      # and stands in for GHAS Dependency Review on private repos. Non-blocking.
+      - name: Audit dependencies
+        run: npm audit --audit-level=high
+        continue-on-error: true
+
+      - name: Type-check
+        run: npm run type-check --if-present
+
+      - name: Lint (ESLint)
+        run: npm run lint --if-present
+
+      - name: Lint (Markdown)
+        run: npm run lint:md --if-present
+
+      - name: Prettier check
+        run: npm run format:check --if-present
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Test
+        run: npm test --if-present

package/templates/github/workflows/codeql.yml

@@ -0,0 +1,35 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 6 * * 1' # weekly, Mondays 06:00 UTC
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze (javascript-typescript)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: javascript-typescript
+          queries: security-extended
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: '/language:javascript-typescript'

package/templates/github/workflows/dependency-review.yml

@@ -0,0 +1,23 @@
+name: Dependency Review
+
+# Flags vulnerable or disallowed dependencies introduced in a pull request.
+# (GitHub Advanced Security — free on public repos.)
+on:
+  pull_request:
+    branches: [main, dev]
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@v5
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: on-failure

package/templates/github/workflows/lighthouse.yml

@@ -0,0 +1,39 @@
+name: Lighthouse
+
+# Lighthouse CI on pull requests — performance, accessibility, best-practices
+# and SEO. Builds the app, serves it, audits the URLs in lighthouserc.json, and
+# posts a public report link in the run logs.
+# Opt-in: NOT installed by `devkit init` unless you pass --lighthouse.
+on:
+  pull_request:
+    branches: [main, dev]
+
+permissions:
+  contents: read
+
+jobs:
+  lighthouse:
+    name: Lighthouse CI
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Run Lighthouse CI
+        uses: treosh/lighthouse-ci-action@v12
+        with:
+          configPath: ./lighthouserc.json
+          uploadArtifacts: true
+          temporaryPublicStorage: true

package/templates/github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish (manual)
+
+# Manual npm publish / re-publish of the version currently in package.json.
+# Use to recover a release whose auto-publish failed (e.g. a bad NPM_TOKEN), or
+# to publish out of band. Normal releases publish automatically from the
+# release-please workflow when its PR is merged. Opt-in: only installed by
+# `devkit init --publish`. For a private/scoped package, adjust `--access`.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write # npm provenance
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          registry-url: 'https://registry.npmjs.org'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Publish
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/templates/github/workflows/release-please-publish.yml

@@ -0,0 +1,54 @@
+name: Release Please
+
+# Maintains a release PR from Conventional Commits; merging it bumps the version,
+# updates CHANGELOG.md, creates a GitHub release + tag, and publishes to npm.
+# Publish is integrated here (rather than a separate `on: release` workflow)
+# because a release created by GITHUB_TOKEN does not trigger other workflows.
+# Requires an NPM_TOKEN repo secret (an npm automation token).
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write # npm provenance
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run release-please
+        id: release
+        uses: googleapis/release-please-action@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # Publish to npm only when a release was just created (the release PR merged).
+      - name: Checkout
+        if: ${{ steps.release.outputs.release_created }}
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        if: ${{ steps.release.outputs.release_created }}
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          registry-url: 'https://registry.npmjs.org'
+          cache: npm
+
+      - name: Install dependencies
+        if: ${{ steps.release.outputs.release_created }}
+        run: npm ci
+
+      - name: Build
+        if: ${{ steps.release.outputs.release_created }}
+        run: npm run build --if-present
+
+      - name: Publish to npm
+        if: ${{ steps.release.outputs.release_created }}
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/templates/github/workflows/release-please.yml

@@ -0,0 +1,22 @@
+name: Release Please
+
+# Maintains a release PR from Conventional Commits; merging it bumps the version
+# in package.json, updates CHANGELOG.md, and creates a GitHub release + git tag.
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run release-please
+        uses: googleapis/release-please-action@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

package/templates/github/workflows/scorecard.yml

@@ -0,0 +1,41 @@
+name: Scorecard
+
+# OSSF Scorecard — supply-chain security posture (branch protection, pinned
+# actions, token permissions, etc.). Best suited to PUBLIC repos; on private
+# repos it needs a PAT with repo + read:org scopes in `repo_token`.
+# Opt-in: this workflow is NOT installed by `devkit init` by default.
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: '0 8 * * 1' # weekly, Mondays 08:00 UTC
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@v2.4.1
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload results to code scanning
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: results.sarif
+          category: scorecard

package/templates/github/workflows/sonarqube.yml

@@ -0,0 +1,31 @@
+name: SonarCloud
+
+# CI-based SonarCloud (SonarQube Cloud) analysis. Requires:
+#   1. a SONAR_TOKEN repo secret (SonarCloud → My Account → Security → token), and
+#   2. Automatic Analysis turned OFF in SonarCloud (project → Administration →
+#      Analysis Method) — CI and Automatic Analysis cannot both run.
+# Project keys live in sonar-project.properties.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main, dev]
+
+permissions:
+  contents: read
+
+jobs:
+  sonarcloud:
+    name: SonarCloud scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history improves new-code detection & blame
+
+      - name: SonarCloud scan
+        uses: SonarSource/sonarqube-scan-action@v8.1.0
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: https://sonarcloud.io

package/templates/github/workflows/trivy.yml

@@ -0,0 +1,43 @@
+name: Trivy
+
+# Scans the repo's dependencies, IaC/config and committed secrets, and uploads
+# results to GitHub code scanning (Security tab). Works on any repo — no
+# container image required.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: '0 7 * * 1' # weekly, Mondays 07:00 UTC
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    name: Filesystem scan
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write # upload SARIF to code scanning
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Run Trivy
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          scan-type: fs
+          scanners: vuln,secret,misconfig
+          format: sarif
+          output: trivy-results.sarif
+          severity: CRITICAL,HIGH
+          ignore-unfixed: true
+
+      - name: Upload results to code scanning
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: trivy-results.sarif
+          category: trivy

package/templates/husky/commit-msg

@@ -0,0 +1 @@
+npx --no-install commitlint --edit "$1"

package/templates/husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/templates/lighthouserc.json

@@ -0,0 +1,23 @@
+{
+  "ci": {
+    "collect": {
+      "startServerCommand": "npm run start",
+      "startServerReadyPattern": "ready|started|listening|Local:|localhost",
+      "startServerReadyTimeout": 60000,
+      "url": ["http://localhost:3000/"],
+      "numberOfRuns": 3,
+      "settings": { "preset": "desktop" }
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["warn", { "minScore": 0.9 }],
+        "categories:accessibility": ["error", { "minScore": 0.9 }],
+        "categories:best-practices": ["warn", { "minScore": 0.9 }],
+        "categories:seo": ["warn", { "minScore": 0.9 }]
+      }
+    },
+    "upload": {
+      "target": "temporary-public-storage"
+    }
+  }
+}

package/templates/markdownlint-cli2.jsonc

@@ -0,0 +1,20 @@
+{
+  // Tuned to coexist with Prettier (which owns whitespace/wrapping).
+  "config": {
+    "default": true,
+    "MD013": false, // line length — Prettier/readability decides wrapping
+    "MD033": false, // allow inline HTML
+    "MD036": false, // intentional bold (taglines, "Last updated:") is not a heading
+    "MD041": false, // first line need not be a top-level heading
+    "MD024": { "siblings_only": true } // duplicate headings ok across sections
+  },
+  "globs": ["**/*.md"],
+  "ignores": [
+    "node_modules",
+    ".next",
+    "dist",
+    "build",
+    "CHANGELOG.md",
+    ".github/**/*.md"
+  ]
+}

package/templates/npmrc

@@ -0,0 +1,9 @@
+# Fail the install when the local Node/npm doesn't satisfy package.json "engines".
+engine-strict=true
+
+# Quieter installs.
+fund=false
+
+# Reproducible installs — uncomment for applications.
+# Leave commented for published libraries so consumers keep semver ranges.
+# save-exact=true

package/templates/nvmrc

@@ -0,0 +1 @@
+22

package/templates/release-please-config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "changelog-path": "CHANGELOG.md",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true,
+      "include-component-in-tag": false,
+      "draft": false,
+      "prerelease": false
+    }
+  }
+}

package/templates/sonar-project.properties

@@ -0,0 +1,13 @@
+# SonarCloud / SonarQube Cloud project config.
+# Find the org & project keys in SonarCloud → your project → Information.
+sonar.organization=YOUR_SONAR_ORG
+sonar.projectKey=YOUR_ORG_YOUR_REPO
+# sonar.projectName=Your Project
+
+sonar.sources=.
+sonar.exclusions=**/node_modules/**,**/dist/**,**/build/**,**/.next/**,**/coverage/**
+
+# If you generate LCOV coverage, point Sonar at it:
+# sonar.javascript.lcov.reportPaths=coverage/lcov.info
+
+sonar.sourceEncoding=UTF-8

package/templates/vscode/extensions.json

@@ -0,0 +1,53 @@
+{
+  "recommendations": [
+    // ── Formatting, linting & spell-check (the toolchain devkit wires up) ──
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint",
+    "DavidAnson.vscode-markdownlint",
+    "streetsidesoftware.code-spell-checker",
+    "EditorConfig.EditorConfig",
+
+    // ── Diagnostics & DX ──
+    "usernamehw.errorlens",
+    "yoavbls.pretty-ts-errors",
+    "wix.vscode-import-cost",
+
+    // ── JavaScript / TypeScript / React authoring ──
+    "dsznajder.es7-react-js-snippets",
+    "formulahendry.auto-rename-tag",
+    "christian-kohler.npm-intellisense",
+    "christian-kohler.path-intellisense",
+    "wmaurer.change-case",
+
+    // ── Testing (Jest; pairs with `devkit init --jest`) ──
+    "orta.vscode-jest",
+    "firsttris.vscode-jest-runner",
+    "andys8.jest-snippets",
+
+    // ── Git & GitHub (devkit ships PR templates, governance & GH workflows) ──
+    "eamodio.gitlens",
+    "donjayamanne.githistory",
+    "ziyasal.vscode-open-in-github",
+    "github.vscode-pull-request-github",
+
+    // ── Code quality (pairs with `devkit init --sonar`) ──
+    "sonarsource.sonarlint-vscode",
+
+    // ── File-type support shipped by this scaffold ──
+    "mikestead.dotenv",
+    "redhat.vscode-yaml",
+    "github.vscode-github-actions",
+
+    // ── Markdown & docs ──
+    "yzhang.markdown-all-in-one",
+    "bierner.markdown-mermaid",
+    "tom-latham.markdown-pdf-plus",
+
+    // ── Productivity & navigation ──
+    "gruntfuggly.todo-tree",
+    "hediet.vscode-drawio",
+    "l13rary.l13-diff",
+    "bokuweb.vscode-ripgrep",
+    "ritwickdey.liveserver"
+  ]
+}

package/templates/vscode/settings.json

@@ -0,0 +1,70 @@
+{
+  // ── Formatting (Prettier owns it) ──────────────────────────────────────────
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "editor.formatOnPaste": false,
+  // Only format when a Prettier config is found, so unconfigured files are left alone.
+  "prettier.requireConfig": true,
+
+  // ── Editor basics (match .editorconfig + Prettier printWidth) ──────────────
+  "editor.tabSize": 2,
+  "editor.detectIndentation": false,
+  "editor.rulers": [100],
+  "editor.bracketPairColorization.enabled": true,
+  "editor.guides.bracketPairs": "active",
+  // Rename paired HTML/JSX tags together as you type.
+  "editor.linkedEditing": true,
+
+  // ── Lint fixes on save ─────────────────────────────────────────────────────
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "eslint.useFlatConfig": true,
+  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
+
+  // ── Files ──────────────────────────────────────────────────────────────────
+  "files.eol": "\n",
+  "files.insertFinalNewline": true,
+  "files.trimTrailingWhitespace": true,
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/dist": true,
+    "**/build": true,
+    "**/coverage": true,
+    "**/.next": true
+  },
+
+  // ── Diffs & reviews ────────────────────────────────────────────────────────
+  // Show whitespace-only changes in diffs (matters since we trim on save).
+  "diffEditor.ignoreTrimWhitespace": false,
+
+  // ── TypeScript / JavaScript ────────────────────────────────────────────────
+  // Use the project's own TypeScript, not VS Code's bundled version.
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "typescript.updateImportsOnFileMove.enabled": "always",
+  "javascript.updateImportsOnFileMove.enabled": "always",
+  "typescript.preferences.preferTypeOnlyAutoImports": true,
+  "typescript.preferences.importModuleSpecifier": "shortest",
+  "typescript.suggest.autoImports": true,
+
+  // ── Per-language formatters ────────────────────────────────────────────────
+  "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[typescriptreact]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[javascript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[javascriptreact]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[json]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[jsonc]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[css]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[scss]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[html]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[yaml]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[github-actions-workflow]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[dockercompose]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.codeActionsOnSave": {
+      "source.fixAll.markdownlint": "explicit"
+    }
+  }
+}

package/tsconfig/base.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "devkit base",
+  "_comment": "Framework-agnostic strict base. Extend a variant (node/next) or this directly.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  }
+}

package/tsconfig/next.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "devkit next",
+  "_comment": "For Next.js apps (App Router). Add your own paths/include in the repo tsconfig.",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "noEmit": true,
+    "allowJs": true,
+    "incremental": true,
+    "plugins": [{ "name": "next" }]
+  }
+}