From 77b8c167b4602418a29cc20a2690f577c04d9435 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 8 Oct 2026 09:28:27 +0000 Subject: [PATCH 1/2] docs: align v3.3.0 docs with actual config, install, and env behavior Correct config layering to match load_layered_config (--config-file, not auto-loaded .structkit.yaml), document Homebrew and Linux workflow artifacts, and list every STRUCTKIT_* env var with its real default. Co-authored-by: Kenneth Belitzky --- .github/workflows/build-linux-packages.yaml | 2 +- README.md | 6 +- docs/cli-reference.md | 14 +- docs/configuration.md | 44 ++++-- docs/environment-variables.md | 126 ++++++++++++++++-- docs/github-integration.md | 38 ++++++ docs/index.md | 14 +- docs/installation.md | 51 ++++++- examples/config-layering/README.md | 16 ++- .../project-config-example.yaml | 3 +- mkdocs.yml | 9 +- packaging/README.md | 7 +- structkit/config.py | 19 ++- structkit/contribs/github/prompts/struct.yaml | 2 +- 14 files changed, 303 insertions(+), 48 deletions(-) diff --git a/.github/workflows/build-linux-packages.yaml b/.github/workflows/build-linux-packages.yaml index 74b1003..98715bf 100644 --- a/.github/workflows/build-linux-packages.yaml +++ b/.github/workflows/build-linux-packages.yaml @@ -7,7 +7,7 @@ on: workflow_dispatch: inputs: version: - description: 'Package version (e.g., 3.2.1)' + description: 'Package version (e.g., 3.3.0)' required: false default: '' diff --git a/README.md b/README.md index e43c575..1d239f2 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,8 @@ These are install paths for [StructKit](https://github.com/httpdss/structkit), n - [VS Code / Cursor](https://github.com/httpdss/vscode-structkit) — schema and autocomplete for `.structkit.yaml` - [Agent skills](https://github.com/httpdss/structkit-skills) — inspect, preview, generate, validate from an assistant - [pre-commit](https://github.com/httpdss/structkit-pre-commit) — validate structures before they land -- [Homebrew](https://github.com/httpdss/homebrew-structkit) — `brew tap httpdss/structkit && brew install structkit` +- [Homebrew](https://github.com/httpdss/homebrew-structkit) — `brew install httpdss/structkit/structkit` +- Linux `.deb` / `.rpm` — download from [build-linux-packages](https://github.com/httpdss/structkit/actions/workflows/build-linux-packages.yaml) workflow artifacts (not attached to GitHub Releases), or build locally per [packaging/README.md](packaging/README.md) - [Backstage](https://github.com/httpdss/backstage-plugin-structkit) — scaffolder actions for platform teams - [Hermes plugin](https://github.com/httpdss/hermes-plugin-structkit) — safe StructKit tools inside Hermes @@ -82,6 +83,8 @@ Project scaffolding tools exist in most ecosystems, but StructKit solves problem - **🌐 Remote Content** - Fetch files from GitHub, HTTP/HTTPS, S3, and Google Cloud Storage - **🛡️ Smart File Handling** - Multiple strategies for managing existing files (overwrite, skip, backup, etc.) - **🪝 Automation Hooks** - Pre and post-generation shell commands +- **🔒 Hook Safety** - Skip hooks (`--no-hooks` / `STRUCTKIT_NO_HOOKS`), confirm interactively, or restrict commands with an allowlist +- **⚙️ Config Layering** - Merge built-in defaults, `~/.config/struct/config.yaml`, optional `--config-file`, and CLI flags - **🎯 Dry Run Mode** - Preview changes before applying them - **✅ Validation & Schema** - Built-in YAML validation and IDE support - **🤖 MCP Integration** - Model Context Protocol support for AI-assisted development workflows @@ -143,6 +146,7 @@ Our comprehensive documentation is organized into the following sections: - **[YAML Configuration](docs/configuration.md)** - Complete configuration reference - **[Template Variables](docs/template-variables.md)** - Dynamic content and Jinja2 features - **[File Handling](docs/file-handling.md)** - Managing files, permissions, and remote content +- **[Environment Variables](docs/environment-variables.md)** - `STRUCTKIT_*` defaults and overrides - **[Schema Reference](docs/schema.md)** - YAML validation and IDE support ### 🔧 Advanced Features diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 605d250..f4641b5 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -25,11 +25,13 @@ These options are available for all commands: The following environment variables can be used to configure default values for CLI arguments: -- `STRUCTKIT_LOG_LEVEL`: Set the default logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Overridden by the `--log` flag. +- `STRUCTKIT_LOG_LEVEL`: Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Applied after argument parsing and **overrides** `--log` and `--debug` when set to a non-empty value. - `STRUCTKIT_STRUCTURES_PATH`: Set the default path to structure definitions. This is used as the default value for the `--structures-path` flag when not explicitly provided. When set, the CLI will log an info message indicating that this environment variable is being used. -- `STRUCTKIT_SOURCES_CONFIG`: Override the user-level named sources config file (default: `$XDG_CONFIG_HOME/structkit/sources.yaml` or `~/.config/structkit/sources.yaml`). +- `STRUCTKIT_SOURCES_CONFIG`: Override the user-level named sources config file (default: `$XDG_CONFIG_HOME/structkit/sources.yaml` or `~/.config/structkit/sources.yaml`). This is separate from the CLI user config at `~/.config/struct/config.yaml`. - `STRUCTKIT_SOURCES_CACHE`: Override the local cache directory used for git-backed sources (default: `$XDG_CACHE_HOME/structkit/sources` or `~/.cache/structkit/sources`). +See [Environment Variables](environment-variables.md) for the full `STRUCTKIT_*` list (hooks, HTTP, and other flags). + **Precedence:** 1. Explicit `--structures-path` CLI flag (highest priority) @@ -121,7 +123,7 @@ Generate the project structure. **Usage:** ```sh -structkit generate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [-n INPUT_STORE] [-d] [--diff] [-v VARS] [-b BACKUP] [-f {overwrite,skip,append,rename,backup}] [-p GLOBAL_SYSTEM_PROMPT] [--non-interactive] [--mappings-file MAPPINGS_FILE] [-o {console,file}] [structure_definition] [base_path] +structkit generate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [-n INPUT_STORE] [-d] [--diff] [-v VARS] [-b BACKUP] [-f {overwrite,skip,append,rename,backup}] [-p GLOBAL_SYSTEM_PROMPT] [--non-interactive] [--mappings-file MAPPINGS_FILE] [-o {console,file}] [--no-hooks] [--hooks-allowlist HOOKS_ALLOWLIST] [structure_definition] [base_path] ``` Defaults when omitted: @@ -149,6 +151,8 @@ structkit generate - `--non-interactive`: Run the command in non-interactive mode. - `--mappings-file MAPPINGS_FILE`: Path to a YAML file containing mappings to be used in templates (can be specified multiple times). - `-o {console,file}, --output {console,file}`: Output mode. +- `--no-hooks`: Skip all pre/post hooks. Can be set via `STRUCTKIT_NO_HOOKS` (`true`, `1`, or `yes`). +- `--hooks-allowlist HOOKS_ALLOWLIST`: Path to a hooks allowlist file. Can be set via `STRUCTKIT_HOOKS_ALLOWLIST`. If omitted, `generate` still loads `.struct-hooks-allowlist` in the current directory when that file exists. ### `explain` @@ -332,8 +336,8 @@ structkit config print [--format {yaml,json}] [-c CONFIG_FILE] The `config print` command shows the final merged configuration from all layers: 1. Built-in defaults (lowest priority) -2. User config (`~/.config/struct/config.yaml`) -3. Project config (`.structkit.yaml`, legacy `.struct.yaml`, or `--config-file`) +2. User config (`~/.config/struct/config.yaml`), loaded automatically when present +3. Project config from `--config-file` only (`.structkit.yaml` is not auto-loaded as CLI config) 4. CLI arguments (highest priority) The command also displays which configuration sources were loaded. diff --git a/docs/configuration.md b/docs/configuration.md index 873964c..1130e48 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,16 +2,29 @@ ## Config Layering -Structkit supports a layered configuration system that allows you to set defaults at multiple levels. Configuration values are merged in the following order (from lowest to highest priority): +StructKit supports a layered configuration system for **CLI defaults** (file strategy, log level, structures path, and similar flags). Values are merged in this order (lowest to highest priority), matching `load_layered_config` and `main.py`: -1. **Built-in defaults** - Hard-coded defaults that are always present -2. **User config** - Global defaults from `~/.config/struct/config.yaml` -3. **Project config** - Project-specific config from `.structkit.yaml` (legacy `.struct.yaml`) or `--config-file` -4. **CLI arguments** - Command-line flags (highest priority) +1. **Built-in defaults** — Hard-coded defaults that are always present +2. **User config** — `~/.config/struct/config.yaml`, loaded automatically when the file exists +3. **Project config** — Only the file passed with `--config-file` (not auto-loaded) +4. **CLI arguments** — Command-line flags (highest priority) + +`.structkit.yaml` (and legacy `.struct.yaml`) is the **structure definition** used by `structkit generate`, `validate`, and similar commands. It is **not** auto-loaded as layered CLI config. To apply project-specific CLI defaults, pass a file with `--config-file`. + +Several flags also read `STRUCTKIT_*` environment variables as argparse defaults. Those values are treated like CLI arguments (they override config files) unless you pass a different flag. `STRUCTKIT_LOG_LEVEL` is applied after parsing and overrides `--log` and `--debug`. See [Environment Variables](environment-variables.md). + +### User config vs named sources + +These are two different files in different directories: + +| File | Purpose | +| --- | --- | +| `~/.config/struct/config.yaml` | User-level CLI defaults (`file_strategy`, `log`, `input_store`, and the other options listed below). Loaded automatically when present. The path is `~/.config/struct/config.yaml` as implemented in code (not XDG-overridable). | +| `$XDG_CONFIG_HOME/structkit/sources.yaml` or `~/.config/structkit/sources.yaml` | Named structure sources for `structkit sources`. Override the path with `STRUCTKIT_SOURCES_CONFIG`. See [Custom Structures](custom-structures.md). | ### User Config -You can create a user-level config file at `~/.config/struct/config.yaml` to set your personal defaults. This is useful for setting preferences that apply across all your projects. +Create a user-level config file at `~/.config/struct/config.yaml` to set personal CLI defaults across projects. Example `~/.config/struct/config.yaml`: @@ -24,7 +37,14 @@ log: WARNING ### Project Config -Project-specific settings can be defined in a `.structkit.yaml` file or specified via the `--config-file` flag. These settings override user config and built-in defaults. A legacy `.struct.yaml` file is still accepted when `.structkit.yaml` is not present. +Project-specific CLI defaults are applied only when you pass `--config-file`. There is no automatic lookup of `.structkit.yaml` or `.struct.yaml` for this layer. + +```bash +structkit generate --config-file project-config.yaml +structkit config print -c project-config.yaml +``` + +These settings override user config and built-in defaults. CLI flags still win. ### CLI Arguments @@ -80,10 +100,12 @@ The command also displays which configuration sources were used: Configuration sources: 1. Built-in defaults: always loaded 2. User config: /home/user/.config/struct/config.yaml (exists) - 3. Project config: .structkit.yaml + 3. Project config: none specified 4. CLI arguments: highest priority ``` +When `--config-file` is set, line 3 shows that path instead of `none specified`. + ## YAML Configuration Properties When defining your project structure in the YAML configuration file, you can use various properties to control the behavior of the script. Here are the available properties: @@ -197,16 +219,16 @@ latest_release(repo_name: str, strip_v: bool = False, return_sha: bool = False) | `strip_v` | `bool` | `false` | In version mode, remove exactly one leading lowercase `v` from the release tag. Tags without that prefix, including an uppercase `V`, are unchanged. | | `return_sha` | `bool` | `false` | Return the commit SHA identified by the release tag instead of the tag name. | -Both options are optional, so existing calls keep their original behavior. For a latest release tagged `v3.2.1`, these examples produce: +Both options are optional, so existing calls keep their original behavior. For a latest release tagged `v3.3.0`, these examples produce: ```yaml files: - release.txt: content: | - # v3.2.1 (unchanged default output) + # v3.3.0 (unchanged default output) {{@ "httpdss/structkit" | latest_release @}} - # 3.2.1 (strip one leading lowercase "v") + # 3.3.0 (strip one leading lowercase "v") {{@ "httpdss/structkit" | latest_release(strip_v=true) @}} # 0123456789abcdef0123456789abcdef01234567 (release commit) diff --git a/docs/environment-variables.md b/docs/environment-variables.md index db7b01b..82aaba6 100644 --- a/docs/environment-variables.md +++ b/docs/environment-variables.md @@ -129,11 +129,11 @@ structkit generate my-custom-structure ./output Sets the logging level for all commands. -**CLI Equivalent:** `--log` (generate command) +**CLI Equivalent:** Applied in `main.py` after parsing. When set to a non-empty value, it **overrides** `--log` and `--debug`. -**Valid Values:** `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` +**Valid Values:** `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` (case-insensitive; unknown values fall back to `INFO`) -**Default:** `INFO` +**Default:** unset, then `--debug` if present, otherwise `--log` (default `INFO`) **Use Case:** Control verbosity of output for debugging or production deployments. @@ -143,14 +143,118 @@ export STRUCTKIT_LOG_LEVEL="DEBUG" structkit generate my-structure ./output ``` +## Hook Safety + +### `STRUCTKIT_NO_HOOKS` + +Skip all pre-generation and post-generation hooks. + +**CLI Equivalent:** `--no-hooks` + +**Valid Values:** `true`, `1`, `yes` (case-insensitive) enable skipping; any other value (including unset) leaves hooks enabled + +**Default:** unset / false (hooks run, subject to confirmation and allowlist) + +**Example:** +```bash +export STRUCTKIT_NO_HOOKS=true +structkit generate my-structure ./output +``` + +### `STRUCTKIT_HOOKS_ALLOWLIST` + +Path to a hooks allowlist file. When hooks are enabled and this is unset, `generate` still loads `.struct-hooks-allowlist` from the current working directory if that file exists. + +**CLI Equivalent:** `--hooks-allowlist` + +**Default:** unset (`None`); then `.struct-hooks-allowlist` in the current directory if present + +**Example:** +```bash +export STRUCTKIT_HOOKS_ALLOWLIST=/path/to/allowlist.txt +structkit generate my-structure ./output +``` + +## Network and HTTP + +Used by GitHub raw-content fetching in `ContentFetcher` (prefer `raw.githubusercontent.com`, then git fallback). + +### `STRUCTKIT_DENY_NETWORK` + +Skip HTTP attempts and use the git fallback directly. Only the string `1` enables this; `true`/`yes` are **not** recognized. + +**Default:** unset (HTTP is attempted) + +**Example:** +```bash +export STRUCTKIT_DENY_NETWORK=1 +structkit generate my-structure ./output +``` + +### `STRUCTKIT_HTTP_TIMEOUT` + +HTTP timeout in seconds for raw GitHub fetches. + +**Default:** `10` + +**Example:** +```bash +export STRUCTKIT_HTTP_TIMEOUT=30 +``` + +### `STRUCTKIT_HTTP_RETRIES` + +Number of retries after the first HTTP attempt (total attempts = retries + 1). + +**Default:** `2` + +**Example:** +```bash +export STRUCTKIT_HTTP_RETRIES=0 +``` + +## Named Sources + +These configure the **sources** file and git cache. They are separate from the CLI user config at `~/.config/struct/config.yaml`. + +### `STRUCTKIT_SOURCES_CONFIG` + +Override the user-level named sources config path. + +**CLI Equivalent:** `structkit sources --config-path` + +**Default:** `$XDG_CONFIG_HOME/structkit/sources.yaml` if `XDG_CONFIG_HOME` is set, otherwise `~/.config/structkit/sources.yaml` + +**Example:** +```bash +export STRUCTKIT_SOURCES_CONFIG=~/team/structkit-sources.yaml +structkit sources list +``` + +### `STRUCTKIT_SOURCES_CACHE` + +Override the local cache directory used for git-backed sources. + +**Default:** `$XDG_CACHE_HOME/structkit/sources` if `XDG_CACHE_HOME` is set, otherwise `~/.cache/structkit/sources` + +**Example:** +```bash +export STRUCTKIT_SOURCES_CACHE=~/cache/structkit-sources +``` + ## Precedence Rules -Command-line arguments **always take precedence** over environment variables. This allows environment variables to set sensible defaults while maintaining the ability to override them when needed. +For flags that use environment variables as argparse defaults (`STRUCTKIT_STRUCTURES_PATH`, `STRUCTKIT_FILE_STRATEGY`, `STRUCTKIT_INPUT_STORE`, `STRUCTKIT_BACKUP_PATH`, `STRUCTKIT_GLOBAL_SYSTEM_PROMPT`, `STRUCTKIT_NON_INTERACTIVE`, `STRUCTKIT_OUTPUT_MODE`, `STRUCTKIT_NO_HOOKS`, `STRUCTKIT_HOOKS_ALLOWLIST`): + +1. Explicit command-line flags +2. Environment variable (argparse default) +3. Layered config files (`--config-file`, then `~/.config/struct/config.yaml`, then built-in defaults) -**Precedence Order (highest to lowest):** -1. Command-line arguments -2. Environment variables -3. Built-in defaults +Because those env vars populate argparse defaults, they override values from config files unless you pass a different CLI flag. + +**Exception:** `STRUCTKIT_LOG_LEVEL` is applied after parsing and overrides `--log` and `--debug` when set. + +`STRUCTKIT_DENY_NETWORK`, `STRUCTKIT_HTTP_TIMEOUT`, `STRUCTKIT_HTTP_RETRIES`, `STRUCTKIT_SOURCES_CONFIG`, and `STRUCTKIT_SOURCES_CACHE` are read directly where they are used; they are not CLI-config layers. **Example:** ```bash @@ -166,6 +270,8 @@ structkit generate my-structure ./output # Uses 'backup' from STRUCTKIT_FILE_STRATEGY ``` +Layered CLI config (`~/.config/struct/config.yaml` and `--config-file`) sits below those argparse env-var defaults. See [Configuration](configuration.md). + ## Docker and Containerization Environment variables are particularly useful when running StructKit in containers: @@ -301,8 +407,10 @@ This should not happen - CLI arguments always take precedence. If you're experie ### Boolean environment variables not working correctly -For `STRUCTKIT_NON_INTERACTIVE`, only `true`, `1`, and `yes` (case-insensitive, e.g., `"True"`, `"TRUE"`, `"YeS"`) are recognized as true values. All other values are treated as false, including: +For `STRUCTKIT_NON_INTERACTIVE` and `STRUCTKIT_NO_HOOKS`, only `true`, `1`, and `yes` (case-insensitive, e.g., `"True"`, `"TRUE"`, `"YeS"`) are recognized as true values. All other values are treated as false, including: - `"true "` (with trailing space) - `"on"` or `"enable"` +`STRUCTKIT_DENY_NETWORK` is stricter: only the exact value `1` disables HTTP fetches. + Use one of the recognized values for reliable behavior. diff --git a/docs/github-integration.md b/docs/github-integration.md index 089f955..5170b91 100644 --- a/docs/github-integration.md +++ b/docs/github-integration.md @@ -23,6 +23,44 @@ jobs: When `struct_file` is omitted, the workflow uses `.structkit.yaml` if present and falls back to a legacy `.struct.yaml`. +## GitHub Action step (`httpdss/structkit-action`) + +For validate, generate, or a dry-run diff/drift check **as a step** in your own job (instead of calling the reusable workflow as a complete job), use [`httpdss/structkit-action`](https://github.com/httpdss/structkit-action). + +Validate: + +```yaml +- uses: actions/checkout@v7 +- uses: httpdss/structkit-action@v1 + with: + command: validate + struct_file: .structkit.yaml +``` + +Drift check (`generate` + `--dry-run --diff`): + +```yaml +- uses: httpdss/structkit-action@v1 + with: + command: generate + struct_file: .structkit.yaml + dry_run: true + diff: true + fail_on_diff: true +``` + +Generate: + +```yaml +- uses: httpdss/structkit-action@v1 + with: + command: generate + struct_file: .structkit.yaml + output_dir: . +``` + +The reusable workflow above is a full job with built-in PR creation. The action is a step you can mix with other checkout, test, or commit steps. See the [action README](https://github.com/httpdss/structkit-action) for full workflow examples and inputs. + ## Best Practices 1. **Secure Your Token**: Store GitHub tokens in secrets management tools. diff --git a/docs/index.md b/docs/index.md index 9e92860..fcd9834 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,6 +15,7 @@ Welcome to the comprehensive documentation for StructKit - the Automated Project - [YAML Configuration](configuration.md) - Complete configuration reference - [Template Variables](template-variables.md) - Working with dynamic content - [File Handling](file-handling.md) - Managing files and permissions +- [Environment Variables](environment-variables.md) - `STRUCTKIT_*` defaults and overrides ### Advanced Features @@ -36,10 +37,21 @@ Welcome to the comprehensive documentation for StructKit - the Automated Project - [Schema Reference](schema.md) - YAML validation and IDE support - [Examples](examples/index.md) - Practical examples and use cases +## 🔗 Ecosystem + +Companion install paths for StructKit (not separate products): + +- [structkit-action](https://github.com/httpdss/structkit-action) — validate, generate, or drift-check as a GitHub Actions step +- [structkit-pre-commit](https://github.com/httpdss/structkit-pre-commit) — validate structures before they land +- [vscode-structkit](https://github.com/httpdss/vscode-structkit) — schema and autocomplete for `.structkit.yaml` +- [homebrew-structkit](https://github.com/httpdss/homebrew-structkit) — `brew install httpdss/structkit/structkit` +- [backstage-plugin-structkit](https://github.com/httpdss/backstage-plugin-structkit) — scaffolder actions for platform teams +- [structkit-skills](https://github.com/httpdss/structkit-skills) — inspect, preview, generate, and validate from an assistant +- [hermes-plugin-structkit](https://github.com/httpdss/hermes-plugin-structkit) — safe StructKit tools inside Hermes + ## 🔗 External Resources - [GitHub Repository](https://github.com/httpdss/structkit) -- [StructKit Agent Skills](https://github.com/httpdss/structkit-skills) - [Articles and Tutorials](articles.md) - [Known Issues](known-issues.md) diff --git a/docs/installation.md b/docs/installation.md index 81aa831..ff63244 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -16,9 +16,24 @@ pip install structkit !!! tip "Enable Auto-Completion" After installation, enable command-line auto-completion using static scripts generated by shtab. See the [Command-Line Completion](completion.md) guide for per-shell instructions. -## From Source +## Using Homebrew -Clone the repository and install locally. See the [Development](development.md) page for details. +StructKit is published through the [`httpdss/homebrew-structkit`](https://github.com/httpdss/homebrew-structkit) tap (formula name: `structkit`). It is not a core Homebrew formula. + +```sh +brew install httpdss/structkit/structkit +``` + +Equivalent two-step form: + +```sh +brew tap httpdss/structkit +brew install structkit +``` + +```sh +structkit --help +``` ## Using Docker @@ -29,3 +44,35 @@ docker run -v $(pwd):/workdir -u $(id -u):$(id -g) ghcr.io/httpdss/structkit:mai ``` Refer to the [Quick Start](quickstart.md) guide for more options. + +## Linux packages (.deb / .rpm) + +Native `.deb` (Debian/Ubuntu) and `.rpm` (Fedora/RHEL) packages are built by the [`build-linux-packages`](https://github.com/httpdss/structkit/actions/workflows/build-linux-packages.yaml) GitHub Actions workflow on each published release and on manual workflow dispatch. They are uploaded as **Actions workflow artifacts** (90-day retention). They are **not** attached to GitHub Releases. + +To install a release package: + +1. Open the [build-linux-packages workflow runs](https://github.com/httpdss/structkit/actions/workflows/build-linux-packages.yaml) and select the run for the release you want. +2. Download the artifact for your architecture: + - `structkit-VERSION-amd64-deb` / `structkit-VERSION-arm64-deb` + - `structkit-VERSION-amd64-rpm` / `structkit-VERSION-arm64-rpm` +3. Install from the downloaded file. + +Debian/Ubuntu: + +```sh +sudo dpkg -i structkit_VERSION_amd64.deb +# if needed: sudo apt-get install -f +``` + +Fedora/RHEL: + +```sh +sudo dnf install ./structkit-VERSION-1.x86_64.rpm +# or: sudo rpm -ivh structkit-VERSION-1.x86_64.rpm +``` + +To build packages locally instead, follow [packaging/README.md](../packaging/README.md). + +## From Source + +Clone the repository and install locally. See the [Development](development.md) page for details. diff --git a/examples/config-layering/README.md b/examples/config-layering/README.md index d584d08..56286c1 100644 --- a/examples/config-layering/README.md +++ b/examples/config-layering/README.md @@ -4,13 +4,15 @@ This example demonstrates how to use structkit's config layering system to set d ## Overview -Structkit supports configuration at four levels (from lowest to highest priority): +StructKit supports CLI configuration at four levels (from lowest to highest priority): 1. **Built-in defaults** - Hard-coded baseline values -2. **User config** - Global defaults from `~/.config/struct/config.yaml` -3. **Project config** - Project-specific config from `.structkit.yaml` (legacy `.struct.yaml`) or `--config-file` +2. **User config** - Global defaults from `~/.config/struct/config.yaml` (loaded automatically when present) +3. **Project config** - Project-specific CLI defaults from `--config-file` only (`.structkit.yaml` is not auto-loaded) 4. **CLI arguments** - Command-line flags (highest priority) +`.structkit.yaml` is the structure definition used by `generate`/`validate`. Named structure sources are a separate file at `~/.config/structkit/sources.yaml` (see [Custom Structures](../../docs/custom-structures.md)). + ## Setup ### 1. Create a User Config @@ -136,14 +138,18 @@ backup: ~/structkit-backups ### Team Project Standards -Share project-specific settings in version control: +Share project-specific CLI defaults in version control and pass them with `--config-file`: ```yaml -# .structkit.yaml (checked into git) +# project-config.yaml (checked into git) structures_path: ./team-structures input_store: ./.structkit/input.json non_interactive: true ``` +```bash +structkit generate --config-file project-config.yaml +``` + ### Temporary Overrides Override for a single command: diff --git a/examples/config-layering/project-config-example.yaml b/examples/config-layering/project-config-example.yaml index 0cdc744..20d880f 100644 --- a/examples/config-layering/project-config-example.yaml +++ b/examples/config-layering/project-config-example.yaml @@ -1,7 +1,8 @@ # Example project config file # # This file can be checked into version control to share project-specific -# settings with your team. Use with --config-file or as .structkit.yaml +# CLI defaults with your team. Pass it with --config-file; it is not +# auto-loaded from .structkit.yaml (that file is the structure definition). # Project-specific structures location structures_path: ./custom-structures diff --git a/mkdocs.yml b/mkdocs.yml index f038f9c..6a174b6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: StructKit Documentation site_description: Automated Project Structure Generator -site_url: https://httpdss.github.io/structkit/ +site_url: https://structkit.app/docs/ repo_url: https://github.com/httpdss/structkit repo_name: httpdss/structkit @@ -62,8 +62,10 @@ nav: - Template Variables: template-variables.md - File Handling: file-handling.md - Mappings: mappings.md + - Environment Variables: environment-variables.md - Advanced Features: - - Custom Structures: structures.md + - Built-in Structures: structures.md + - Custom Structures: custom-structures.md - Hooks: hooks.md - GitHub Integration: github-integration.md - MCP / AI Agent Workflow: mcp-integration.md @@ -74,6 +76,7 @@ nav: - Command-Line Completion: completion.md - Contributing: contributing.md - Reference: + - CLI Reference: cli-reference.md - Examples: examples/index.md - Articles and Tutorials: articles.md - Known Issues: known-issues.md @@ -107,4 +110,4 @@ extra_css: - stylesheets/extra.css extra: - homepage: https://httpdss.github.io/structkit/ + homepage: https://structkit.app/ diff --git a/packaging/README.md b/packaging/README.md index b5b766e..2c99a03 100644 --- a/packaging/README.md +++ b/packaging/README.md @@ -95,10 +95,12 @@ The built packages will be in the `dist/` directory: ## Installing Packages +Packages are **not** attached to GitHub Releases. Download them from the [build-linux-packages](https://github.com/httpdss/structkit/actions/workflows/build-linux-packages.yaml) workflow run artifacts for the release, or build them locally with the steps above. + ### Debian/Ubuntu ```bash -# Download the .deb package, then: +# Download the .deb artifact from the workflow run, then: sudo dpkg -i structkit_VERSION_amd64.deb # If there are dependency issues, resolve them with: @@ -108,7 +110,7 @@ sudo apt-get install -f ### Fedora/RHEL ```bash -# Download the .rpm package, then: +# Download the .rpm artifact from the workflow run, then: sudo dnf install ./structkit-VERSION-1.x86_64.rpm # Or using rpm directly: @@ -135,6 +137,7 @@ The workflow: - Builds packages for both `amd64` and `arm64` architectures - Creates both `.deb` and `.rpm` packages (4 total artifacts) - Uploads packages as GitHub Actions artifacts (90-day retention) +- Does **not** attach packages to GitHub Releases - Can be triggered with a custom version via workflow dispatch ### Triggering a Manual Build diff --git a/structkit/config.py b/structkit/config.py index a41afe4..5909d77 100644 --- a/structkit/config.py +++ b/structkit/config.py @@ -1,12 +1,18 @@ """Configuration layering system for structkit. -Supports loading and merging configuration from multiple sources: +Supports loading and merging CLI configuration from multiple sources: 1. Built-in defaults -2. User config (~/.config/struct/config.yaml) -3. Project config (.structkit.yaml, legacy .struct.yaml, or --config-file) +2. User config (~/.config/struct/config.yaml) — loaded automatically when present +3. Project config from --config-file only (not auto-loaded from .structkit.yaml) 4. CLI arguments -Priority order: CLI args > Project config > User config > Built-in defaults +Priority order: CLI args > --config-file > user config > built-in defaults + +.structkit.yaml (and legacy .struct.yaml) is the structure definition used by +generate/validate/etc., not a layered CLI config file. + +Named structure sources live in a separate file +(~/.config/structkit/sources.yaml, overridable via STRUCTKIT_SOURCES_CONFIG). """ import os @@ -97,10 +103,11 @@ def load_layered_config(project_config_path: Optional[str] = None) -> Dict[str, Merge order (lowest to highest priority): 1. Built-in defaults 2. User config (~/.config/struct/config.yaml) - 3. Project config (if provided) + 3. Project config from --config-file, if provided + (.structkit.yaml is not auto-loaded here) Args: - project_config_path: Path to project-specific config file + project_config_path: Path from --config-file, or None Returns: Merged configuration dictionary diff --git a/structkit/contribs/github/prompts/struct.yaml b/structkit/contribs/github/prompts/struct.yaml index fb11b91..ecbc209 100644 --- a/structkit/contribs/github/prompts/struct.yaml +++ b/structkit/contribs/github/prompts/struct.yaml @@ -9,7 +9,7 @@ files: ## Role - You are an expert assistant that generates valid `.structkit.yaml` files for the [StructKit tool](https://github.com/httpdss/struct), which automates project structure generation from YAML configuration. + You are an expert assistant that generates valid `.structkit.yaml` files for the [StructKit tool](https://github.com/httpdss/structkit), which automates project structure generation from YAML configuration. ## Defining the `.structkit.yaml` file From 2e71978a6dceb0bfb1389c5f19a77e689c4c9581 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 8 Oct 2026 09:29:33 +0000 Subject: [PATCH 2/2] docs: point Linux package local-build link at GitHub packaging README MkDocs cannot resolve ../packaging/README.md from docs_dir, so use the repository URL instead of a broken relative path. Co-authored-by: Kenneth Belitzky --- docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index ff63244..8290b1b 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -71,7 +71,7 @@ sudo dnf install ./structkit-VERSION-1.x86_64.rpm # or: sudo rpm -ivh structkit-VERSION-1.x86_64.rpm ``` -To build packages locally instead, follow [packaging/README.md](../packaging/README.md). +To build packages locally instead, follow [packaging/README.md](https://github.com/httpdss/structkit/blob/main/packaging/README.md). ## From Source