Skip to content
quotentirolerPublic

About

AI-powered configuration manager with visual editing, intelligent rules, and an MCP server for AI assistant integration.

Topics

Resources

Code of conduct

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

93 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Guido - Configuration Template Manager

Guido

A visual configuration management tool for creating, editing, and validating application settings with intelligent rule-based automation.

Version

React 19 TypeScript Vite Tailwind CSS License

Coverage Tests Build Size

Live Demo β€’ Quick Start β€’ Features β€’ Documentation


What is Guido?

Guido is a web-based GUI application that simplifies the management of complex configuration files. Instead of manually editing JSON, YAML, or other config formats, Guido provides:

  • Visual editing of configuration fields with validation
  • Intelligent rules that automatically enable/disable settings based on conditions
  • Template system with reusable configuration schemas
  • Multi-format support for JSON, YAML, CSV, .env, .properties, and .txt files

Quick Start

Use the Hosted App

Visit quotentiroler.github.io/Guido to use Guido directly in your browser.

Run Locally

# Clone the repository
git clone https://github.com/quotentiroler/Guido.git
cd Guido

# Install dependencies
npm install

# Start development server
npm run dev

Open http://localhost:5173 in your browser.

Features

πŸŽ›οΈ Visual Configuration Editor

Edit configuration fields through an intuitive UI with:

  • Field metadata (descriptions, examples, documentation links)
  • Real-time validation (integers, booleans, URLs, regex patterns, enums)
  • Checkbox-based field selection for export

πŸ”— Rule Engine

Define conditional logic that automatically manages field dependencies:

If "Repository" is set to "MongoDb"
Then "MongoDbOptions.ConnectionString" must be set

Rule States:

State Description
set Field must be enabled and have a value
set_to_value Field must equal a specific value
contains Field contains value as a discrete item: an array element, or (for a string) an exact match. Not a substring match
gt / lt / gte / lte Numeric comparison of the field value against value (condition-only)

πŸ€– MCP Server (AI Integration)

The included MCP (Model Context Protocol) server enables AI assistants like Claude to manage Guido templates programmatically.

Documentation

Template Structure

A .guido.json template consists of:

{
  "name": "My App Settings",
  "fileName": "appsettings.json",
  "version": "1.0.0",
  "description": "Configuration template for My App",
  "owner": "MyOrganization",
  "application": "My App",
  "docs": "https://docs.example.com",
  "command": "docker run myapp:latest",
  "fields": [...],
  "ruleSets": [...]
}

Field Definition

Each field describes a configuration option:

{
  "name": "Database.ConnectionString",
  "value": "Server=localhost;Database=mydb",
  "info": "Connection string for the primary database",
  "example": "Server=localhost;Database=mydb;User=admin",
  "range": "string",
  "link": "https://docs.example.com/connection-strings",
  "checked": true
}

Field Properties:

Property Type Description
name string Field identifier (use dots for nesting:Section.Subsection.Key)
value string| number | boolean | string[] Default value
info string Description shown in tooltip
example string Example value
range string Validation rule (see below)
link string? URL to documentation
checked boolean? Whether field is enabled for export
secret boolean? Never printed with a value in generated files or messages

Range Types:

Range Description
string Any string value (unbounded)
boolean Must be true or false
integer Must be a whole number
integer(min..max) Integer within range (e.g., integer(1..65535))
string(min..max) String with length limits (e.g., string(0..255))
url Must be a valid URL
string[] Array of strings
integer[] Array of integers
string[min..max] Array with size limits (e.g., string[1..10])
opt1||opt2||opt3 Must match one of the options
(opt1||opt2)[] Array of options ((opt1||opt2)[min..max] limits its size)
^regex$ Must match the regex pattern; a range anchored with ^ or $ is always a regex

In flat settings files (.env, .properties, .ini, .txt, command-line args) an array-typed field is written as a comma list: SPRING_PROFILES_ACTIVE=production,metrics. An empty value (KEY=) counts as unset.

Rule Definition

Rules define conditional relationships between fields:

{
  "description": "MongoDB requires connection string",
  "conditions": [
    { "name": "Repository", "state": "set_to_value", "value": "MongoDb" }
  ],
  "targets": [
    { "name": "MongoDbOptions.ConnectionString", "state": "set" }
  ]
}

Logic: If the conditions match, then ALL targets are enforced. Conditions combine per the rule's match: all (default, AND - every condition must hold) or any (OR - at least one).

Cardinality Constraints

A ruleset can also declare cardinality constraints over a set of fields (validated against a config, not applied as rules):

{
  "constraints": [
    { "kind": "exactly-one", "fields": ["MongoDb", "SQLite", "Postgres"] }
  ]
}

kind is exactly-one (exactly 1 of the fields set), at-least-one (>= 1), at-most-one (<= 1), or all-or-none (none or every field, e.g. a certificate and its key). A field counts as set when it is enabled with a non-empty value.

RuleDomain Properties:

Property Type Description
name string Field name to evaluate/affect
state set | set_to_value | contains | gt | lt | gte | lte Condition/target type
value string? Value for set_to_value, contains, or the numeric comparisons
valueField string? Compare against another field's value instead of value (e.g. MinPort lte field MaxPort). Condition-side; for set_to_value and the numeric comparisons
not boolean? Negate the condition/target

Known Limitations

Dynamic Arrays of Complex Objects

Guido cannot describe configuration structures with dynamic arrays of complex objects where users need to add/remove items at runtime. The dot notation flattening (e.g., Plugins.0.Name, Plugins.1.Name) works for fixed-size arrays but not for unbounded collections.

Pattern Example Supported
Nested objects Database.Connection.Host βœ…
Simple arrays AllowedOrigins with range: "string[]" βœ…
Fixed-size object arrays Servers.0.Host, Servers.1.Host βœ…
Dynamic object arrays Unlimited plugin definitions ❌

CLI Tools

Validate Templates

npm run validate "path/to/template.guido.json"

Checks for:

  • Rule contradictions
  • Circular dependencies
  • Invalid rule structures
  • Field validation issues

Convert JSON Schema to Guido

npm run schema-to-guido "schema.json" -o "output.guido.json" \
  --name "My Template" \
  --version "1.0.0" \
  --owner "MyOrg" \
  --application "My App" \
  --docs "https://docs.example.com"

Convert Guido to JSON Schema

npm run guido-to-schema "template.guido.json" -o "output.schema.json"

Configuration Contract

guido-contract keeps a template, the code that reads its settings, the docs and env example generated from it, and every environment's settings in agreement. It reads guido.contract.json (--config to override; guido-contract schema prints its JSON Schema):

{
  "template": "app.guido.json",
  "scan": {
    "files": [{ "include": ["src/**/*.ts"], "exclude": ["**/*.test.ts"], "patterns": ["process-env", "workers-env"] }],
    "ignore": ["CI"],
    "ignoreBindingsFrom": ["wrangler.toml"]
  },
  "generate": {
    "docs": { "path": "docs/environment-variables.md" },
    "envExample": { "path": ".env.example", "requiredRuleset": "Deployed" }
  },
  "targets": [
    { "name": "prod", "source": { "type": "compose", "path": "docker-compose.prod.yml", "service": "api" }, "ruleset": "Deployed", "strict": true },
    { "name": "edge", "source": { "type": "wrangler", "path": "wrangler.toml", "env": "production", "secrets": { "file": "secrets.json" } }, "tag": "edge" }
  ]
}
guido-contract check     # generated files current, code reads match the template's fields
guido-contract generate  # rewrite <!-- guido:fields #anchor --> tables and the env example
guido-contract validate [--target prod]
guido-contract all
  • Scan patterns: process-env, env-helper-call (intEnv('X')), workers-env (env.X, c.env.X, destructuring), import-meta-env, spring-placeholder, java-getenv, or { "regex": "...", "flags": "m" } with one capture group.
  • Sources: dotenv, file (json, yaml, ini, properties, ... via format), compose (${X:-d} gives d, ${X} is supplied at deploy time; interpolate resolves references from another source), wrangler (toml/json/jsonc vars of the top level or one env), spring (dir, layered profiles), secrets (names only), values (literals) and merge. Every source takes secrets (names supplied at deploy time, inline or from a file such as wrangler secret list --format json), select (keep and rename keys) and excludePrefixes.
  • Keys supplied at deploy time count as present; their values are not range- or rule-checked. Paths resolve against root (default: the config's directory). With GITHUB_ACTIONS set, problems print as ::error:: annotations.

Available Scripts

Script Description
npm run dev Start development server
npm run build Build for production
npm run preview Preview production build
npm run test Run tests
npm run test:watch Run tests in watch mode
npm run lint Run ESLint
npm run deploy Deploy to GitHub Pages

Technology Stack

  • Frontend: React 19, TypeScript, Tailwind CSS
  • Build: Vite, npm workspaces (monorepo)
  • Testing: Vitest
  • Deployment: GitHub Pages

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Before contributing, please read our Code of Conduct.

Quick Start for Contributors

# Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/Guido.git
cd Guido

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2024-2025 Maximilian Nussbaumer

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

About

AI-powered configuration manager with visual editing, intelligent rules, and an MCP server for AI assistant integration.

Topics

Resources

Code of conduct

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages