feat: initial commit

CLAUDE.md

@@ -0,0 +1,93 @@
+# 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: <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.