st-creator 0.2.0__tar.gz

st_creator-0.2.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.3
+Name: st-creator
+Version: 0.2.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.
+
+## Rules DSL
+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 `INCLUDE(<expr>)` / `EXCLUDE(<expr>)` statements, one or more per file. `<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"))
+```

st_creator-0.2.0/README.md

@@ -0,0 +1,170 @@
+# 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.
+
+## Rules DSL
+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 `INCLUDE(<expr>)` / `EXCLUDE(<expr>)` statements, one or more per file. `<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"))
+```

st_creator-0.2.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "st-creator"
+version = "0.2.0"
+description = "A stupid CLI to easily create themes for Structurizr."
+readme = "README.md"
+authors = [
+    { name = "Federico Cantarelli", email = "fede.cantarelli98@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "click>=8.4.2,<9.0.0",
+]
+
+[project.scripts]
+st = "st_creator:main"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "$version"
+version_scheme = "semver2"
+version_provider = "uv"
+update_changelog_on_bump = true
+major_version_zero = true

st_creator-0.2.0/src/st_creator/__init__.py

@@ -0,0 +1,16 @@
+import click
+
+from st.commands.theme import theme
+from st.commands.version import version
+
+
+@click.group()
+def main():
+    """ST: A command line tool for creating Structurizr themes easily."""
+
+
+main.add_command(version)
+main.add_command(theme)
+
+if __name__ == "__main__":
+    main()

st_creator-0.2.0/src/st_creator/commands/theme.py

@@ -0,0 +1,137 @@
+import os
+import pathlib
+
+import click
+
+from st.core.model import Theme
+from st.core.model import ThemeElement
+from st.core.model import go_through_fs_tree
+from st.core.rule_parser import RuleSet
+from st.core.rule_parser import filter_elements
+from st.utils.config import CONFIG_FILE
+from st.utils.config import init_config
+from st.utils.config import load_config
+from st.utils.pretty_print import print_done
+from st.utils.pretty_print import print_verbose
+from st.utils.pretty_print import print_warning
+from st.utils.str_utils import to_clean_string
+
+
+@click.group()
+def theme():
+    """Create a DSL theme."""
+
+
+@theme.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--output", type=click.Path(), required=False, default=None)
+@click.option(
+    "--rules",
+    type=click.Path(exists=True, dir_okay=False),
+    required=False,
+    default=None,
+    help="Path to a rules file (e.g. rules.st) filtering which icons to process.",
+)
+def clean(path, output, rules):
+    """Prepare a directory of icons for theme creation."""
+    full_path = pathlib.Path(path)
+    output_path = full_path.parent / (output if output else "cleaned")
+    if not output_path.exists():
+        output_path.mkdir(parents=True, exist_ok=True)
+    first_level = [item for item in os.listdir(full_path) if not item.startswith(".")]
+    first_level_dict = {item: to_clean_string(item) for item in first_level}
+    for item in first_level_dict.values():
+        if item.startswith("."):
+            print_verbose(f"Skipping hidden directory: {item}")
+        else:
+            if item is not None:
+                os.makedirs(os.path.join(output_path, item), exist_ok=True)
+    elements = go_through_fs_tree(
+        full_path=full_path, include_top_parent_directory=False
+    )
+    if rules is not None:
+        elements = filter_elements(elements, RuleSet.from_file(pathlib.Path(rules)))
+    for element in elements:
+        element.copy(
+            output_path=output_path
+            / element.top_parent_directory
+            / element.cleaned_file_name
+            if element.top_parent_directory
+            else output_path / element.cleaned_file_name
+        )
+    print_done("Cleaning done!")
+
+
+@theme.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--name", type=str, required=True)
+@click.option("--description", type=str, required=False, default=None)
+@click.option(
+    "--rules",
+    type=click.Path(exists=True, dir_okay=False),
+    required=False,
+    default=None,
+    help="Path to a rules file (e.g. rules.st) filtering which icons to process.",
+)
+def create(path, name: str, description: str | None, rules: str) -> None:
+    if not CONFIG_FILE.exists():
+        print_warning("Configuration file not found. Creating one with default values.")
+        init_config(config_path=CONFIG_FILE)
+    config = load_config(config_path=CONFIG_FILE)
+    full_path = pathlib.Path(path).resolve()
+    output_path = full_path.parent / "-".join(name.lower().split(" "))
+
+    name = name.replace("'", "").replace('"', "")
+    description = (
+        description.replace("'", "").replace('"', "")
+        if description is not None
+        else None
+    )
+    os.makedirs(os.path.join(output_path), exist_ok=True)
+    theme = Theme(
+        name="Name here" if name is None else name,
+        description="Description here" if description is None else description,
+    )
+
+    elements = go_through_fs_tree(
+        full_path=full_path,
+        include_top_parent_directory=False,
+    )
+    if rules is not None:
+        elements = filter_elements(elements, RuleSet.from_file(pathlib.Path(rules)))
+
+    for element in elements:
+        element.copy(
+            output_path=output_path / (theme.file_prefix + "_" + element.theme_name),
+        )
+        element.load_properties_from_json()
+
+        theme_element = ThemeElement(
+            tag=element.get_theme_tag(prefix=theme.tag_prefix),
+            # stroke=color
+            # if color is not None
+            # else config["defaults.theme"]["stroke"],
+            # color=color if color is not None else config["defaults.theme"]["color"],
+            stroke="#232f3d",
+            color="#232f3d",
+            icon=theme.file_prefix + "_" + element.theme_name,
+        )
+        theme.add_element(theme_element)
+
+    theme.export(pathlib.Path(output_path) / "theme.json")
+
+    print_done("Theme created!")
+
+
+# TODO: keep this for future releases maybe >^.^<
+# @click.command()
+# @click.option("--output", type=click.Path(), required=True)
+# def scrape(output) -> None:
+#     print(f"Scraping icons from {TECH_ICON_URL}\n")
+#     time.sleep(1)
+#     if download_blob_image(
+#         base_url=TECH_ICON_URL, output_dir=pathlib.Path(output).resolve()
+#     ):
+#         print_done("\nAll images downloaded successfully!")
+#     else:
+#         print_warning("\nDownload failed")

st_creator-0.2.0/src/st_creator/commands/version.py

@@ -0,0 +1,9 @@
+import click
+
+from st.utils.pretty_print import print_version
+
+
+@click.command()
+def version():
+    """Get CLI version."""
+    print_version()