shortpoet · shortpoet · Sep 8, 2025 · Sep 7, 2025 · Sep 7, 2025 · Sep 8, 2025
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:shortpoet.com)",
+      "Bash(pnpm:*)",
+      "Read(//Users/Shared/source/repos/shortpoet/**)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,44 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `app/`: Vue 3 + Vite (SSG) frontend. Source in `app/src/`, static assets in `app/public/`, build output in `app/build/`.
+- `.iac/`: Terraform for infrastructure (e.g., Cloudflare, base/app stacks). Linting and docs via pre-commit hooks.
+- `.github/workflows/`: CI/CD pipelines for building and deploying app/infra.
+- Tests live alongside code or under `app/tests/` (unit) and optional e2e via Cypress.
+
+## Build, Test, and Development Commands
+Run these in `app/` (uses pnpm):
+```bash
+pnpm i                # Install deps
+pnpm dev              # Start Vite dev server (port 8888)
+pnpm build            # Build (SSG) to app/build
+pnpm preview          # Preview local build
+pnpm test             # Run unit tests (Vitest)
+pnpm test:e2e         # Open Cypress (if e2e tests present)
+pnpm lint             # Lint
+pnpm lint:ext --fix   # Lint (Vue/TS/JS) and fix
+pnpm type-check       # TS type checking
+```
+Infra: use `tflint` and `terraform` inside relevant `.iac/` subdirs. CI handles deploys.
+
+## Coding Style & Naming Conventions
+- Linting/formatting: ESLint + Prettier (`app/.eslintrc.esm`, `app/.prettierrc.json`).
+  - 2-space indent, single quotes, semicolons, width 80, no trailing commas, `bracketSameLine: true`.
+- Vue SFC filenames in PascalCase (e.g., `Landing.vue`, `Start.vue`).
+- JS/TS modules: prefer descriptive names; camelCase for identifiers.
+- Terraform: snake_case for variables/locals; require provider/version constraints (see `.tflint.hcl`).
+
+## Testing Guidelines
+- Unit: Vitest. Name tests `*.spec.ts` or `*.test.ts`, colocated or under `app/tests/unit/`.
+- DOM-heavy tests should use a DOM environment (Vitest config) and minimal mocking.
+- E2E: Cypress via `pnpm test:e2e` (add tests under `app/cypress/`).
+
+## Commit & Pull Request Guidelines
+- Commits: imperative, concise; optional scope tags (`app:`, `iac:`, `ci:`). Link issues (e.g., `#123`) when relevant.
+- PRs: clear description, screenshots for UI changes, linked issues, and notes for infra changes (include `terraform plan` summary when applicable).
+- Before opening a PR: `pnpm lint`, `pnpm test`, and `pnpm build` should pass locally.
+
+## Security & Configuration
+- App env files: `app/.env`, `app/.env.uat`, `app/.env.prod`. Never commit secrets.
+- Cloudflare/AWS credentials flow via GitHub Actions secrets; for local infra work, follow `README.md` (e.g., `aws_assume_role`).
+
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+All frontend development happens in the `app/` directory using pnpm:
+
+```bash
+cd app
+pnpm i           # Install dependencies
+pnpm dev         # Start dev server on port 8888
+pnpm build       # SSG build to app/build/
+pnpm preview     # Preview local build
+pnpm test        # Unit tests (Vitest)
+pnpm lint        # ESLint + Prettier
+pnpm type-check  # TypeScript checks
+```
+
+Infrastructure commands (run in appropriate `.iac/` subdirectories):
+```bash
+terraform init
+terraform plan
+terraform apply
+tflint          # Linting for Terraform
+```
+
+## Architecture Overview
+
+### Frontend (`app/`)
+- **Framework**: Vue 3 + Vite with Static Site Generation (vite-ssg)
+- **Key Features**: Multilingual resume/portfolio, PDF export, articles from Markdown
+- **Build Output**: `app/build/` directory
+- **Main Views**: Landing (`/`), Resume (`/resume`), PDF (`/pdf`), About (`/about`), Articles (`/articles`)
+
+### Vue Application Structure
+- `app/src/views/`: Main page components (Landing.vue, Start.vue for /resume, PDF.vue, About.vue, Articles.vue)
+- `app/src/components/`: Feature-specific components organized by domain (Articles/, Landing/, Resume/)
+- `app/src/router/`: Vue Router configuration with automatic route generation via vite-plugin-pages
+- `app/locales/`: i18n YAML files for 18+ languages (default: en)
+- `app/src/modules/`: User modules for NProgress, i18n registration
+- `app/src/stores/`: Vuex store modules
+- `app/src/composables/`: Vue composition utilities
+
+### Key Technical Patterns
+- **Auto-imports**: Vue, Vue Router, VueUse, and local composables/stores auto-imported
+- **Component Registration**: Automatic component registration via unplugin-vue-components
+- **Markdown**: Articles written in Markdown with Shiki syntax highlighting, processed by vite-plugin-md
+- **Styling**: SCSS with Bootstrap 5, global variables in `@/assets/scss/_variables.scss`
+- **Aliases**: `@/` resolves to `app/src/`
+
+### Infrastructure (`.iac/`)
+- **Providers**: Cloudflare (primary), AWS (secondary)
+- **Structure**: 
+  - `infra_base/`: Base infrastructure
+  - `infra_app/`: Application-specific resources
+  - `cloudflare/`, `aws/`: Provider-specific configurations
+- **Deployment**: GitHub Actions workflows (`infra-app.yml`, `infra-base.yml`)
+
+### Testing Strategy
+- **Unit Tests**: Vitest with jsdom environment
+- **Test Location**: Configured to look for `test/**/*.test.ts` files
+- **E2E**: Cypress available via `pnpm test:e2e`
+- **Coverage**: Test environment includes Vue Test Utils, jsdom mocking
+
+### Development Patterns
+- **Code Style**: ESLint + Prettier with Vue 3 recommended rules
+- **TypeScript**: Strict configuration with Vue SFC TypeScript support
+- **Build**: Static site generation with sitemap generation, minified output
+- **Deployment**: CI/CD via GitHub Actions with Terraform for infrastructure
+
+### Important Configuration Files
+- `vite.config.ts`: Main build configuration with all plugins
+- `.eslintrc.esm`: ESLint configuration for Vue 3 + TypeScript
+- `package.json`: All development scripts and dependencies
+- `.tflint.hcl`: Terraform linting rules and version constraints
+
+### Multilingual Support
+The application supports 18+ languages with YAML-based translations in `app/locales/`. The i18n setup uses Vue I18n v9 with composition API support. Language files follow ISO language codes (e.g., `en.yml`, `zh-CN.yml`, `pt-BR.yml`).
diff --git a/README.md b/README.md
@@ -1,79 +1,74 @@
-# sp
-
-## npm upgrades
-
-```out
-ncu --upgrade
-Upgrading /Users/Shared/source/repos/shortpoet/sp/app/package.json
-[====================] 51/51 100%
-
- @fortawesome/fontawesome-free              ^5.15.4  →   ^6.3.0
- @fortawesome/fontawesome-svg-core          ^1.2.36  →   ^6.3.0
- @fortawesome/free-brands-svg-icons         ^5.15.4  →   ^6.3.0
- @fortawesome/free-regular-svg-icons        ^5.15.4  →   ^6.3.0
- @fortawesome/free-solid-svg-icons          ^5.15.4  →   ^6.3.0
- @fortawesome/vue-fontawesome               ^0.1.10  →   ^3.0.3
- @fullhuman/postcss-purgecss                 ^4.0.3  →   ^5.0.0
- @vue/cli-plugin-babel                      ^4.5.13  →   ^5.0.8
- @vue/cli-plugin-eslint                     ^4.5.13  →   ^5.0.8
- @vue/cli-plugin-router                     ^4.5.13  →   ^5.0.8
- @vue/cli-plugin-unit-jest                  ^4.5.13  →   ^5.0.8
- @vue/cli-plugin-vuex                       ^4.5.13  →   ^5.0.8
- @vue/cli-service                           ^4.5.13  →   ^5.0.8
- @vue/test-utils                      1.0.0-beta.31  →   2.2.10
- axios                                      ^0.21.4  →   ^1.3.3
- bootstrap                                   ^4.6.0  →   ^5.2.3
- chalk                                       ^4.1.2  →   ^5.2.0
- core-js                                    ^3.18.1  →  ^3.28.0
- eslint                                      ^6.7.2  →  ^8.34.0
- eslint-plugin-vue                           ^6.1.2  →   ^9.9.0
- fontfaceobserver                            ^2.1.0  →   ^2.3.0
- html2canvas                                 ^1.3.2  →   ^1.4.1
- jest                                       ^25.5.4  →  ^29.4.2
- jest-canvas-mock                            ^2.3.1  →   ^2.4.0
- jquery                                      ^3.6.0  →   ^3.6.3
- js-yaml                                    ^3.14.1  →   ^4.1.0
- jsdom                                      ^16.7.0  →  ^21.1.0
- jspdf                                       ^2.4.0  →   ^2.5.1
- markdown-it                                ^11.0.1  →  ^13.0.1
- moment                                     ^2.29.1  →  ^2.29.4
- portal-vue                                  ^2.1.7  →   ^3.0.0
- postcss-preset-env                          ^6.7.0  →   ^8.0.1
- sass                                       ^1.42.1  →  ^1.58.1
- sass-loader                                 ^8.0.2  →  ^13.2.0
- vue                                        ^2.6.14  →  ^3.2.47
- vue-markdown-loader                         ^2.4.1  →   ^2.5.0
- vue-router                                  ^3.5.2  →   ^4.1.6
- vue-template-compiler                      ^2.6.14  →  ^2.7.14
- vuex                                        ^3.6.2  →   ^4.1.0
-```
+# Shortpoet — Resume & Articles
 
-## deploy
+Live: <https://shortpoet.com>
 
-```bash
-aws_assume_role
-export CLOUDFLARE_API_TOKEN=$(pass Cloud/cloudflare/Terraform_Token)
-```
+## Purpose & Context
 
-## cloudflare
+**What**: Personal portfolio site showcasing Carlos Soriano's professional experience and technical expertise.
 
-```bash
-terraform import cloudflare_zone.shortpoet d4e2...
-```
+**Why**: Multilingual résumé platform with PDF export for professional networking, recruitment, and career opportunities.
+
+**How**: Vue 3 SSG with article authoring, i18n support (18+ languages), and print-friendly views.
+
+**For Whom**: Recruiters, potential employers, technical collaborators, and professional contacts.
+
+Vue 3 + Vite SSG site for a multilingual résumé, PDF export, and a small articles section rendered from Markdown. Infra is managed separately via Terraform and deployed with GitHub Actions.
+
+## Project Structure
+
+- `app/`: Frontend app (Vue 3, Vite, vite-ssg).
+  - `app/src/views/`: Main pages (`Landing`, `Start` at `/resume`, `PDF`, `About`, `Articles`).
+  - `app/src/components/`: Feature components (Landing, Articles, PDF, etc.).
+  - `app/locales/`: i18n resources (default `en`).
+  - `app/public/`: Static assets. Build output: `app/build/`.
+- `.iac/`: Infrastructure-as-code (Cloudflare/AWS). See “Infra”.
+- `.github/workflows/`: Build/deploy pipelines for app and infra.
+
+## Getting Started
+
+Prereqs: Node 18+ and pnpm (CI uses pnpm 10; local 7+ works).
 
 ```bash
-get_cloudflare_record_id() {
-  zones=$(curl -X GET "https://api.cloudflare.com/client/v4/zones/$(pass Cloud/cloudflare/zone_id)/dns_records" \
-    -H "Content-Type:application/json" \
-    -H "Authorization: Bearer $(pass Cloud/cloudflare/Terraform_Token)")
-  echo $zones | jq -r '.result[] | select(.name == "dev.shortpoet.com") | .id'
-  echo $zones | jq -r '.result[] | select(.name == "shortpoet.com") | .id'
-}
+cd app
+pnpm i           # install
+pnpm dev         # start dev server on :8888
+pnpm build       # SSG build to app/build
+pnpm preview     # preview local build
+pnpm test        # unit tests (Vitest)
+pnpm lint        # ESLint + Prettier
+pnpm type-check  # TS checks
 ```
 
-## instructions
+## Notes on Testing & Linting
+
+- Unit tests run with Vitest (jsdom). Default glob is `test/**/*.test.ts` (update if you prefer colocated `*.spec.ts`).
+- Legacy Jest config exists, but `pnpm test` uses Vitest by default.
+- ESLint config: `app/.eslintrc.esm`; Prettier: `app/.prettierrc.json`.
+
+## Routing & Content
+
+- Routes: `/` (Landing), `/resume` (interactive résumé), `/pdf` (print-friendly), `/about`, `/articles` (redirects to first post).
+- Articles authored in Markdown with Shiki highlighting; see `app/src/components/Articles/Content`.
+- NProgress and i18n registered via user modules in `app/src/modules/`.
+
+## CI/CD & Infra
+
+- App build/deploy: [`.github/workflows/infra-app.yml`](.github/workflows/infra-app.yml) (reusable workflow). Uses pnpm 10, Node latest, outputs zipped from `app/build`.
+- Base infra: [`.github/workflows/infra-base.yml`](.github/workflows/infra-base.yml).
+- Terraform & linting live under [`.iac/`](.iac/) with TFLint configured in [`.tflint.hcl`](.tflint.hcl).
+- Deployment targets: Cloudflare (primary), AWS (secondary) via GitHub Actions.
+- Optional: install pre-commit hooks to lint Terraform and inject docs blocks: `pre-commit install`.
+
+## SEO tip
+
+Sitemap currently emits `http://localhost` links. Set a hostname in `vite.config.ts` (vite-ssg-sitemap) for production, e.g. `generateSitemap({ hostname: 'https://shortpoet.com', outDir: 'build' })`.
+
+## Troubleshooting
 
-- on dev
+- **pnpm version**: Local development works with pnpm 7+ (tested with 7.27.1), but CI uses pnpm 10.
+- **Test runner**: `pnpm test` uses Vitest by default; legacy Jest config exists but is not the primary runner.
+- **Production site**: Requires JavaScript - site shows message if JS is disabled.
+- **Sitemap URLs**: Production sitemap shows `localhost` URLs due to missing hostname config in `vite.config.ts`.
 
 <!-- BEGIN_TF_DOCS -->
 ## Requirements

diff --git a/app/.vscode/extensions.json b/app/.vscode/extensions.json
@@ -1,3 +1,5 @@
 {
-  "recommendations": ["Vue.volar", "Vue.vscode-typescript-vue-plugin"]
-}
+  "recommendations": [
+    "Vue.vscode-typescript-vue-plugin"
+  ]
+}
diff --git a/app/README.md b/app/README.md
@@ -1,46 +1 @@
 # shortpoet
-
-This template should help get you started developing with Vue 3 in Vite.
-
-## Recommended IDE Setup
-
-[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
-
-## Type Support for `.vue` Imports in TS
-
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) to make the TypeScript language service aware of `.vue` types.
-
-If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669) that is more performant. You can enable it by the following steps:
-
-1. Disable the built-in TypeScript Extension
-    1) Run `Extensions: Show Built-in Extensions` from VSCode's command palette
-    2) Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)`
-2. Reload the VSCode window by running `Developer: Reload Window` from the command palette.
-
-## Customize configuration
-
-See [Vite Configuration Reference](https://vitejs.dev/config/).
-
-## Project Setup
-
-```sh
-npm install
-```
-
-### Compile and Hot-Reload for Development
-
-```sh
-npm run dev
-```
-
-### Type-Check, Compile and Minify for Production
-
-```sh
-npm run build
-```
-
-### Lint with [ESLint](https://eslint.org/)
-
-```sh
-npm run lint
-```