Skip to content

AGENTS.md

Latest commit

 

History

History
145 lines (118 loc) · 7.02 KB

AGENTS.md

File metadata and controls

145 lines (118 loc) · 7.02 KB
Raw

AGENTS

This file is for automated coding agents working in this repo.

Project Snapshot

  • Hexo theme implementation with browser JS in source/js/**, Hexo Node scripts in scripts/**, and Stylus/Tailwind CSS in source/css/**.
  • Build outputs are committed to source/js/build/** and source/css/build/tailwind.css.
  • The theme config lives in _config.yml and is exported at build/runtime by scripts/config-export.js.

Environment & Tooling

  • Package manager: npm (CI uses npm install).
  • Node versions seen in CI: 20.x for build, 18 for release workflows.
  • No TypeScript, no test runner configured.

Commands (Build / Lint / Test)

  • Install deps: npm install.
  • Build all assets: npm run build (runs CSS + JS builds).
  • Build CSS only: npm run build:css (Tailwind CLI).
  • Build JS only: npm run build:js (minifies into source/js/build).
  • Watch CSS: npm run watch:css.
  • Pre-commit hook blocks committing build outputs on non-main/dev branches (see .husky/pre-commit).
  • Lint: no npm script or config present; add one if needed.
  • Tests: no test runner configured.
  • Single test: N/A (no unit/integration test tooling configured).
  • Manual verification (if you have a Hexo site): hexo clean && hexo g in the site repo.

Generated Assets (Do Not Edit Directly)

  • source/css/build/tailwind.css is generated from source/css/tailwind.source.css.
  • source/js/build/** is generated by source/js/build.js (Terser minification + lib copy).
  • If you touch source/js/** or source/css/**, rerun npm run build for verification. Build outputs are committed by CI on dev/main after merge.

JavaScript Style (Browser: source/js/**)

  • Module system: ES modules with import/export; keep imports at top.
  • Formatting: 2-space indentation, semicolons, double quotes.
  • Prefer const; use let only when reassigning.
  • Use trailing commas in multi-line objects/arrays/params (matches existing files).
  • Naming: camelCase for variables/functions, PascalCase for classes, UPPER_SNAKE_CASE for constants.
  • Init patterns: exported functions commonly named initX, onX, handleX.
  • Guards: early returns for invalid inputs or missing DOM nodes.
  • Optional chaining and nullish coalescing are used; keep null-safe checks.
  • Event listeners: prefer { signal } and pass an AbortSignal when available.
  • Side effects: keep in onReady/onPageView hooks or explicit init functions.

JavaScript Style (Hexo/Node: scripts/**)

  • Module system: CommonJS with require(...) and "use strict"; at top.
  • Use hexo.extend.* APIs (helpers, filters, events) as seen in existing scripts.
  • Keep functions small and mostly pure; use try/catch around external data parsing.
  • Avoid direct DOM usage here; this layer runs in Node during Hexo build.

Error Handling & Logging

  • Use try/catch for unsafe operations (JSON/YAML parsing, URL parsing, fetch).
  • Log with console.warn/console.error for non-fatal failures.
  • Prefer to return early after logging; avoid throwing unless it should break the build.

Styling (Stylus + Tailwind)

  • Stylus files use // comments and section separators; mirror existing structure.
  • Variables use $ prefix and hyphenated names (see source/css/common/variables.styl).
  • Reuse mixins like redefine-tablet() and redefine-mobile() for breakpoints.
  • Read config in Stylus via hexo-config('path.to.setting').
  • Class naming: favor existing kebab-case classes and theme-specific names.
  • Tailwind source lives in source/css/tailwind.source.css; never edit the generated file.

Configuration/Data Flow

  • _config.yml is the theme config; new options should be exported in scripts/config-export.js.
  • scripts/config-export.js writes window.config, window.theme, and language data into the page.
  • Keep JS code resilient to missing config by using optional chaining and defaults.

Imports & Dependencies

  • Prefer local relative imports within source/js/**.
  • Keep import lists grouped by path depth; avoid reordering unless needed.
  • Avoid adding new dependencies unless required; check impact on Hexo users.

Files & Naming Conventions

  • Browser JS filenames are mostly camelCase.js (e.g., homeBanner.js).
  • Hexo script filenames often use kebab-case.js (e.g., config-export.js).
  • Keep new files in the same naming style as their folder.

Content & i18n

  • Language files live in languages/** and are loaded by scripts/config-export.js.
  • If you add new UI strings, update the language YAMLs accordingly.

CI/Automation Notes

  • GitHub Actions build workflow runs npm run build on main/dev changes to JS/CSS.
  • CI commits updated build assets back to the branch when they change.

Contribution Notes (from CONTRIBUTING.md)

  • PRs should target the dev branch.
  • Commit message format: [section]: [brief info] (example: footer: optimize style).
  • Test changes locally before opening a PR.

Cursor/Copilot Rules

  • No .cursor/rules/, .cursorrules, or .github/copilot-instructions.md found in this repo.

Suggested Agent Workflow

  • Locate relevant source in source/js/**, source/css/**, or scripts/**.
  • Make changes in source files, not generated build outputs.
  • Run npm run build to refresh compiled assets.
  • If you cannot run builds, state the missing verification in your report.

Quick Pointers

  • Main client entry: source/js/main.js.
  • JS build script: source/js/build.js.
  • Tailwind entry: source/css/tailwind.source.css.
  • Core Stylus vars: source/css/common/variables.styl.
  • Hexo helper for config export: scripts/config-export.js.

Notes for Single-Test Requests

  • There is no test framework configured, so single-test execution is not applicable.
  • If a test runner is added later, document the exact single-test command here.

Guardrails for Agents

  • Keep changes minimal and consistent with existing style.
  • Do not edit auto-generated build files by hand.
  • Preserve license headers or top-of-file banners when present.
  • Avoid adding non-ASCII characters unless the file already uses them.

When Updating CSS/JS

  • Update source/js/** or source/css/** first.
  • Rebuild with npm run build for verification.
  • Build outputs are committed by CI on dev/main after merge.

When Adding New Config Options

  • Add defaults in _config.yml.
  • Export them in scripts/config-export.js.
  • Consume with optional chaining and defaults in JS.
  • Consider adding Stylus variables via hexo-config() if needed.

When Modifying Hexo Filters/Helpers

  • Keep functions pure and avoid heavy computation in filters.
  • Use defensive checks for config and data fields.

When Modifying UI Behavior

  • Keep init logic in init* functions and register via lifecycle hooks.
  • Use AbortSignal or cleanup patterns to avoid duplicate listeners.

Security/Privacy

  • Do not log or expose user secrets from _config.yml.
  • Treat external URLs as untrusted; validate before use where possible.

Docs

End

  • Keep this file updated when tooling or conventions change.