@next-friday/create-app 0.0.0-stage → 0.1.0

package/templates/nestjs/src/health/health.module.ts

@@ -0,0 +1,10 @@
+import {Module} from "@nestjs/common";
+import {TerminusModule} from "@nestjs/terminus";
+
+import {HealthController} from "./health.controller.js";
+
+@Module({
+  imports: [TerminusModule],
+  controllers: [HealthController],
+})
+export class HealthModule {}

package/templates/nestjs/src/main.ts

@@ -0,0 +1,25 @@
+import {ConsoleLogger} from "@nestjs/common";
+import {NestFactory} from "@nestjs/core";
+import type {NestExpressApplication} from "@nestjs/platform-express";
+
+import {AppModule} from "./app.module.js";
+import {parsePort} from "./port.js";
+
+/**
+ * Start the HTTP server on the port given by the `PORT` environment variable. Production logs are JSON lines.
+ */
+async function bootstrap() {
+  const port = parsePort(process.env.PORT);
+
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+    logger: new ConsoleLogger({
+      json: process.env.NODE_ENV === "production",
+    }),
+  });
+
+  app.disable("x-powered-by");
+  app.enableShutdownHooks();
+  await app.listen(port);
+}
+
+void bootstrap();

package/templates/nestjs/src/port.test.ts

@@ -0,0 +1,29 @@
+import {assert, integer, property} from "fast-check";
+
+import {parsePort} from "./port.js";
+
+describe("parsePort", () => {
+  it("reads every port from 1 to 65535", () => {
+    assert(
+      property(
+        integer({
+          min: 1,
+          max: 65_535,
+        }),
+        port => {
+          expect(parsePort(String(port))).toBe(port);
+        },
+      ),
+    );
+  });
+
+  it.each([undefined, ""])("requires a value, rejecting %j", value => {
+    expect(() => parsePort(value)).toThrow("PORT environment variable is required");
+  });
+
+  it.each(["abc", "0", "65536", "3000.5", "-1", " 3000", "0x10"])("rejects %j", value => {
+    expect(() => parsePort(value)).toThrow(
+      `PORT must be an integer from 1 to 65535, got "${value}"`,
+    );
+  });
+});

package/templates/nestjs/src/port.ts

@@ -0,0 +1,20 @@
+const maxPort = 65_535;
+
+/**
+ * Read the TCP port the server listens on.
+ * @param value - The raw `PORT` environment variable.
+ * @returns The port as an integer from 1 to 65535.
+ */
+export function parsePort(value: string | undefined): number {
+  if (value === undefined || value === "") {
+    throw new Error("PORT environment variable is required");
+  }
+
+  const port = Number(value);
+
+  if (!/^\d+$/.test(value) || port < 1 || port > maxPort) {
+    throw new Error(`PORT must be an integer from 1 to ${maxPort}, got "${value}"`);
+  }
+
+  return port;
+}

package/templates/nestjs/test/app.e2e.test.ts

@@ -0,0 +1,40 @@
+import request from "supertest";
+import {Test, TestingModule} from "@nestjs/testing";
+import type {INestApplication} from "@nestjs/common";
+import type {Server} from "node:http";
+
+import {AppModule} from "../src/app.module.js";
+
+describe("AppController (e2e)", () => {
+  let app: INestApplication<Server>;
+
+  beforeEach(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+  });
+
+  it("GET / returns the greeting", async () => {
+    const response = await request(app.getHttpServer()).get("/");
+
+    expect(response.status).toBe(200);
+    expect(response.text).toBe("Hello World!");
+  });
+
+  it("GET /health reports ok", async () => {
+    const response = await request(app.getHttpServer()).get("/health");
+
+    expect(response.status).toBe(200);
+
+    expect(response.body).toMatchObject({
+      status: "ok",
+    });
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+});

package/templates/nestjs/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "test", "dist", "**/*.test.ts"]
+}

package/templates/nestjs/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "nodenext",
+    "isolatedModules": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "incremental": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strictPropertyInitialization": false,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "types": ["vitest/globals", "node"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/nestjs/vitest.config.ts

@@ -0,0 +1,13 @@
+import {defineConfig} from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    coverage: {
+      reporter: ["text", "html", "cobertura"],
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts", "src/main.ts", "src/**/*.module.ts"],
+    },
+    include: ["src/**/*.test.ts"],
+  },
+});

package/templates/nestjs/vitest.e2e.config.ts

@@ -0,0 +1,8 @@
+import {defineConfig} from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ["test/**/*.e2e.test.ts"],
+  },
+});

package/templates/nextjs/.agents/rules/typescript-first.md

@@ -0,0 +1,7 @@
+# TypeScript-First
+
+In a TypeScript-capable app or package, write source, tests, and scripts as `.ts`, and JSX as `.tsx`. Use that extension for new work and for any JavaScript file whose implementation this change already touches, then update its imports, scripts, tests, and configuration in the same change.
+
+Keep other languages in separately maintained components. Use a non-TypeScript extension when the runtime, tool, or public contract requires it.
+
+_Completion criterion_: Every file this change created or materially rewrote in a TypeScript-capable project uses the TypeScript extension the runtime accepts, and its imports and scripts resolve.

package/templates/nextjs/.agents/rules.json

@@ -0,0 +1,41 @@
+{
+  "automation-owned-checks": {
+    "description": "Owned checks: hooks and CI define what must pass; run checks by hand to verify"
+  },
+  "code-comments": {
+    "description": "Required comments: comment only where a tool or rule needs it, or for a reason the code cannot show"
+  },
+  "current-state-authority": {
+    "description": "Current state: implement from user requirements and the working tree"
+  },
+  "demand-driven-configuration": {
+    "description": "Demand-driven configuration: add a setting only for an active requirement"
+  },
+  "dependency-security": {
+    "description": "Dependencies: add a package only when code or a contract uses it",
+    "globs": ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml"]
+  },
+  "deterministic-testing": {
+    "description": "Test admission: add a case only when it catches a defect current tests miss",
+    "globs": ["**/*.test.ts", "**/*.test.tsx"]
+  },
+  "diagnostics-and-error-handling": {
+    "description": "Diagnostics: fix runtime failures at the source and keep the root cause"
+  },
+  "git-workflow": {
+    "description": "Git workflow: trunk-based branches, commits, and pull requests"
+  },
+  "no-suppression": {
+    "description": "Findings: fix scanner and linter reports without inline suppressions"
+  },
+  "script-driven-changes": {
+    "description": "Scripts: apply a repeated edit across many files with a script"
+  },
+  "single-author-style": {
+    "description": "Sibling style: match layout, naming, and composition in the same project"
+  },
+  "typescript-first": {
+    "description": "TypeScript-first: write source, tests, and scripts as .ts or .tsx",
+    "globs": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
+  }
+}

package/templates/nextjs/.claude/rules/deterministic-testing.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+---
+
+# Test Admission
+
+Keep tests as small, deterministic protections for observable contracts.
+
+Name the contract and the distinct defect a proposed test can detect before writing it. Admit a test for externally observable behavior, a public contract, a demonstrated regression, a non-trivial invariant, a meaningful failure mode, or an explicit repository verification requirement.
+
+Choose the narrowest existing layer that owns that contract. Give each test one defect to detect. Add a case only when it catches a defect remaining cases miss. Treat coverage percentage as a measurement.
+
+Search existing coverage first. Extend the file that already owns the contract. Create a file only when the contract has no owner or needs a different harness. Follow the nearest directory and naming pattern. Keep setup local until multiple tests share live runtime logic, then extract one helper.
+
+Use the framework's standard assertions. Use an inline snippet unless filesystem paths, module resolution, or compiler services are the contract. Keep fixtures declarative and read-only.
+
+When the user asks to run tests, run the narrowest owning file or filter.
+
+_Completion criterion_: Every added or modified case maps to an admitted contract and a defect current cases would miss. Tests stay unchanged when no proposed case survives admission.

package/templates/nextjs/.claude/rules/typescript-first.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
+# TypeScript-First
+
+In a TypeScript-capable app or package, write source, tests, and scripts as `.ts`, and JSX as `.tsx`. Use that extension for new work and for any JavaScript file whose implementation this change already touches, then update its imports, scripts, tests, and configuration in the same change.
+
+Keep other languages in separately maintained components. Use a non-TypeScript extension when the runtime, tool, or public contract requires it.
+
+_Completion criterion_: Every file this change created or materially rewrote in a TypeScript-capable project uses the TypeScript extension the runtime accepts, and its imports and scripts resolve.

package/templates/nextjs/.cursor/rules/deterministic-testing.mdc

@@ -0,0 +1,21 @@
+---
+description: "Test admission: add a case only when it catches a defect current tests miss"
+globs: "**/*.test.ts,**/*.test.tsx"
+alwaysApply: false
+---
+
+# Test Admission
+
+Keep tests as small, deterministic protections for observable contracts.
+
+Name the contract and the distinct defect a proposed test can detect before writing it. Admit a test for externally observable behavior, a public contract, a demonstrated regression, a non-trivial invariant, a meaningful failure mode, or an explicit repository verification requirement.
+
+Choose the narrowest existing layer that owns that contract. Give each test one defect to detect. Add a case only when it catches a defect remaining cases miss. Treat coverage percentage as a measurement.
+
+Search existing coverage first. Extend the file that already owns the contract. Create a file only when the contract has no owner or needs a different harness. Follow the nearest directory and naming pattern. Keep setup local until multiple tests share live runtime logic, then extract one helper.
+
+Use the framework's standard assertions. Use an inline snippet unless filesystem paths, module resolution, or compiler services are the contract. Keep fixtures declarative and read-only.
+
+When the user asks to run tests, run the narrowest owning file or filter.
+
+_Completion criterion_: Every added or modified case maps to an admitted contract and a defect current cases would miss. Tests stay unchanged when no proposed case survives admission.

package/templates/nextjs/.cursor/rules/typescript-first.mdc

@@ -0,0 +1,13 @@
+---
+description: "TypeScript-first: write source, tests, and scripts as .ts or .tsx"
+globs: "**/*.ts,**/*.tsx,**/*.js,**/*.jsx"
+alwaysApply: false
+---
+
+# TypeScript-First
+
+In a TypeScript-capable app or package, write source, tests, and scripts as `.ts`, and JSX as `.tsx`. Use that extension for new work and for any JavaScript file whose implementation this change already touches, then update its imports, scripts, tests, and configuration in the same change.
+
+Keep other languages in separately maintained components. Use a non-TypeScript extension when the runtime, tool, or public contract requires it.
+
+_Completion criterion_: Every file this change created or materially rewrote in a TypeScript-capable project uses the TypeScript extension the runtime accepts, and its imports and scripts resolve.

package/templates/nextjs/.dependency-cruiser.json

@@ -0,0 +1,34 @@
+{
+  "extends": "dependency-cruiser/configs/recommended-strict",
+  "forbidden": [
+    {
+      "name": "no-orphans",
+      "to": {},
+      "from": {
+        "orphan": true,
+        "pathNot": [
+          "(^|/)tsconfig\\.json$",
+          "(^|/)eslint\\.config\\.ts$",
+          "(^|/)next\\.config\\.ts$",
+          "(^|/)postcss[.]config[.]mjs$",
+          "(^|/)vitest[.]config[.]ts$",
+          "(^|/)playwright[.]config[.]ts$",
+          "^test/.*[.]e2e[.]test[.]ts$",
+          "^app/.*(page|layout|template|loading|error|not-found|default|route)[.]tsx?$"
+        ]
+      }
+    }
+  ],
+  "options": {
+    "skipAnalysisNotInRules": true,
+    "tsPreCompilationDeps": true,
+    "enhancedResolveOptions": {
+      "conditionNames": ["import", "require", "node", "default", "types"],
+      "exportsFields": ["exports"]
+    },
+    "exclude": "(^|/)(?:\\.next|coverage|node_modules)/",
+    "tsConfig": {
+      "fileName": "tsconfig.json"
+    }
+  }
+}

package/templates/nextjs/.dockerignore

@@ -0,0 +1,10 @@
+*
+!package.json
+!pnpm-lock.yaml
+!pnpm-workspace.yaml
+!next.config.ts
+!postcss.config.mjs
+!tsconfig.json
+!app/
+app/**/*.test.ts
+app/**/*.test.tsx

package/templates/nextjs/.env.example

@@ -0,0 +1 @@
+# Copy to .env and fill in. List every environment variable the app reads, with a safe example value.

package/templates/nextjs/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,66 @@
+name: Bug report
+description: Report crashes, incorrect behavior, or setup problems.
+labels: ["bug", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Reproduce the issue with the supported Node.js version.
+        Remove credentials, secrets, personal or customer data, and proprietary source code before submitting.
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before you submit
+      description: Confirm these items before submitting the report.
+      options:
+        - label: I searched existing issues and didn't find a matching report.
+          required: true
+        - label: I can reproduce this issue on the latest commit of the default branch.
+          required: true
+  - type: input
+    id: version
+    attributes:
+      label: Commit
+      placeholder: 769e0ef
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: List Node.js, operating system, package manager, browser, and device.
+      placeholder: |
+        Node.js: 24.22.1
+        OS: Ubuntu 24.04 / macOS
+        Package manager: pnpm 12.6.0
+        Browser: Chrome on Android
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Link to a minimal public reproduction or provide sanitized code and configuration that reproduce the issue.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Describe the behavior you expected.
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Describe what happened, including errors and logs.
+    validations:
+      required: true
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Sensitive information
+      options:
+        - label: I removed credentials, secrets, personal or customer data, and proprietary code from this report.
+          required: true

package/templates/nextjs/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,50 @@
+name: Feature request
+description: Suggest a specific change to next-friday-template-nextjs.
+labels: ["enhancement", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for changes that are ready to evaluate.
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Affected area
+      description: Select the area this request affects.
+      options:
+        - Pages and routes
+        - Components and styling
+        - Configuration
+        - Tooling / CI
+        - Documentation
+        - Repository governance
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Describe the problem or use case.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: Describe the smallest change that solves the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: List existing options you considered.
+    validations:
+      required: false
+  - type: checkboxes
+    id: breaking
+    attributes:
+      label: Breaking change
+      description: Indicate whether this request changes behavior for existing users.
+      options:
+        - label: This request changes an existing page route or public contract.

package/templates/nextjs/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+<!-- Title: `<type>(<scope>): <subject>` with a lowercase scope and a subject of 50 characters or fewer. Repository workflows validate it. The squash merge puts the title on `main`. Delete a section that has nothing to say, except Scope. -->
+
+## Why
+
+<!-- The problem and the approach in 1-3 short sentences. No SHAs or rebase history. Link a related issue with `Closes #123`. -->
+
+## What changed
+
+<!-- 1-3 short bullets. Name a symbol or path only when it carries the change, and both sides of a rename. Name every added, changed, or removed page, route, and environment variable. Document new variables in `.env.example`. -->
+
+## Scope
+
+<!-- 1-3 short items: what this covers and what it deliberately leaves out. -->
+
+## Tradeoffs
+
+<!-- Only rejected alternatives a reviewer would ask about. -->
+
+## Blast Radius
+
+<!-- 1-2 sentences on who or what this touches and why that is safe or risky. If main is red, state the cost of leaving it red. -->
+
+## Verification
+
+<!-- 1-3 bullets, each a check you ran and its outcome. For a perf change, one number as before -> after. After this section, attach videos or screenshots that prove a claim. -->