Skip to content

AGENTS.md

Latest commit

 

History

History
368 lines (274 loc) · 15 KB

AGENTS.md

File metadata and controls

368 lines (274 loc) · 15 KB

AGENTS.md

Purpose

This document describes the automated agents, CI/CD workflows, test runners, and helper scripts used by the SmarkForm project. It explains what runs automatically, where configuration lives, how to run things locally, and how to add or change automation safely.

Overview

  • Playwright test runner: end-to-end and co-located docs example tests.
  • Collector: script that extracts docs examples into a manifest used by tests.
  • Build & bundle agents: rollup-based bundling and scripts to produce dist/.
  • Documentation build and deploy: Jekyll site, built locally or via GitHub Pages workflow.
  • Local live-serve helpers: scripts to run dev servers and watchers.
  • GitHub Pages workflow: deploy docs site from stable branch.
  • Dependabot: monitors npm (devDependencies) and GitHub Actions to propose updates.

Agent Behavior Preferences

  • Default to opening a PR for all changes unless the user explicitly says otherwise. Always use report_progress to commit and push changes to a PR branch.

  • Make step commits: When several steps are specified in the task, make at least one commit per each step. In case of bug fixes, a commit with failing tests should come first, then a commit with the fix, and finally a commit with documentation updates, etc... if needed. These are minimums: There can be more intermediate commits if it makes sense to break down the work into smaller steps or there is something that needs to be fix in an already committed change, but there should not be fewer than one commit per step.

Reference to Future Work

To ensure coding agents (and contributors alike) make the best decisions while solving current tasks, we maintain a detailed PROMPTS.md file. This file serves as:

  1. A detailed TODO list for future work and improvements.
  2. A brainstorming space where ideas can be drafted, refined, and polished into implementable tasks.
  3. A prompt storage space for developing AI-assisted tasks and identifying interdependencies between them before starting code implementation.

Contributors and agents are encouraged to review the PROMPTS.md file when tackling significant changes or planning enhancements. This ensures all work aligns with upcoming goals and avoids duplication or divergent strategies.

Find the file at: PROMPTS.md

Quick checklist (update AGENTS.md when these change)

When you change or add any of the following, please update this file to reflect the change:

  • package.json scripts (build, test, pretest, dev)
  • playwright.config.js or files under test/
  • scripts/* (collector, build scripts, live-serve helpers)
  • rollup.config.js or rollup-plugins/
  • docs/ content, co-located examples, or test collection logic
  • .github/workflows/* (CI / Pages deployment)

For convenience, include this exact sentence in the PR description when you want the assistant to update AGENTS.md automatically:

"Please update AGENTS.md to reflect the changes in this PR."

Detailed Component Documentation

Playwright Test Runner

What it does: Runs end-to-end tests against the built distribution files and validates documentation examples.

Configuration: playwright.config.js

Test location: test/ directory

How to run locally:

npm test            # all browsers + chromium-mobile (full matrix, default)
npm run test:quick  # one randomly-chosen browser (fast, non-deterministic)

Key details:

  • Test files match pattern: **/*.tests.js
  • npm test runs the full matrix: chromium, firefox, webkit, and chromium-mobile (Pixel 5 emulation)
  • npm run test:quick picks one project at random (see scripts/test_quick.sh) — useful for a fast sanity check without committing to a specific browser
  • Generates HTML reports
  • Screenshots and traces captured on failure
  • forbidOnly enabled in CI to prevent .only commits
  • Mobile project (chromium-mobile) uses Playwright's Pixel 5 device emulation to catch Android/Brave-specific bugs

Troubleshooting:

  • If tests fail, check playwright-report/index.html for detailed reports
  • Use npm run test:pick to run specific test files (auto-discovers all projects including mobile)
  • Ensure npm run build completes successfully before testing

Collector Script

What it does: Extracts documentation examples into a manifest file that Playwright tests use to validate examples.

Location: scripts/collect-docs-examples.js

How to run locally:

node scripts/collect-docs-examples.js

Key details:

  • Runs automatically as part of npm run pretest
  • Scans docs/ for co-located examples
  • Creates a manifest used by test suite

Troubleshooting:

  • If tests can't find examples, re-run the collector
  • Check that example files exist in docs/ structure

Build & Bundle Agents

What they do: Bundle the source code using Rollup to produce ESM and UMD distributions in dist/.

Configuration: rollup.config.js, rollup-plugins/

How to run locally:

# Production build
npm run build
# or
scripts/build_production_smarkform.sh

# Build everything (library + examples)
npm run bundle
# or
scripts/build_all.sh

# Watch mode for development
npm run watch
# or
scripts/livebuild_dev_smarkform.sh

Key details:

  • Outputs: dist/SmarkForm.esm.js (ES module), dist/SmarkForm.umd.js (UMD)
  • Uses Babel for transpilation with decorators support
  • Minification via Terser
  • Cleanup plugin for code formatting
  • Custom Pug and Sass plugins for examples
  • Generates computed metadata (bundle size, last updated)

Troubleshooting:

  • If build fails, check Node.js version compatibility
  • Ensure all devDependencies are installed: npm install
  • Check rollup.config.js for plugin configuration issues
  • Review rollup-plugins/ for custom plugin errors

Documentation Build and Deploy

What it does: Builds the Jekyll documentation site from the docs/ directory.

Configuration:

  • Jekyll config: docs/_config.yml
  • Workflow: .github/workflows/pages.yml

How to run locally:

# Build docs site
npm run doc
# or
scripts/build_documentation_site.sh

# Serve docs with live reload
npm run servedoc
# or
scripts/liveserve_documentation_site.sh

# Run both library and docs in watch mode
npm run dev
# or
scripts/liveserve_all.sh

Key details:

  • Jekyll site in docs/ directory
  • Built package and examples copied into docs for deployment
  • package.json copied to docs/_data/ for Jekyll data files
  • Built examples copied to docs/_resources/

Troubleshooting:

  • If Jekyll fails, ensure Ruby and bundler are installed
  • Run bundle install in docs/ directory
  • Check Jekyll version compatibility
  • Review docs/Gemfile for dependencies

Auto Color Scheme Implementation

What it does: Provides automatic color scheme switching for the documentation site based on user's system preferences.

Configuration:

  • CSS: docs/assets/css/auto-color-scheme.css
  • JavaScript: docs/assets/js/auto-logo-switcher.js
  • Include: docs/_includes/head_custom.html
  • Documentation: docs/CUSTOMIZATION.md

How it works:

  • CSS media queries detect prefers-color-scheme and apply appropriate styles
  • JavaScript dynamically switches between light (smarkform.svg) and dark (smarkform_dark.svg) logos
  • Automatically updates when user changes system color scheme preference
  • No user configuration needed - works automatically

Key details:

  • Implemented because JustTheDocs 0.10.1 doesn't support color_scheme: auto
  • Dark mode colors match JustTheDocs dark theme for consistency
  • Supports modern browsers (Chrome 76+, Firefox 67+, Safari 12.1+)
  • Falls back to light mode in older browsers
  • Includes styles for all common elements (code blocks, tables, links, buttons, etc.)

Customization files:

  • docs/assets/css/auto-color-scheme.css - Color scheme styles
  • docs/assets/js/auto-logo-switcher.js - Logo switching logic
  • docs/_includes/head_custom.html - Loads custom CSS and JS
  • docs/CUSTOMIZATION.md - Full documentation

Testing:

  1. Build and serve the Jekyll site: npm run servedoc
  2. Open site in browser
  3. Change system color scheme preference
  4. Site should automatically update to match

Troubleshooting:

  • If colors don't change, check browser console for JavaScript errors
  • Verify CSS and JS files are loading in browser DevTools Network tab
  • Ensure head_custom.html is being included by Jekyll
  • Check browser supports prefers-color-scheme media queries

Local Live-Serve Helpers

What they do: Run development servers with live reload for rapid iteration.

Available scripts:

  • npm run watch / scripts/livebuild_dev_smarkform.sh - Watch library source
  • npm run servedoc / scripts/liveserve_documentation_site.sh - Serve docs with Jekyll
  • npm run dev / scripts/liveserve_all.sh - Run both library watcher and docs server

How to run locally:

# Development mode (both library and docs)
npm run dev

Key details:

  • Uses concurrently to run multiple processes
  • Library changes trigger automatic rebuilds
  • Documentation server provides live reload
  • Automatically stops any previously running instance on startup — running npm run dev in a different branch or worktree always cleanly terminates the previous server first, so you never accidentally test against the wrong build
  • Stop with Ctrl+C in the terminal where it was started

Troubleshooting:

  • If changes don't appear, check that watchers are running
  • Ensure ports are not already in use
  • Check console output for build errors

GitHub Pages Workflow

What it does: Automatically builds and deploys the documentation site to GitHub Pages when changes are pushed to the stable branch.

Configuration: .github/workflows/pages.yml

Trigger conditions:

  • Push to stable branch (not main)
  • Changes to docs/** paths
  • Manual workflow dispatch

Key steps:

  1. Checkout code
  2. Setup Ruby and install Jekyll dependencies
  3. Install npm dependencies (from docs directory with working-directory: docs)
  4. Build package with npm run build (executed from docs directory)
  5. Copy built files from parent directory to docs structure
  6. Build Jekyll site
  7. Upload and deploy to GitHub Pages

Note: The workflow sets working-directory: docs as the default, so npm commands execute from the docs directory.

Troubleshooting:

  • Check Actions tab in GitHub for workflow run details
  • Review workflow logs for build failures
  • Ensure stable branch is up to date
  • Verify GitHub Pages settings in repository configuration

Dependabot

What it does: Automatically creates pull requests to update npm dependencies (devDependencies) and GitHub Actions versions.

Configuration: .github/dependabot.yml

Monitored ecosystems:

  • npm - devDependencies in package.json
  • github-actions - Actions used in workflow files

Key details:

  • Checks daily for npm updates
  • Checks weekly for GitHub Actions updates
  • No runtime dependencies (only devDependencies)
  • Helps keep tooling and CI/CD up to date

How to manage:

  • Review PRs created by Dependabot
  • Test updates locally before merging
  • Check for breaking changes in changelogs
  • Merge updates regularly to avoid large batches

Troubleshooting:

  • If Dependabot PRs fail CI, review breaking changes
  • Check compatibility with Node.js version
  • Review package changelogs for migration guides
  • Test locally: npm install <package>@<version>

Configuration File Locations

Component Configuration File(s)
Playwright playwright.config.js
Rollup rollup.config.js, rollup-plugins/*
Jekyll docs/_config.yml, docs/Gemfile
GitHub Actions .github/workflows/pages.yml
Dependabot .github/dependabot.yml
npm scripts package.json (scripts section)
Example collector scripts/collect-docs-examples.js
Auto color scheme docs/assets/css/auto-color-scheme.css, docs/assets/js/auto-logo-switcher.js, docs/_includes/head_custom.html

Common Commands Reference

# Testing
npm test                    # Run full matrix: chromium + firefox + webkit + chromium-mobile
npm run test:quick          # Run on one randomly-chosen browser (fast sanity check)
npm run test:pick          # Run specific test file(s) interactively
npm run pretest            # Build and collect examples (runs before test / test:quick)

# Building
npm run build              # Build production library
npm run bundle             # Build library and examples
npm run watch              # Watch mode for library

# Documentation
npm run doc                # Build documentation site
npm run servedoc           # Serve docs with live reload
npm run dev                # Watch library + serve docs

# Utility
node scripts/collect-docs-examples.js  # Collect docs examples

Agent Knowledge Directory (AGENTS/)

The AGENTS/ directory at the repository root contains specialised knowledge files for coding agents. These files capture patterns, gotchas, and implementation details that are not obvious from reading the source code.

File Contents
AGENTS/SmarkForm-Usage.md Pointer to docs/_resources/AGENTS/SmarkForm-Usage.md — component types, list template roles, button context patterns, CSS grid layout, exportEmpties behaviour. Full content kept here for agents that need it without following a link.
AGENTS/SmarkForm-Forms.md Pointer to docs/_resources/AGENTS/SmarkForm-Forms.md — practical form implementation guide, CDN/npm/downloaded-copy consumption snippets, prompt templates, and an agent checklist
AGENTS/Documentation-Examples.md How the playground template works — demoValue, DOCS_ONLY_PARAMS, co-located test patterns, tips for harvesting realistic demo data

Agents should read the relevant AGENTS/ files before making changes to documentation examples, showcase forms, or anything involving SmarkForm component authoring.

Keeping AGENTS/ Up to Date

When you discover a new pattern, fix a bug caused by an undocumented constraint, or find that an existing entry in AGENTS/ is incorrect or incomplete:

  1. Update or create the relevant file in AGENTS/ as part of the same commit.
  2. Add new entries for anything you had to learn the hard way — gotchas, non-obvious constraints, error messages and their root causes.
  3. Correct inaccurate entries whenever you verify that something documented is wrong.
  4. You do not need a special PR description sentence to update AGENTS/ files — just do it as part of your normal work.

Updating This Document

This document should be kept up to date as automation changes. When you make changes to CI/CD, tests, build scripts, or other automation:

  1. Update the relevant section(s) in this file
  2. Test your changes locally
  3. Commit the AGENTS.md update with your changes

For automated updates: Include the sentence "Please update AGENTS.md to reflect the changes in this PR." in your PR description, and the GitHub Copilot Chat Assistant will update this file for you.