Metadata-Version: 2.3
Name: st-creator
Version: 0.3.0
Summary: A stupid CLI to easily create themes for Structurizr.
Author: Federico Cantarelli
Author-email: Federico Cantarelli <fede.cantarelli98@gmail.com>
Requires-Dist: click>=8.4.2,<9.0.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# Structurizr Theme Creator

A very stupid CLI to create Structurizr themes starting from icons.

<b>:warning: This is super work in progress. Will be completed soon.</b>

## Installation

`st` is not published to PyPI yet, so you can install it directly from the repository using [`uv`](https://docs.astral.sh/uv/).

```bash
# Clone the repository
git clone https://github.com/FedericoCantarelli/st.git
cd st

# Install dependencies and create the virtual environment
uv sync

# Run the CLI using uv
uv run st --help
```

If you want to have `st` command available directly from CLI, you can install the tool running the following command from the root of the repository:

```bash
uv tool install .
st --help
```

## Usage
The CLI is enterile based on `click` module. To get CLI help you can run the following command:

```bash
st --help
```

### Version
Print the CLI version

```bash
st version
```

### Clean
Normalizes a raw icon export (e.g. downloaded from an icon library) into a directory of `cleaned_string`-named files and directories, ready to be fed into `st theme create`. See [Naming Convention](#naming-convention-of-exported-icons) for how output names are derived. Hidden files and directories (starting with `.`) are <u>skipped</u>.

```bash
st theme clean <path> [--output <dir>] [--rules <rules.st>]
```

| Argument / Option | Required | Description |
| --- | --- | --- |
| `path` | Yes | Path to the input directory containing the raw icon export. Must exist. |
| `--output` | No | Name of the output directory, created as a sibling of `path`. Defaults to `cleaned`. |
| `--rules` | No | Path to a [rules file](#rules-dsl) used to filter which icons are processed. |

Example:

```bash
st theme clean ./raw-icons --output cleaned --rules ./rules.st
```

### Create

Create a theme from a cleaned icon directory, builds one theme element per `.svg` file found, and exports a `theme.json` compatible with Structurizr's [custom theme](https://docs.structurizr.com/dsl/themes) format. The output is written to a new directory named after `--name` (lowercased, spaces replaced with `-`), placed as a sibling of `path`.

```bash
st theme create <path> --name "My Theme" [--description <text>] [--rules <rules.st>]
```

| Argument / Option | Required | Description |
| --- | --- | --- |
| `path` | Yes | Path to the input directory containing the icons to include in the theme. Must exist. |
| `--name` | Yes | Name of the theme. Also used to derive the file prefix and tag prefix (see [Naming Convention](#naming-convention-of-exported-icons)). |
| `--description` | No | Description of the theme, written into `theme.json`. |
| `--rules` | No | Path to a [rules file](#rules-dsl) used to filter which icons are processed. |

Example:

```bash
st theme create ./cleaned --name "GCP Icons" --description "Google Cloud Platform icon theme" --rules ./rules.st
```

On first run, `st theme create` creates a default configuration file at `~/.st/config.ini` if one does not already exist. For the moment this file is unusued. TODO: implement default configuration options in this file.

## Naming Convention of Exported Icons

The naming convention of exported icons depends on the directory structure of the icons: exported icon names depend on the first-level nested directories inside the input directory.

Given the following project structure:
```text
# First level nested directories are `Category Icons` and `Unique Icons`
.
├── Category Icons
│   └── Agents
│       ├── PNG
│       │   └── Agents-512-color.png
│       └── SVG
│           └── Agents-512-color.svg
└── Unique Icons
    └── AlloyDB
        ├── PNG
        │   └── AlloyDB-512-color.png
        └── SVG
            └── AlloyDB-512-color.svg
```
The naming convention for the exported icons is the following:
```
<prefix>_<first_level_dir>_<snake_case_filename>
```
where `<prefix>` is computed from theme name, `<first_level_dir>` is the name of the first-level nested directory in snake case, and `<snake_case_filename>` is the filename converted to snake case, removing everything else that is not a character (number or non-alphanumeric characters).

For example the file `AlloyDB-512-color.png` will be exported as `gcp_unique_icons_alloydb_color.png` if the theme name is `Google Cloud Platform`.

Only the top-level directory (one level inside the `--path` folder) is used for the naming convention.

For `st theme create`, the `--name` you pass also drives two additional prefixes:
- **Tag prefix**: used to prefix the Structurizr element tag (e.g. `GCP - Category - Agents`). If the theme name has more than two "eligible" words (longer than 2 characters), the prefix is the initials of those words; otherwise it's the whole name in snake case.
- **File prefix**: same derivation logic, used to prefix the icon file name and the theme's output directory.

## ST Rules
Both `st theme clean` and `st theme create` accept an optional `--rules <path>` argument pointing to a rules file (conventionally named `rules.st`). Rules let you filter which icons get processed without having to restructure your input directory. TODO: eventually this can become a `.txt` for the mental health of everybody.

A rules file is a sequence of statements. There are two families:

- **Filter statements** — `INCLUDE(<expr>)` / `EXCLUDE(<expr>)` — decide which icons get processed (used by both `st theme clean` and `st theme create`).
- **Conditional statements** — `IF(<expr>) THEN <action>` — set attributes on the generated theme element, or rename the icon (used only by `st theme create`). See [Conditional rules](#conditional-rules-if--then).

`<expr>` is a boolean expression built from `AND`, `OR`, `NOT`, parentheses, and two kinds of leaf predicates:

- `ATTRIBUTE=value` — glob-matches `value` against an icon attribute. Supports `*` (any sequence of characters, including none), `?` (any single character), and `[...]` / `[!...]` character classes (with `-` for ranges, e.g. `[a-z]`).
- `CONTAIN(ATTRIBUTE, "substring")` — true if the attribute's value contains `substring` as a literal substring.

`ATTRIBUTE` is one of:

| Attribute | Description |
| --- | --- |
| `NAME` | The icon's file name without its extension. |
| `EXTENSION` | The icon's file extension, including the leading dot (e.g. `.svg`). |
| `PATH` | The icon's full path, as a POSIX-style string. |

Matching is **case-sensitive**. Values are written either as bare words or quoted strings (`'...'` or `"..."`); quoting is required for values containing spaces or reserved characters. This set of attributes is meant to be extensible and will be expanded (hopefully) in future versions of the CLI to allow more specific rules.

### Decision rule

An icon is dropped if it matches any `EXCLUDE` expression, unless it also matches an `INCLUDE` expression. Thus `INCLUDE` always overrides `EXCLUDE` on conflict. Default is keep: if an icon matches neither an `INCLUDE` nor an `EXCLUDE` expression is kept.

If a rules file has `INCLUDE` statements but **no** `EXCLUDE` statements, `INCLUDE` acts as a standalone whitelist: only icons matching at least one `INCLUDE` expression are kept
- 'INCLUDE' acts as a filter in
- 'EXCLUDE' acts as a filter out
Thus 'EXCLUDE(NOT NAME="file_name.svg") will include the file_name.svg and exclude all the others.

I'm not sure if this is the best approach, but i wrote it like this.

### Examples

Keep only `.svg` files, and drop anything under a directory called `Unique Icons`, unless its file name starts with `Alloy`:

```
INCLUDE(NAME="Alloy*" AND EXTENSION=".svg")
EXCLUDE(CONTAIN(PATH, "Unique Icons"))
EXCLUDE(NOT EXTENSION=".svg")
```

Whitelist a single file, dropping everything else:

```
INCLUDE(NAME="filename")
EXCLUDE(NAME="*")
```

Exclude every file whose name contains 'deprecated'
```
EXCLUDE(CONTAIN(NAME, "deprecated"))
```

### Conditional rules (IF ... THEN)

Conditional rules let you style the generated theme elements from the rules file, instead of relying on hardcoded defaults, and rename icons. `st theme create` honours all of them. `st theme clean` builds no theme elements, so it applies only the `REPLACE_STRING` actions of a matching rule and ignores the `<attr>=<value>` assignments.

```
IF(<condition>) THEN <action>[, <action> ...]
```

- `<condition>` uses the **same expression grammar** as a filter expression (`AND`, `OR`, `NOT`, parentheses, `ATTRIBUTE=value`, `CONTAIN(...)`) over the icon attributes `NAME`, `EXTENSION`, `PATH`.
- `THEN` takes one or more **comma-separated** actions, each being either:
  - `<attr>=<value>` — an assignment setting a settable theme-element attribute, or
  - `REPLACE_STRING("<old>", "<new>")` — a rename of the icon. See [Renaming icons](#renaming-icons-replace_string).

When the condition matches an icon, every action is applied. Rules are evaluated **top-to-bottom**, so when several rules set the same attribute on the same element, **the last matching rule wins**.

#### Settable attributes and validation

Each `<value>` is validated and coerced **when the rules file is parsed** — a malformed value fails immediately (before any icons are processed) with a message pointing at the offending rule.

| Attribute | Accepted values |
| --- | --- |
| `stroke`, `color`, `background` | Hex color, `#rgb` or `#rrggbb` (e.g. `#000000`). |
| `border` | One of `solid`, `dashed`, `dotted` (case-insensitive). |
| `shape` | A Structurizr shape, e.g. `Box`, `Circle`, `Cylinder`… `RoundedBox` (case-insensitive). |
| `width`, `height`, `font_size` | A positive integer. |
| `opacity` | An integer between `0` and `100`. |
| `description` | A non-empty string. |

`tag` and `icon` are managed by the tool and cannot be set from rules.

#### Renaming icons (REPLACE_STRING)

```
REPLACE_STRING("<old>", "<new>")
```

Replaces **every** occurrence of `<old>` in the icon name (the file name without its extension) with `<new>`. If `<old>` does not occur in the name, the action does nothing. Matching is literal and case-sensitive — no globs. `<new>` may be empty (`""`) to simply strip `<old>`; `<old>` may not.

The name a rule sees is the **original** name on disk, *before* any snake_case conversion — so for a raw export like `AlloyDB-512-color.png`, match `-color`, not `_color`. The conversion to `alloydb_...` happens after the rules have run.

The file on disk is never renamed. The rewritten name is what the tool derives from afterwards, so a rename propagates to the **copied icon file name**, the theme element's `icon` and its `tag`:

```
IF(CONTAIN(NAME, "google_")) THEN REPLACE_STRING("google_", "")
```

Given `Category Icons/google_cloud_run.svg` and a theme named `Test Theme Demo`, the icon is copied as `ttd_category_cloud_run.svg` and tagged `TTD - Category - Cloud Run` instead of `TTD - Category - Google Cloud Run`.

Because each rule's condition is evaluated when its turn comes, a rename done by an earlier rule is visible to the conditions of the later ones:

```
IF(CONTAIN(NAME, "google_")) THEN REPLACE_STRING("google_", "")
IF(NAME="cloud_*") THEN stroke="#ff0000"
```

Here `google_cloud_run.svg` becomes `cloud_run` and *then* matches the second rule.

#### Examples

Give every `.svg` icon a black stroke, and make anything named like a database a dashed circle at 80% opacity:

```
IF(EXTENSION=".svg") THEN stroke="#000000"
IF(CONTAIN(NAME, "database")) THEN shape="Circle", opacity="80", border="dashed"
```

Because the last matching rule wins, a later rule can override an earlier one:

```
IF(EXTENSION=".svg") THEN stroke="#000000"
IF(NAME="database_*") THEN stroke="#ff0000"
```

Here every `.svg` gets a black stroke, except icons whose name starts with `database_`, which end up red.

Strip an exporter's noise from every icon name and style the result in one rule:

```
IF(CONTAIN(NAME, "_512_color")) THEN REPLACE_STRING("_512_color", "")
IF(CONTAIN(NAME, "cloud_sql")) THEN REPLACE_STRING("cloud_sql", "sql"), shape="DiamondCylinder"
```
