# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project overview

`id-configurator` is a proprietary CLI tool by InterDiode to "configure a device in an air-gapped environment".
It targets Python 3.13+ and is packaged with the `uv_build` backend.
It takes a configuration (JSON or YAML, either from a file or from a base64-encoded environment variable) and applies it to the system, including installing root certificates, configuring package managers, and other system-level settings.
Modified files are written to a destination directory given with --dst by the user, this directory can be used to build a Docker image.
The original file system can be provided with --src by the user to detect existing configuration.

Example:
- the configuration specifies a root certificate to install, the tool will copy it to `<dst>/etc/ssl/certs` and update the system's CA certificates.
- the configuration specifies a apt source to add and `<src>` contains an existing `/etc/apt/sources.list`, the tool will merge the new source into the existing sources and write the result to `<dst>/etc/apt/sources.list`.

The configuration is expected to be a JSON or YAML object with the following structure:

```yaml
uuid: <UUID>
organisation: <string>
description: <string>
configurations:
    certificates:
      - name: <string>
        content: <PEM>
    apt:
        sources:
            - name: <string>
              content: <string>
        keys:
            - name: <string>
              content: <GPG key>
    yum:
        repositories:
            - name: <string>
              index-url: <string>
              gpg-url: <string>
    python:
        repositories:
            - name: <string>
              index-url: <string>
```

The tool must have an extensible modular structure. Each module can use any part of the configuration, detect if is relevant by checking the current filesystem from `<src>`, and write modified files to `<dst>`.
Several modules can read the certificates from the configuration and use them differently.
The tool must be able to run in a Docker container, and must not require any network access.
It is forbidden to write any file outside of `<dst>`.

The tool must be called by `python -m id_configurator`, or via the console script entry point `id-configurator`.

Here is a preliminary list of modules that will be implemented:
- install root certificates in the system's CA store
- configure system package managers:
  - apt
  - yum
  - apk
  - dnf
- configure programming language package managers:
  - python (pip)
  - ruby (gem)
  - nodejs (npm)
  - golang (go)
  - java (maven, gradle)
  - php (composer)
  -

## Current state

This repository is a skeleton: `id_configurator/__init__.py` is currently empty, and `README.md` is empty. `pyproject.toml` already declares a console-script entry point:

```
id-configurator = "id_configurator:main"
```

There is no `main` callable yet — implementing it in `id_configurator/__init__.py` (or importing it there) is the first thing needed to make the CLI runnable. No tests, no `[tool.ruff]`/`[tool.pytest]` config, and no CI config exist yet.

## Commands

- Install/sync dependencies: `uv sync`
- Run the CLI (once `main` exists): `uv run id-configurator`
- Lint and auto-fix: `uv run ruff check --fix .`
- Format: `uv run ruff format .`
- Run all pre-commit hooks (ruff, bandit, shellcheck, commitizen, check-yaml/toml/json, etc.): `uv run pre-commit run --all-files`

There is no test suite yet.

## Conventions

- Python version is pinned to 3.13 (`.python-version`, `requires-python = ">=3.13"` in `pyproject.toml`).
- `.editorconfig`: 4-space indentation, single quotes, LF line endings, 120 max line length for `.py` files.
- Commit messages are linted by commitizen via pre-commit, implying Conventional Commits format.
- The package is proprietary (`Private :: Do Not Upload` classifier) and is not published to PyPI.