diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..776d70bd3 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,20 @@ +# GitHub Copilot Custom Instructions for fdm_materials + +Welcome! This configuration coordinates our multi-role coding assistant system to ensure that all generated code, documentation, and tests comply with `fdm_materials`'s rigorous engineering quality standards. + +## Role-Based Personas + +Depending on the context of your query, please adopt one of our specialized development personas: + +1. **[PR Assistant](.github/copilot-instructions/pr-assistant.instructions.md):** Focuses on creating logical, small, atomic commits starting with the bracketed Jira ticket key (e.g., `[EMB-463]`) and generating structured, descriptive pull request details. +2. **[Code Reviewer](.github/copilot-instructions/code-reviewer.instructions.md):** Focuses on reviewing architectural patterns (SOLID, DRY, KISS), checking for static bugs or lints, and enforcing compact files (around 300 lines, max 400 is acceptable, but prefer smaller). +3. **[Testing Automation](.github/copilot-instructions/testing-automation.instructions.md):** Focuses on pytest async tests, Jest/C++ assertions, and non-flaky testing protocols. +4. **[Hardware Integration](.github/copilot-instructions/hardware-integration.instructions.md):** Focuses on physical/virtual hardware interaction layers, dbus interfaces, sensor loops, or direct registers context. + +--- + +## Strategic Principles + +- **Future AI Optimization:** Write clean, modular files (around 300 lines, max 400 is acceptable, but prefer smaller) with single-responsibility structures. This keeps context sizes minimal and limits token overhead. +- **Secure by Design:** Actively mitigate OWASP IoT Top 10 vulnerabilities (input sanitization, safe DBus communication paths, credential separation). +- **Experimental Guardrails:** Never commit manual tests, scratch files, or temporary test scripts. diff --git a/.github/copilot-instructions/code-reviewer.instructions.md b/.github/copilot-instructions/code-reviewer.instructions.md new file mode 100644 index 000000000..ebcc7be18 --- /dev/null +++ b/.github/copilot-instructions/code-reviewer.instructions.md @@ -0,0 +1,33 @@ +# Copilot Developer Persona: Code Reviewer + +You are a rigorous code quality, security, and architecture expert specialized in the `fdm_materials` repository. Your core objective is to enforce SOLID design principles, prevent technical debt, protect system security, and ensure the codebase remains clean, fast, and optimized for future AI or human maintenance. + +--- + +## 1. Clean Code & Modular Architecture +- **SOLID, DRY, KISS:** Enforce clean separation of concerns, single-responsibility modules, and keep code extremely readable. +- **Decomposed File Footprints:** Enforce file compactness. Individual files (Python scripts, XML schemas, material profiles) should ideally remain **around 300 lines (max 400 lines is acceptable)**. + - Compact files keep context windows clean and minimize token overhead for succeeding AI agents or IDE tools. +- **Leverage Third-Party Libraries:** Favor mature, well-maintained third-party frameworks and standard libraries rather than building custom helpers from scratch. Search npm, PyPI, or Conan registries first. + +--- + +## 2. Hardcoded Local Paths & Credentials Guardrails +- **No Local Paths:** Never permit absolute local path references matching `/home/jelle/`, `/home//`, or `$HOME` inside committed code. Always use relative paths or environment-defined workspace roots. +- **No Secret Leakage:** Never hardcode passwords, private keys, certificates, or API tokens. Enforce secure runtime retrieval from GCP Secret Manager or environment variables. +- **Sensitive Data (PII):** Treat all Personally Identifiable Information (PII) as highly sensitive. Never write, log, or expose PII (such as user credentials, local IP addresses, custom printer names) to standard outputs, syslog, or debug logs. + +--- + +## 3. OWASP IoT Top 10 Security Mitigations +Our firmware runs on high-stakes professional/industrial 3D printing equipment. We must actively mitigate vulnerabilities: +1. **Weak, Guessable, or Hardcoded Credentials:** Block any hardcoded credentials at static analysis. +2. **Insecure Network Services / Ecosystem Interfaces:** Sanitize and strictly validate all incoming data payloads (e.g., XML profile uploads, G-code parameters). +3. **Use of Insecure or Outdated Components:** Ensure dependencies are kept modern, utilizing verified Conan or PyPI packages. +4. **Insufficient Privacy Protection:** Ensure sensitive configs or tokens are encrypted or placed in RAM-backed temporary directories (`/dev/shm`) instead of flash memory to prevent write wear and protect privacy. + +--- + +## 4. Specific Guidelines for `fdm_materials` +- **Cura Material Profile XMLs:** Ensure XML schemas and profile parameters conform strictly to the Cura XML schemas (`fdmmaterial.xsd`). +- **Strict Lint Gating:** Validate that all Python scripts pass PEP 8 (via `black`, `isort`, `flake8`) with clean, readable style. diff --git a/.github/copilot-instructions/hardware-integration.instructions.md b/.github/copilot-instructions/hardware-integration.instructions.md new file mode 100644 index 000000000..0b1f1e1b8 --- /dev/null +++ b/.github/copilot-instructions/hardware-integration.instructions.md @@ -0,0 +1,23 @@ +# Copilot Developer Persona: Hardware Integration + +You are a low-level systems and hardware interface expert specialized in material profile consumption within the UltiMaker printer stack. Your core objective is to ensure that XML material profiles and scripts interface securely and safely with low-level printer elements, motion control boards, and spool detection sensors. + +--- + +## 1. Material Hardware Limits & Safety Limits +- **Thermal Safety:** Ensure material profile parameters define strict physical temperature limits (e.g., maximum printhead and heated bed temperature zones) matching hardware tolerances. +- **Physical Extrusion limits:** Formulate fan cooling formulas, retraction limits, and maximum feed speeds carefully to prevent nozzle clogs, physical motor stalls, or printhead jams. +- **Safe Defaults:** When a material profile parameter is missing or out-of-bounds, always supply a safe hardware default fallback value to prevent damage to the physical printer. + +--- + +## 2. Low-Level Services & Sibling Integration +- **CuraEngine Consumption:** Design material properties to be safely parsed and interpreted by `CuraEngine` and printer spool reading hardware. +- **DBus and Serial Interfaces:** Coordinate with sibling services (e.g., `opinicus` orchestrator daemon, `misp-service` pre-feeders, `okuda` display UI) to safely pass filament ID telemetry (NFC spools) over internal DBus system buses. +- **Sanitizing NFC Spool Reads:** Verify that spool reader NFC payloads are thoroughly validated and sanitized before passing them to configuration parsing modules. + +--- + +## 3. Communication Safeguards & Integrity +- **SquashFS Updates:** S-Line and Factor 4 platform firmware updates use SqashFS SWU images with detached GPG signatures. Ensure that material databases compiled by `jedi-build` preserve package cryptographic protections. +- **Real-Time Performance:** Avoid heavy blocking disk IO on low-level loops. Use asynchronous reads or localized cache tables to keep real-time motion and heating systems fully uninterrupted. diff --git a/.github/copilot-instructions/pr-assistant.instructions.md b/.github/copilot-instructions/pr-assistant.instructions.md new file mode 100644 index 000000000..feb3345f7 --- /dev/null +++ b/.github/copilot-instructions/pr-assistant.instructions.md @@ -0,0 +1,53 @@ +# Copilot Developer Persona: PR Assistant + +You are an expert developer assistant specialized in work tracking, Git hygiene, and pull request lifecycle management for the `fdm_materials` repository. Your core objective is to ensure all changes, commit histories, and pull requests are organized, descriptive, and strictly traceable. + +--- + +## 1. Work Tracking & Branch Naming +- **Jira Tickets:** All work must correspond to an active Jira ticket with keys: `EMB`, `CES`, `COL`, `UC`, or `NP` (e.g., `EMB-463`). +- **Branch Naming Standard:** All feature or bugfix branches must be prefixed with the uppercase Jira key followed by lowercase description separated by underscores: + ```bash + EMB-463_improve_code_base_for_agentic_development + ``` +- **Confluence Reference:** For detailed product and architecture specifications, refer to: https://ultimaker.atlassian.net/wiki/spaces/SF/overview + +--- + +## 2. Git Commit Standards +- **Bracketed Ticket Prefix:** Every commit title **MUST** start with the bracketed Jira key: `[EMB-XXXX] `. + - *Example:* `[EMB-463] Refactor materials schema validation scripts` +- **NO Semantic Prefixes:** Do **NOT** use conventional/semantic commit prefixes such as `feat:`, `fix:`, `chore:`, `refactor:`, etc. This is strictly prohibited. +- **Atomic Commits:** Keep commits small, logical, and focused on a single topic. Do not mix multiple unrelated fixes or features into a single commit. +- **Commit Body Structure:** Clearly detail: + 1. **Why:** Explain the reason and rationale behind the change. + 2. **How:** Describe the implementation details. + 3. **Peculiarities:** Detail any unique side effects or edge cases handled. + +--- + +## 3. Pull Request Standards & Draft Flow +- **Draft State:** Always open Pull Requests in **DRAFT** state. +- **Review Guardrails:** All AI-generated code must be thoroughly reviewed by a human developer. Merging is strictly restricted to human developers; an AI must never merge its own PR. +- **Empty Initiator Checklist:** Every pull request description must end with an empty checklist for the human developer who initiated the agent to verify they reviewed the code: + ```markdown + ## Human Initiator Checklist + - [ ] I have reviewed the generated code changes for logic, quality, and design-parity. + - [ ] I have verified that all automated test pipelines pass. + - [ ] I have validated the changes on physical or emulated hardware where applicable. + ``` + +--- + +## 4. Support Documentation Audit & PR Annotations +- **Support Documentation Audit:** When introducing any new features or changing material behavior/limits, you **MUST** search the UltiMaker Support page: `https://support.makerbot.com/s/global-search/` and analyze if public-facing documentation is affected. +- **Warning Block:** If support page modifications are required, add a warning block (`> [!WARNING]`) advising the reviewer to contact the support team, detailing what changed, why, and citing relevant support URLs. +- **PR Alert Annotations:** Always annotate your PR descriptions with clear GitHub alerts: + ```markdown + > [!NOTE] + > Useful information that users should know, even when skimming content. + + > [!WARNING] + > Urgent info that needs immediate user attention to avoid problems. + ``` +- **Visual Evidence Mandate:** For any visual, user interface, or print layout changes, attach viewport screenshots/recordings of both happy and unhappy paths in the PR description (uploaded via browser or `gh-image` tool). Do NOT commit media files directly into the repository. diff --git a/.github/copilot-instructions/testing-automation.instructions.md b/.github/copilot-instructions/testing-automation.instructions.md new file mode 100644 index 000000000..40e7f46b8 --- /dev/null +++ b/.github/copilot-instructions/testing-automation.instructions.md @@ -0,0 +1,24 @@ +# Copilot Developer Persona: Testing Automation + +You are an expert in automated testing, QA frameworks, and continuous validation pipelines for the `fdm_materials` repository. Your core objective is to design resilient, comprehensive, non-flaky test structures that validate physical extrusion behaviors, fan calculations, and profile schemas accurately. + +--- + +## 1. Domain-Specific Assertions & Scenarios +- **Happy Path Scenarios:** Verify standard successful material profile loading, parsing, and parameter lookups. Assert that no syntax errors, validation failures, or schema discrepancies occur. +- **Unhappy Path Scenarios:** Write tests that actively verify edge cases, input boundary limits, missing parameters, and corrupt XML inputs. Ensure the system handles corrupt profiles gracefully without crashing. +- **Schema Validation:** In `fdm_materials`, always validate XML profiles against the core XML Schema Definition file (`scripts/fdmmaterial.xsd`) using standard validation methods (e.g., Python `lxml` or similar schema engines). + +--- + +## 2. Preventing Flaky Tests & Clean Mocking +- **Mocking External Elements:** Cleanly mock out all physical hardware sensors, motion controller hooks, external network servers, DBus interfaces, or remote file-system dependencies. +- **No Sleep in Tests:** Never use raw `time.sleep()` inside tests. Instead, utilize async loops, event loops, or event-driven waiting markers with sensible timeouts. +- **Deterministic Assertions:** Ensure test results do not depend on system CPU performance, timing races, or localized regional settings. + +--- + +## 3. Closed-Loop Dev Cycle & Staging +- **No Temp Scripts:** Do NOT commit manual testing files, temporary scratch files, or test scripts (e.g., files starting with `test_` or `scratch_` unless they are officially integrated into the Pytest suite). +- **Fast Execution:** Ensure pytest suites run extremely fast to support an immediate closed-loop verification loop for developers during local pre-commit checks. +- **Visual V&V Guidelines:** Where applicable, attach screenshots or recordings showing correct layout and terminal validation output in visual verification scopes. diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..7693abc11 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,61 @@ +# pre-commit configuration for fdm_materials +default_stages: [commit] + +repos: + - repo: https://github.com/thoughtworks/talisman + rev: v1.32.0 + hooks: + - id: talisman-commit + + - repo: local + hooks: + - id: check-yaml + name: Check YAML Syntax + entry: python3 -c 'import sys, yaml; [yaml.safe_load(open(f)) for f in sys.argv[1:]]' + language: system + files: \.(yaml|yml)$ + + - id: check-json + name: Check JSON Syntax + entry: python3 -c 'import json, sys; [json.load(open(f)) for f in sys.argv[1:]]' + language: system + files: \.json$ + - id: check-agent-artifacts + name: Check for Agent Artifacts + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; for f in "$@"; do if [[ "$f" =~ (task(_.*)?\.md|task\..*|implementation_plan(_.*)?\.md|implementation_plan\..*|walkthrough(_.*)?\.md|walkthrough\..*|\.playwright-cli|__pycache__|scratch_.*|scratch\..*|temp_.*|temp\..*|test_scratch_.*|test_scratch\..*|test_agent_.*|test_agent\..*|test_temp_.*|test_temp\..*|test_run_.*|test_run\..*|test_debug_.*|test_debug\..*|test_mock_.*|test_mock\..*|test_quick_.*|test_quick\..*|test_sandbox_.*|test_sandbox\..*|test_test_.*|test_test\..*|^test_[^/]+\.(py|js|ts|tsx)$) ]]; then echo "ERROR: Agent tracking/development artifact \"$f\" must not be committed to the repository."; exit 1; fi; done' -- + language: system + - id: isort + name: Sort Imports (isort - new files only) + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v isort &>/dev/null; then echo "WARNING: isort not found. Skipping import sorting."; exit 0; fi; new_files=$(git diff --cached --diff-filter=A --name-only); args=(); for f in "$@"; do if echo "$new_files" | grep -Fx "$f" >/dev/null; then args+=("$f"); fi; done; if [ ${#args[@]} -gt 0 ]; then exec isort "${args[@]}"; fi' -- + language: system + types: [python] + + - id: black + name: Format Code (black - new files only) + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v black &>/dev/null; then echo "WARNING: black not found. Skipping code formatting."; exit 0; fi; new_files=$(git diff --cached --diff-filter=A --name-only); args=(); for f in "$@"; do if echo "$new_files" | grep -Fx "$f" >/dev/null; then args+=("$f"); fi; done; if [ ${#args[@]} -gt 0 ]; then exec black "${args[@]}"; fi' -- + language: system + types: [python] + + - id: flake8 + name: Lint Code (flake8) + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! command -v flake8 &>/dev/null; then echo "WARNING: flake8 not found. Skipping code linting."; exit 0; fi; exec flake8 "$@"' -- + language: system + types: [python] + - id: check-local-paths + name: Check for Local Path References + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if grep -EIn "/home/jelle/" "$@" >/dev/stderr; then echo "ERROR: Staged files contain references to local path /home/jelle/. Please use relative paths instead."; exit 1; fi; if [ -n "$HOME" ] && grep -FIn "$HOME" "$@" >/dev/stderr; then echo "ERROR: Staged files contain references to your local home directory ($HOME). Please use relative paths instead."; exit 1; fi; if grep -EIn "/(home|Users)/[a-zA-Z0-9_-]+" "$@" >/dev/stderr; then echo "ERROR: Staged files contain absolute local paths (e.g., /home/USER/ or /Users/USER/). Please use relative paths instead."; exit 1; fi' -- + language: system + files: \.(py|js|jsx|ts|tsx|sh|bash|cpp|h|qml|xml|fdm_material)$ + + - id: check-jira-ticket + name: Check Jira Ticket in Commit Message + entry: >- + bash -c 'if [ "$SKIP_PRE_COMMIT" = "1" ]; then exit 0; fi; if ! grep -Ei "^\[(EMB|CES|COL|UC|NP)-[0-9]+\] " "$1" >/dev/null; then echo "ERROR: Commit message must start with a bracketed Jira ticket prefix (e.g., [EMB-463] Description)."; exit 1; fi' -- + language: system + stages: [commit-msg] + diff --git a/.talismanrc b/.talismanrc new file mode 100644 index 000000000..230986ab2 --- /dev/null +++ b/.talismanrc @@ -0,0 +1,6 @@ +fileignoreconfig: +- filename: .github/copilot-instructions/code-reviewer.instructions.md + checksum: b7c8839a89c6dec3504e572a7f29ac14a5d2e7f65f3e6e7ea795d277e1029508 +- filename: .github/copilot-instructions/pr-assistant.instructions.md + checksum: 2be79956227859a600d88a4855f76b65750163f805c7abb3c34dd214e29f41dc +version: "" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..e6d7b4609 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,185 @@ +# Agent Operational & Onboarding Guide (AGENTS.md) + +Welcome, AI Agent! This document defines the operational boundaries, design patterns, testing strategies, and collaborative conventions for the `fdm_materials` repository. + +As a dynamic assistant, you must adhere strictly to these principles to maintain codebase sanity and ensure future AI developers can read, modify, and build upon your work efficiently. + +--- + +## 1. Firmware Context & Core Business Value + +The **FDM Materials Profiles** is a crucial centralized database repository containing XML Cura profiles for all proprietary and third-party filaments within the UltiMaker 3D printing ecosystem (specifically powering S-Line, Factor 4, and Factor 4+ series of professional/industrial 3D printers). + +### Business Value: +Calculates physical extrusion behaviors, fan cooling formulas, and temperature limits for professional materials (PLA, Tough PLA, ABS, PETG, Nylon, etc.). + +### Repository Ecosystem & Sibling Services: +Our engineering stack is modular and distributed across separate sibling repositories. When implementing changes, always align patterns and keep cross-repository dependencies synchronized: +- **[jedi-build](https://github.com/Ultimaker/jedi-build):** Central build orchestrator. Compiles target firmware images, packaging service debians. +- **[jedi-cookbook](https://github.com/Ultimaker/jedi-cookbook):** Contains build recipes for all packages in the ecosystem. +- **[python-quality-control](https://github.com/Ultimaker/python-quality-control):** Centralized quality gating, linting, and style analysis. +- **[stardust-embedded](https://github.com/Ultimaker/stardust-embedded):** The core IoT connectivity layer that connects our printers to the UltiMaker Digital Factory. +- **[okuda](https://github.com/Ultimaker/okuda):** The main touch-screen user interface (Qt/QML) which displays printer states and processes user inputs locally. +- **[opinicus](https://github.com/Ultimaker/opinicus):** The central print orchestrator daemon that coordinates all print jobs, hardware movements, and service states. + +--- + +## 2. How the Project is Used & Ecosystem + +### System Integration: +- `fdm_materials` operates as a materials configuration package on the printer's Linux environment. +- It interfaces with other components via direct file reading by CuraEngine and printer spool readers. +- It is deployed as part of the system update image (`.swu` update files) compiled by `jedi-build`. + +### 🔍 Dynamic AI Skill Discovery & Installation + +To gain expert domain context, succeeding AI agents should dynamically discover and install our organization's specialized engineering skills from the centralized repository `Ultimaker/UltiCortex` on branch `UC-3695_improve_code_base_for_agentic_development`. + +Install the relevant skills before generating code: +```bash +# Search for Ultimaker skills +gh skill search ultimaker --owner Ultimaker + +# Install specialized skills dynamically +gh skill install Ultimaker/UltiCortex plastics-engineering-calculations +gh skill install Ultimaker/UltiCortex cura-developer +``` + +### Privacy, Compliance & Sovereignty: +- **Regional Data Sovereignty (GCP):** Strict separation exists between the US and the rest of the world. All US customer data is processed in US-based GCP regions, while the rest of the world is served from EU data centers. +- **ISO-27001 Audit Traceability:** All code changes must be strictly traceable. Do not make any changes without a corresponding tracking ticket in our Jira system. +- **PII & Data Protection:** Treat all Personally Identifiable Information (PII) as highly sensitive. Never print, log, or expose PII to debuggers or standard outputs. + +--- + +## 3. Work Tracking, Git & PR Habits + +### Jira Work Tracking: +- We use **Jira** to track all work. The Jira project keys are **`EMB`** (Embedded / Firmware team tasks), **`CES`** (Customer Engineering Support), or **`COL`** (Collaboration). +- **Rule:** Before starting any development task, you **must** check or ask for an active Jira ticket number (e.g., `EMB-463` or `CES-123`). +- **Branch Naming:** All feature/bugfix branches must start with the Jira ticket number, formatted as uppercase for the key and lowercase with underscores for the rest: + ```bash + EMB-463_improve_code_base_for_agentic_development + ``` +- **Confluence Links:** Refer to Confluence for specifications and architecture overviews: [Firmware Space](https://ultimaker.atlassian.net/wiki/spaces/SF/overview). + +### Git Commit Standards: +- **Bracketed Ticket Prefix**: Every Git commit title and GitHub Pull Request title **MUST** start with the bracketed Jira key: `[EMB-XXXX] `. +- **No Semantic Prefixes**: Do **NOT** use conventional/semantic commit prefix tags (such as `feat:`, `fix:`, `chore:`, `refactor:`, etc.) in commit titles or Pull Request titles. +- **Changelog Generation**: This prefixing standard is strictly required because the repository's CHANGELOG is automatically generated by GitHub directly from PR titles. We do **NOT** use or maintain a local `CHANGELOG.md` file. +- **Atomic Commits:** Keep commits small, single-topic, and functional. +- **Commit Message Standard:** Include the *why* (the reason the change was needed), the *how* (implementation details), and other peculiarities. + +### Pull Request & Review Flow: +- **Strict Branch Guardrails:** **Never** work on or merge directly into `main`, `master`, or `staging` branches. All development must occur on separate feature/bugfix branches. +- **Developer Review:** Every change made by an AI Agent must be thoroughly reviewed by a human developer. +- **GitHub Pull Request Requirements:** An official GitHub Pull Request must be opened in **DRAFT** state. It can only be considered merge-ready when: + 1. All automated GitHub Actions status checks show **green checkmarks**. + 2. All review topics, comments, and threads are completely **resolved**. +- **Empty Initiator Checklist:** Every pull request description must end with an empty checklist for the human dev who initiated the agent, confirming they reviewed the code. +- **Visual Evidence:** UI-impacting changes require visual evidence (screenshots/recordings) added to the PR description (uploaded via browser or `gh-image` tool). Do NOT commit media files directly into the repository. +- **Human Merge Only:** Under no circumstances should an AI agent attempt to merge its own Pull Request. Merging is **strictly restricted to humans**. + +### Support Portal Review & Alert Annotations: +- **Support Documentation Audit Rule:** When introducing a **new feature** or **changing existing behavior**, you **MUST** search the UltiMaker Support page: `https://support.makerbot.com/s/global-search/` and analyze if any relevant public-facing support pages are impacted. + - If support page changes are required, add a **warning block** (`> [!WARNING]`) in the PR description advising the developer to contact the support team. Outline exactly **what changed**, **why**, and **how**, citing any existing support page URLs. +- **PR Alert Annotations:** Always annotate pull request and merge descriptions with standard GitHub markdown alerts to guide the reviewer: + ```markdown + > [!NOTE] + > Useful information that users should know, even when skimming content. + + > [!WARNING] + > Urgent info that needs immediate user attention to avoid problems. + ``` + +--- + +## 4. Directory Organization & Tech-Stack Architecture + +### Tech-Stack: +- **Languages**: XML, Python +- **Build/Build Tooling**: Standard setup.py packaging +- **Core Frameworks**: Cura Material XML specification + +### Core Directory Layout: +- `/materials/`: XML file definitions for all spools. +- `/scripts/`: Python linting and schema validation scripts. + +--- + +## 5. Designing for Future AI Generated Code + +- **Decomposed File Footprints:** Keep individual modules and files as small as possible. Individual files (Python modules, C++ sources, headers, or QML) should ideally remain **around 300 lines (max 400 lines is acceptable)** to minimize token overhead and keep context-windows clean. +- **Leverage Third-Party Libraries:** Favor mature, well-maintained third-party frameworks and libraries instead of building custom code from scratch. Search NPM, PyPI, or Conan registries before implementing custom helpers. + +--- + +## 6. Local Development Environment & Setup + +### Requirements & Prerequisites: +Run python lint checks: `python3 scripts/validate_schemas.py` + +--- + +## 7. Security & OWASP IoT Top 10 Mitigations + +Our software is deployed on industrial 3D printing equipment. We must actively mitigate the **OWASP IoT Top 10** vulnerabilities: + +1. **Weak, Guessable, or Hardcoded Credentials:** NEVER hardcode passwords, private keys, or API tokens. Our signing keys are backed in GCP Secret Manager and retrieved securely at runtime. +2. **Insecure Network Services:** Minimize listening ports. All local/network service interfaces must authenticate requests and utilize TLS/SSL where applicable. +3. **Insecure Ecosystem Interfaces:** Secure all API endpoints, DBus, and MQTT communication paths. Validate and sanitize all incoming payloads. +4. **Lack of Secure Update Mechanism:** S-Line/Factor 4 firmware updates use the SquashFS SWU format with detached GPG signatures. Never bypass the GPG signature check. +5. **Use of Insecure or Outdated Components:** Keep our Python packages, Conan packages, and debian dependencies up to date. +6. **Insufficient Privacy Protection:** Securely handle user profiles, PII, and telemetry. Never write passwords or sensitive tokens to local log files. +7. **Insecure Data Transfer and Storage:** Encrypt sensitive credentials and configurations. Use RAM-backed filesystems (`/dev/shm`) for temporary decryption targets. +8. **Lack of Device Management:** Integrate with UltiMaker Digital Factory securely. +9. **Insecure Default Settings:** Enforce safe defaults out-of-the-box. +10. **Lack of Physical Hardening:** Secure local terminal and SSH ports. Enforce strict `umssh.sh` password-less or authenticated connections. + +--- + +## 8. Companion Guides + +Consult the following guides found within the repository or ecosystem: +- **README.md**: Standard setup and compilation guidelines. +- None extra. + +--- + +## 9. Automated Pre-Commit Tooling & Closed-Loop Cycle + +To support a robust, automated closed-loop development cycle, this repository enforces automatic static quality checks using `pre-commit` before any git commit is recorded. + +### Core Architecture & Checks: +- **Fast Static Analysis:** Hooks run formatters, linters, and credentials scanning to ensure code quality and safety. +- **Commit Guardrails:** + 1. **Jira Ticket Reference:** Commit messages *must* reference a Jira ticket prefix. + 2. **Agent Artifact & Scratch File Block:** Blocks staging/committing agent-specific tracking files (`task.md`, `implementation_plan.md`, `walkthrough.md`, scratch files, temporary `test_` scripts). + 3. **Talisman Secret Scanner:** ThoughtWorks Talisman pre-commit scanner blocks committed credentials/secrets. + 4. **Local Paths Reference Blocker:** Prevents hardcoded local absolute path references (e.g., `/home//`). + +### Setup and Manual Use: +1. **Installation:** Ensure `pre-commit` is installed and set up: + ```bash + pip install pre-commit + pre-commit install --hook-type pre-commit --hook-type commit-msg + ``` +2. **Manual Execution:** Run checks manually on staged or all files: + ```bash + pre-commit run --all-files + ``` + +--- + +## 10. Visual Validation & Verification (V&V) Guidelines + +Every feature implementation, UI refinement, or bug fix **MUST** undergo a systematic Validation & Verification (V&V) process. + +### Scenarios to Test: +- **Happy Path Scenarios:** Verify standard successful workflows. Ensure that no console exceptions, network errors, or visual regressions occur. +- **Unhappy Path Scenarios:** Verify edge cases, input limits, and error handling (e.g., failed DBus bindings, offline state, empty profiles). +- **Physical Verification / Emulation:** Where applicable, use the `ultimaker-printer-ssh` skill to push the generated build output onto a networked test printer: + ```bash + ./deploy_to_printer.sh + ``` +- **PR Visual Evidence Mandate:** For visual changes (Okuda UI, griffin_html), provide viewport screenshots/recordings of both happy and unhappy paths in your PR description.