Skip to content

AGENTS.md

Latest commit

 

History

History
122 lines (84 loc) · 4.67 KB

AGENTS.md

File metadata and controls

122 lines (84 loc) · 4.67 KB
Raw

cosmic-containers — Agent Instructions

Layer boundaries: imports flow one direction only (utils → services → commands → extension). Extract to a shared module when logic is duplicated 2+ times.

Don't touch: target/**

For numeric thresholds (line count, function length, complexity, etc.) run Ctrl+Alt+F — values live in VS Code settings, not here.

Overview

Rust crate (cosmic-containers): Cosmic Containers — COSMIC panel applet for Pop!_OS that lists and starts/stops Docker containers via CLI (libcosmic, cosmic::applet::run). Binary requires feature applet, Docker in PATH, and system Wayland/GTK-related dev packages. See README.md for install and “Add widget” steps.

Chat language: Reply to the user in Ukrainian unless they ask for another language. Keep code, identifiers, commits, and this file in English.

When requirements are unclear, ask once with concrete options rather than guessing architecture.

Tech Stack

Item Value
Language Rust
Edition 2024 (Cargo.toml)
Package manager Cargo
Build output target/ (gitignored)

Commands

# Build (debug)
cargo build

# Run applet (COSMIC session, requires system deps + --features applet)
cargo run --release

# Release build
cargo build --release

# Check without full link
cargo check

# Format
cargo fmt

# Lint
cargo clippy

Prefer cargo check for fast feedback during edits; run cargo build or cargo run before claiming a change works.

Code Style

  • Match existing style: minimal, direct Rust without premature abstractions.
  • Keep diffs small; do not refactor unrelated code in the same change.
  • Prefer Result and explicit error handling over unwrap() in non-trivial paths.
  • Use cargo fmt before finishing; keep Cargo.toml dependencies justified.
  • Comments only for non-obvious behavior; let names and types carry intent.

Architecture

cosmic-containers/
  AGENTS.md              # This file
  Cargo.toml             # `applet` feature → libcosmic
  src/lib.rs             # APP_ID, ContainerSummary, parse_ps_output
  src/main.rs            # cosmic::applet::run
  src/app.rs             # Application impl (panel + popup)
  src/services/docker.rs # async docker CLI
  resources/             # .desktop, metainfo, icon
  scripts/install-local.sh
  .githooks/
  .cursor/skills/

Panel UI lives in src/app.rs; parsing and types in src/lib.rs; Docker in src/services/docker.rs. Register applets with X-CosmicApplet=true in resources/*.desktop.

Testing

  • Do not add tests unless the user asks or they cover real, non-trivial behavior.
  • Pre-commit (when configured): cargo test runs via SnakeFlow custom checks in .vscode/settings.json.
  • After adding tests, run cargo test before claiming the change works.

Security

Never: commit target/, secrets, API keys, or machine-specific paths in agent context files.

Always: read Cargo.toml and relevant src/**/*.rs before proposing changes; justify new dependencies in Cargo.toml.

PR / Commit

  • Create commits only when the user explicitly asks.
  • Do not force-push to main/master or skip hooks (--no-verify) unless the user explicitly requests it.
  • Pre-commit hook: .githooks/pre-commit (SnakeFlow). Requires SnakeFlow extension CLI when installed; otherwise exits 0.

Agent Workflows

  1. Read Cargo.toml and relevant src/**/*.rs before proposing changes.
  2. Implement the smallest change that satisfies the request.
  3. Verify with cargo check (minimum) or cargo run when behavior matters.

Dev environment (SnakeFlow): use .cursor/skills/setup-dev-manager/SKILL.md. Fetch live docs from https://snakeflow.pages.dev/getting-started/cursor-setup-skill/ when configuring devManager.* in .vscode/settings.json.

Verify / Acceptance

Before marking work done:

Step Command
Fast compile check cargo check
Format cargo fmt --check
Lint (if enabled in pre-commit) cargo clippy -- -D warnings
Tests (if present / requested) cargo test
Run behavior cargo run when output or CLI behavior matters

Pre-Planning Protocol

For non-trivial work:

  1. Clarify: ask focused questions about scope, target platform (desktop integration vs CLI), and error-handling expectations before coding.
  2. Test plan: decide whether cargo check, cargo test, or cargo run proves the change; note any manual steps on Pop!_OS if relevant.
  3. Read first: Cargo.toml, src/main.rs, and any new modules touched; skip for trivial one-line fixes.