Stabilize and modernize portfolio baseline

.github/workflows/nextjs.yml

@@ -1,93 +1,67 @@
-# Sample workflow for building and deploying a Next.js site to GitHub Pages
-#
-# To get started with Next.js see: https://nextjs.org/docs/getting-started
-#
-name: Deploy Next.js site to Pages
+name: Validate and deploy portfolio
 
 on:
-  # Runs on pushes targeting the default branch
+  pull_request:
+    branches: [main]
   push:
-    branches: ["main"]
-
-  # Allows you to run this workflow manually from the Actions tab
+    branches: [main]
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
 jobs:
-  # Build job
   build:
+    name: Validate and build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
-      - name: Detect package manager
-        id: detect-package-manager
-        run: |
-          if [ -f "${{ github.workspace }}/yarn.lock" ]; then
-            echo "manager=yarn" >> $GITHUB_OUTPUT
-            echo "command=install" >> $GITHUB_OUTPUT
-            echo "runner=yarn" >> $GITHUB_OUTPUT
-            exit 0
-          elif [ -f "${{ github.workspace }}/package.json" ]; then
-            echo "manager=npm" >> $GITHUB_OUTPUT
-            echo "command=ci" >> $GITHUB_OUTPUT
-            echo "runner=npx --no-install" >> $GITHUB_OUTPUT
-            exit 0
-          else
-            echo "Unable to determine package manager"
-            exit 1
-          fi
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          cache: ${{ steps.detect-package-manager.outputs.manager }}
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-        with:
-          # Automatically inject basePath in your Next.js configuration file and disable
-          # server side image optimization (https://nextjs.org/docs/api-reference/next/image#unoptimized).
-          #
-          # You may remove this line if you want to manage the configuration yourself.
-          static_site_generator: next
-      - name: Restore cache
-        uses: actions/cache@v4
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
         with:
-          path: |
-            .next/cache
-          # Generate a new cache whenever packages or source files change.
-          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
-          # If source files changed but packages didn't, rebuild from a prior cache.
-          restore-keys: |
-            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
+          node-version: "24"
+          cache: npm
+
       - name: Install dependencies
-        run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
-      - name: Build with Next.js
-        run: ${{ steps.detect-package-manager.outputs.runner }} next build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        run: npm ci
+
+      - name: Audit dependencies
+        run: npm audit --audit-level=high
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        run: npm test
+
+      - name: Build static site
+        run: npm run build
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5
         with:
           path: ./out
 
-  # Deployment job
   deploy:
+    name: Deploy to GitHub Pages
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
     steps:
-      - name: Deploy to GitHub Pages
+      - name: Deploy
         id: deployment
         uses: actions/deploy-pages@v5

.gitignore

@@ -12,9 +12,11 @@
 
 # testing
 /coverage
+/.tmp/
 
 # next.js
 /.next/
+**/.next/
 /out/
 
 # production

README.md

@@ -1,10 +1,84 @@
-# Welcome
-This is my experience with GitHub Pages.
+# JMG3000.github.io
 
+- Personal portfolio for Jacob Garrett.
+- Production URL: [jmg3000.github.io](https://jmg3000.github.io/)
+- Active application: Next.js Pages Router, React, TypeScript, Chakra UI.
+- Hosting model: static export deployed to GitHub Pages.
 
+## Current architecture
 
+- `src/pages/`: production routes and page metadata.
+- `components/`: shared responsive application layout.
+- `components/ui/`: Chakra UI provider and reusable UI utilities.
+- `config/site.ts`: compatible loader for preserved `.md` and `.markdown` content.
+- `content/posts/`: preserved post content from the Jekyll implementation.
+- `public/`: profile image, resume, favicon, and static assets.
+- `.github/workflows/nextjs.yml`: pull-request validation and GitHub Pages deployment.
 
+## Production routes
 
+- `/`: profile, capabilities, and contact links.
+- `/portfolio`: selected project work and public engineering profile.
+- `404`: generated by Next.js for unmatched static paths.
 
-----------------------------
-##### Are you able to find the door?
+## Local development
+
+- Required runtime: Node.js 24 and npm.
+- Install locked dependencies:
+
+```bash
+npm ci
+```
+
+- Start development server:
+
+```bash
+npm run dev
+```
+
+- Run the complete local quality gate:
+
+```bash
+npm run check
+```
+
+- Run checks individually:
+
+```bash
+npm audit --audit-level=high
+npm run lint
+npm run typecheck
+npm test
+npm run build
+```
+
+- Static output is generated in `out/`.
+- GitHub Pages has no request-time Node.js runtime; all production routes must remain statically exportable.
+
+## Delivery controls
+
+- Pull requests run dependency audit, lint, typecheck, tests, and static build.
+- Pushes to `main` run the same validation before deployment.
+- Build job is read-only.
+- Pages write and OIDC permissions exist only in the deployment job.
+- Production deployment uses the `out/` artifact produced from the locked dependency graph.
+
+## Preserved project history
+
+- `README.txt`: original planning notes and dated migration changelog beginning November 2025.
+- `prior_site_architecture/`: preserved Ruby/Jekyll site structure, configuration, content, and assets.
+- `content/posts/`: original Jekyll post retained for content compatibility.
+- Git history and tag `v1.0.0`: complete evolution from the initial GitHub Pages/Jekyll site through Next.js.
+- `docs/jira-tracker.md`: historical issue-tracking record.
+
+## Modernization records
+
+- [Architecture decision and stabilization scope](docs/superpowers/specs/2026-07-23-portfolio-modernization-design.md)
+- [Executable stabilization plan](docs/superpowers/plans/2026-07-23-portfolio-stabilization.md)
+
+## Deferred roadmap
+
+- Incremental App Router migration after the stabilized baseline is deployed.
+- Expanded project case studies with measurable outcomes and supporting media.
+- Full visual-design pass, accessibility review, and performance budgets.
+- Optional custom domain, analytics, monitoring, and server-backed contact workflow.

components/Layout.tsx

@@ -4,46 +4,63 @@ import NextLink from "next/link";
 export default function Layout({ children }: { children: React.ReactNode }) {
   return (
     <VStack minH="100vh" gap={0}>
-      <Box bg="gray.800" color="white" py={4} w="100%">
-        <Container maxW="container.lg">
-          <Flex justify="space-between" align="center">
-
-            // change href and a href tags to CharkraLinks 
-            <NextLink href="/">
-              <Text fontSize="xl" fontWeight="bold" cursor="pointer">
-                Jacob Garrett
-              </Text>
-            </NextLink>
-            <Stack direction="row" gap={6}>
+      <Box as="header" bg="gray.800" color="white" py={4} w="100%">
+        <Container maxW="6xl">
+          <Flex
+            as="nav"
+            aria-label="Primary"
+            align={{ base: "flex-start", sm: "center" }}
+            direction={{ base: "column", sm: "row" }}
+            gap={4}
+            justify="space-between"
+          >
+            <Link asChild _hover={{ textDecoration: "underline" }}>
               <NextLink href="/">
-                <Link _hover={{ textDecoration: "underline" }}>Home</Link>
-              </NextLink>
-              <NextLink href="/portfolio">
-                <Link _hover={{ textDecoration: "underline" }}>Portfolio</Link>
-              </NextLink>
-              <NextLink href="/tutorials">
-                <Link _hover={{ textDecoration: "underline" }}>Tutorials</Link>
+                <Text as="span" fontSize="xl" fontWeight="bold">
+                  Jacob Garrett
+                </Text>
               </NextLink>
+            </Link>
+            <Stack as="span" direction="row" gap={{ base: 4, sm: 6 }} wrap="wrap">
+              <Link asChild _hover={{ textDecoration: "underline" }}>
+                <NextLink href="/">Home</NextLink>
+              </Link>
+              <Link asChild _hover={{ textDecoration: "underline" }}>
+                <NextLink href="/portfolio">Portfolio</NextLink>
+              </Link>
             </Stack>
           </Flex>
         </Container>
       </Box>
 
-      <Container maxW="container.lg" py={8} flex={1} w="100%">
+      <Container as="main" maxW="6xl" py={{ base: 8, md: 12 }} flex={1} w="100%">
         {children}
       </Container>
 
-      <Box bg="gray.800" color="white" py={6} w="100%" mt="auto">
-        <Container maxW="container.lg">
+      <Box as="footer" bg="gray.800" color="white" py={6} w="100%" mt="auto">
+        <Container maxW="6xl">
           <Stack gap={4}>
-            <Stack direction="row" gap={6}>
-              <NextLink href="https://github.com/JMG3000" target="_blank">
-                <Link _hover={{ textDecoration: "underline" }}>GitHub</Link>
-              </NextLink>
-              <NextLink href="https://www.linkedin.com/in/jacobgarrett/" target="_blank">
-                <Link _hover={{ textDecoration: "underline" }}>LinkedIn</Link>
-              </NextLink>
-              <Link href="mailto:jakeincbusinesssolutions@gmail.com" _hover={{ textDecoration: "underline" }}>
+            <Stack direction="row" gap={{ base: 4, sm: 6 }} wrap="wrap">
+              <Link
+                href="https://github.com/JMG3000"
+                target="_blank"
+                rel="noopener noreferrer"
+                _hover={{ textDecoration: "underline" }}
+              >
+                GitHub
+              </Link>
+              <Link
+                href="https://www.linkedin.com/in/jacobgarrett/"
+                target="_blank"
+                rel="noopener noreferrer"
+                _hover={{ textDecoration: "underline" }}
+              >
+                LinkedIn
+              </Link>
+              <Link
+                href="mailto:jakeincbusinesssolutions@gmail.com"
+                _hover={{ textDecoration: "underline" }}
+              >
                 Email
               </Link>
             </Stack>
@@ -55,4 +72,4 @@ export default function Layout({ children }: { children: React.ReactNode }) {
       </Box>
     </VStack>
   );
-}
+}

config/site.ts

@@ -1,11 +1,37 @@
-import fs from "fs";
-import matter from "gray-matter";
+import fs from "node:fs";
+import path from "node:path";
+
+import { load } from "js-yaml";
+
+const postDirectory = path.join(process.cwd(), "content", "posts");
+const frontMatterPattern = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+function parsePost(raw: string) {
+  const frontMatter = raw.match(frontMatterPattern);
+
+  if (!frontMatter) {
+    return { meta: {}, content: raw };
+  }
+
+  const parsed = load(frontMatter[1]);
+  const meta: Record<string, unknown> =
+    typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : {};
+
+  return { meta, content: raw.slice(frontMatter[0].length) };
+}
 
 export function readPost(slug: string) {
-  const raw = fs.readFileSync(`content/posts/${slug}.md`, "utf8");
-  const { data, content } = matter(raw);
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(slug)) {
+    throw new Error(`Invalid post slug: ${slug}`);
+  }
+
+  const postPath = [".md", ".markdown"]
+    .map((extension) => path.join(postDirectory, `${slug}${extension}`))
+    .find((candidate) => fs.existsSync(candidate));
 
+  if (!postPath) {
+    throw new Error(`Post not found: ${slug}`);
+  }
 
-  return { meta: data, content };
+  return parsePost(fs.readFileSync(postPath, "utf8"));
 }
-// ...use meta.title etc. in pages instead of Jekyll site._config...