diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 5f1492d..cb9b5bd 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,10 +1,15 @@ +stages: + - build + - deploy + build: stage: build image: name: gcr.io/kaniko-project/executor:v1.23.2-debug entrypoint: [""] script: - - /kaniko/executor + - > + /kaniko/executor --context "${CI_PROJECT_DIR}" --dockerfile "${CI_PROJECT_DIR}/Dockerfile" --destination "${CI_REGISTRY_IMAGE}:${CI_COMMIT_BRANCH}" @@ -39,7 +44,8 @@ preview: - echo "Deploying branch preview..." - echo "Preview available at preview URL" needs: - - staging + - job: staging + optional: true artifacts: paths: - public diff --git a/AGENTS.md b/AGENTS.md index a5608b3..2d9fcd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,80 +1,46 @@ -# Agent Instructions for Anson's Projects +# Repository Guidelines -This repository contains a multi-language technical blog with Rust automation tools, Julia data analysis notebooks, and Quarto documentation. +## Project Structure & Module Organization +- `ghost-upload/`: Rust automation for Ghost CMS publishing. +- `posts/`: Quarto posts with Julia/Python code per post directory. +- `public/`: Quarto build output (generated by `quarto render`). +- Root: Quarto config (`_quarto.yml`), shared assets, CI/CD, docs. -## Build/Lint/Test Commands +## Build, Test, and Development Commands +- Rust (`ghost-upload/`): + - Build: `cd ghost-upload && cargo build` + - Run: `cd ghost-upload && cargo run` + - Test: `cd ghost-upload && cargo test` (single: `cargo test `) + - Lint: `cd ghost-upload && cargo clippy` + - Format: `cd ghost-upload && cargo fmt` +- Julia (root or `posts/*/`): + - Packages: `julia -e "using Pkg; Pkg.instantiate()"` + - Precompile: `julia -e "using Pkg; Pkg.precompile()"` + - Run notebook/script: `julia .jl` +- Quarto (docs/site): + - Build site: `quarto render --to html --output-dir public` + - Preview: `quarto preview` + - Check: `quarto check` +- Docker: `docker build -t projects .` then `docker run projects` -### Rust (ghost-upload/) -- **Build**: `cd ghost-upload && cargo build` -- **Run**: `cd ghost-upload && cargo run` -- **Test**: `cd ghost-upload && cargo test` -- **Lint**: `cd ghost-upload && cargo clippy` -- **Format**: `cd ghost-upload && cargo fmt` -- **Single test**: `cd ghost-upload && cargo test ` +## Coding Style & Naming Conventions +- Rust: `cargo fmt`; fix all `cargo clippy` warnings. Use `?` over `unwrap()`. Imports: std → external → local. Naming: snake_case (fn/vars), PascalCase (types). Public docs with `///`. +- Julia: 4-space indent; spaces around operators; group `using` at top; snake_case; prefer pipelines `|>` for DataFrames; handle expected errors with try-catch. +- Quarto: Include title/date in YAML; set `echo: false`, `warning: false` for clean outputs; descriptive figure captions and alt text. -### Julia (posts/*/ and root) -- **Run notebook**: `julia .jl` -- **Package management**: `julia -e "using Pkg; Pkg.instantiate()"` -- **Precompile**: `julia -e "using Pkg; Pkg.precompile()"` +## Testing Guidelines +- Rust: Unit tests for core logic; add integration tests for API calls. Run with `cargo test`. Organize tests near code or in `tests/`. +- Julia: Validate transformations and plots visually; keep scripts deterministic. +- Quarto: Manually review rendered HTML for links, figures, and warnings. -### Quarto (Documentation) -- **Build site**: `quarto render --to html --output-dir public` -- **Preview**: `quarto preview` -- **Check**: `quarto check` +## Commit & Pull Request Guidelines +- Commits: Use clear, conventional messages (e.g., `feat:`, `fix:`, `docs:`). Scope small and focused. +- PRs: Provide description, linked issues, steps to validate (commands), and screenshots of rendered docs when relevant. -### Docker -- **Build**: `docker build -t projects .` -- **Run**: `docker run projects` +## Security & Configuration +- Environment variables: `kagi_api_key`, `admin_api_key`. Export locally (e.g., `export admin_api_key=...`); never commit secrets. +- Dependencies: Keep minimal and up-to-date. Prefer configuration via env vars over hardcoded values. -## Code Style Guidelines +## CI/CD & Deployment +- GitLab CI builds Docker, renders Quarto to static hosting; Rust runs separately for content sync. Avoid pipeline changes unless necessary; include rationale in PRs if modified. -### Rust -- **Formatting**: Use `cargo fmt` (4-space indentation, standard Rust style) -- **Linting**: Use `cargo clippy` and fix all warnings -- **Imports**: Group by standard library, external crates, then local modules -- **Error Handling**: Prefer `?` operator over `unwrap()`, use custom error types for complex cases -- **Naming**: snake_case for functions/variables, PascalCase for structs/enums -- **Documentation**: Use `///` for public APIs, `//` for implementation details -- **Async**: Use `async fn` for async functions, avoid blocking operations in async contexts - -### Julia -- **Formatting**: 4-space indentation, spaces around operators -- **Imports**: Use `using` for packages, group at top of file -- **Naming**: snake_case for functions and variables -- **Types**: Use descriptive names, consider performance implications -- **Plotting**: Use Plots.jl with consistent themes (e.g., `theme(:ggplot2)`) -- **DataFrames**: Use pipe operators `|>` for data transformations -- **Error Handling**: Use try-catch blocks for expected errors - -### Quarto (.qmd files) -- **YAML frontmatter**: Include title, date, and relevant metadata -- **Code chunks**: Use appropriate language engines (`{rust}`, `{julia}`, `{python}`) -- **Output**: Set `echo: false` for clean output, `warning: false` to suppress warnings -- **Figures**: Use descriptive captions and alt text -- **Citations**: Use `@citekey` format with bibliography files - -### General -- **Git**: Write clear commit messages, use conventional commits when possible -- **Documentation**: Update README.md for significant changes -- **Dependencies**: Keep dependencies minimal and up-to-date -- **Security**: Never commit API keys or sensitive credentials -- **Performance**: Profile code before optimizing, focus on readability first - -## Project Structure -- `ghost-upload/`: Rust automation for blog post publishing -- `posts/`: Individual blog posts (Quarto markdown + Julia/Python code) -- Root: Quarto website configuration and shared assets - -## Environment Variables -- `kagi_api_key`: For Kagi API summarization (Rust) -- `admin_api_key`: For Ghost CMS API (Rust) - -## Testing Strategy -- **Rust**: Unit tests for core functionality, integration tests for API interactions -- **Julia**: Visual validation of plots and data transformations -- **Quarto**: Manual review of rendered output and links - -## Deployment -- Uses GitLab CI/CD with Docker -- Deploys to static hosting after Quarto build -- Rust component runs separately for content synchronization \ No newline at end of file diff --git a/ghost-upload/.gitlab-ci.yml b/ghost-upload/.gitlab-ci.yml index c313ee3..56c4879 100644 --- a/ghost-upload/.gitlab-ci.yml +++ b/ghost-upload/.gitlab-ci.yml @@ -12,7 +12,8 @@ publish: needs: - job: deploy optional: true - - staging + - job: staging + optional: true # Manual trigger to force update all Ghost posts force-update-ghost: @@ -25,7 +26,8 @@ force-update-ghost: needs: - job: deploy optional: true - - staging + - job: staging + optional: true rules: - when: manual allow_failure: false