id_configurator/CLAUDE.md

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:

uuid: <UUID>
organisation: <string>
description: <string>
configurations:
    certificates:
      - name: <string>
        content: <base64-encoded PEM>
    apt:
        sources:
            - name: <string>
              content: <string>
        keys:
            - name: <string>
              content: <base64-encoded 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.