Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (64 loc) · 5.27 KB

AGENTS.md

File metadata and controls

80 lines (64 loc) · 5.27 KB
Raw

AGENTS.md

Commands

  • Install dependencies: poetry install
  • Build local Python package: poetry build
  • Build add-on from a package source: poetry run ucc-gen build --source <path-to-package>
  • Build add-on with verbose file state output: poetry run ucc-gen build --source <path-to-package> --verbose
  • Build add-on and custom UI together: poetry run ucc-gen build --source <path-to-package> --build-custom-ui
  • Initialize a new add-on skeleton: poetry run ucc-gen init --addon-name "<addon_name>" --addon-display-name "<display_name>" --addon-input-name <input_name>
  • Package a built add-on: poetry run ucc-gen package --path output/<addon_name>
  • Validate a built add-on with AppInspect integration: poetry run ucc-gen validate --addon-path output/<addon_name>
  • Run docs site locally: poetry run mkdocs serve -a localhost:8001
  • One-command backend/frontend/dev setup: ./scripts/quick_start_ui.sh
  • Build UI assets and copy into UCC static assets: ./scripts/build_ui.sh
  • UI workspace setup (run from ui/): yarn run setup
  • UI dev server (run from ui/): yarn start
  • UI production build (run from ui/): yarn build

Testing

  • Run Python unit tests: poetry run pytest tests/unit
  • Run smoke tests: poetry run pytest tests/smoke
  • Run UI end-to-end tests: poetry run pytest tests/ui
  • Run UI library tests (run from ui/): yarn run test
  • Run tests with coverage report: poetry run pytest tests/unit --cov splunk_add_on_ucc_framework --cov-report html
  • Run smoke tests with coverage report: poetry run pytest tests/smoke --cov splunk_add_on_ucc_framework --cov-report html
  • Coverage HTML output path: htmlcov/index.html
  • Make sure unit tests coverage does not decrease after changes made
  • Before running UI tests locally, build a sample add-on and start Splunk via ./scripts/run_splunk.sh as documented in docs/contributing.md.

Project Structure

  • splunk_add_on_ucc_framework/: core Python framework and ucc-gen command implementation.
  • tests/: unit, smoke, and UI pytest suites.
  • ui/: TypeScript UI library, Storybook, ESLint/Prettier workflows.
  • docs/: MkDocs source for user/developer documentation.
  • scripts/: helper scripts for local UI build/start and Splunk test environment.
  • assets/: project assets used by docs/workflows.
  • output/: generated add-on build outputs.
  • dist/: built distribution artifacts.
  • demo_addon_for_splunk/, demo_addon_for_splunk_already_exists/, init_addon_for_ucc_package/: sample/add-on fixture projects used for validation and demos.

Code Style

  • Run all Python lint/type hooks with: pre-commit run --all-files
  • Pre-commit is authoritative for Python checks and includes: black, mypy, flake8, pyupgrade, autoflake, and markdownlint.
  • Python formatting/lint baseline: Flake8 max line length is 120 (see .flake8).
  • Use Python 3.9+ compatible syntax for Python changes (pyupgrade --py39-plus is enforced).
  • For UI changes in ui/, run from ui/: yarn run eslint and yarn run format:verify (or yarn run eslint:fix / yarn run format when intentionally rewriting formatting).
  • yarn run setup in ui/ is a prerequisite before other UI yarn tasks.

Git Workflow

  • Default development branch is develop; open regular feature/fix/docs PRs against develop.
  • Use small PRs and include tests with bug fixes/features.
  • PR titles must follow Conventional Commits, e.g. feat(ui): add ..., fix(generator): ..., docs(...): ....
  • Regular PRs to develop should be merged via squash on GitHub.
  • Release PR flow is develop -> main with merge commit (not squash), then backport main -> develop with merge commit.
  • Use documented GitHub CLI commands in docs/contributing.md for release/backport PR creation and merge automation.

Boundaries

  • Do not hand-edit generated add-on artifacts under output/<addon_name>/...; regenerate with ucc-gen build.
  • Do not hand-edit docs/generated_files.md; it is generated by splunk_add_on_ucc_framework/generators/doc_generator.py. After changing generated-file descriptions, regenerate it via poetry run ucc-gen-docs.
  • Treat files documented in docs/generated_files.md as generated outputs (for example default/app.conf, default/inputs.conf, default/restmap.conf, default/web.conf, generated XML views/nav, alert files, and OpenAPI output).
  • Input scripts are regenerated on each build. Put custom modular input logic in helper modules (inputHelperModule) in bin/; those helper modules are preserved.
  • If you need custom .conf behavior, prefer providing source .conf files in the add-on default source location instead of patching generated output.
  • Avoid committing local runtime/cache artifacts such as .venv/, .pytest_cache/, .mypy_cache/, htmlcov/, and transient local output unless intentionally updating reproducible fixtures.
  • When changing commands, release flow, or test workflows, update docs/commands.md and/or docs/contributing.md in the same PR.

Operational Rules

GPG-Signed Commits

If git commit fails with gpg failed to sign the data, do not bypass with --no-gpg-sign or --no-verify. Instead:

  1. Stage files with git add as normal.
  2. Provide the user with the exact git commit command to run in their own terminal.
  3. Wait for confirmation before proceeding (push, MR creation, etc.).