.zzz ZSH Configuration Framework

Project Management

This repository is connected to Linear for project management and issue tracking:

• Linear Workspace: Matkoson's Linear workspace
• Linear Team: ZZZ (key: ZZZ, ID: 00e028ac-e68c-4c2f-bf5c-a411d319e107)
• Project: ZZZ Shell Framework
• Integration: Team-level GitHub integration
• Issue References: Use ZZZ-# in branch names and commit messages (e.g., ZZZ-1-feature-name)

For detailed instructions on creating tasks, updating status, and synchronizing changelog entries with Linear comments, see HOW_TO_MAINTAIN_LINEAR.md.

For integration details, see CHANGELOG/2025-04-04_linear_github_integration.md.

Branch Management

CRITICAL: All development work MUST be done on the development branch

• The development branch is the primary branch for all development work
• The master branch is the stable, production-ready branch
• Pull requests MUST ONLY be created from development to master
• Do NOT create feature branches unless explicitly instructed otherwise
• All changes must be thoroughly tested on the development branch before being considered for merging to master

Guidelines for Development

Before starting any development work, it is MANDATORY to review the following guidelines:

• Augment Guidelines: See .augment-guidelines for comprehensive development guidelines
• Behavior Guidelines: See 0-docs/behavior/augment_guidelines.md for detailed behavior guidelines
• DO Guidelines: See 0-docs/solutions/1-DO/do.md for required best practices
• DON'T Guidelines: See 0-docs/solutions/2-DONT/dont.md for practices to avoid

🔥 MANDATORY: The Hyper Comment Rule

This rule is NON-NEGOTIABLE and strictly enforced.

• Requirement: Every single line of code MUST have a detailed explanatory comment placed directly above it.
• Shell Command Emphasis: Comments for shell commands are ESPECIALLY CRITICAL and MUST include:
  1. A clear explanation of what the command does.
  2. A detailed explanation of EVERY flag and option used.
  3. Explicit confirmation from the author that the command with those specific flags/options has been tested and verified to work correctly on Zsh on macOS.
• Rationale: Untested or misunderstood shell commands and flags are the #1 source of runtime errors in this framework. Adherence to this rule is essential for stability and maintainability.
• Enforcement: Failure to comply WILL result in rejection.

See the MUST Guidelines for the canonical definition.

🔒 MANDATORY: Dry Run First for Modifying Scripts

• Any script that modifies the file system MUST operate in Dry Run mode by default when run interactively.
• It MUST first show the user exactly what changes would occur.
• It MUST then require explicit user confirmation before making any actual changes.

👍 MANDATORY: Strict 'Y' Confirmation

• When scripts require user confirmation to proceed (especially after a dry run), only a literal uppercase 'Y' is accepted as affirmative.
• All other inputs MUST be treated as negative/cancel.

🤖 MANDATORY: Non-Interactive Mode & Verification

• Scripts in bin/ modifying the filesystem MUST support a --non-interactive flag for automated execution.
• In non-interactive mode, prompts are suppressed (confirmation assumed).
• Crucially, non-interactive mode REQUIRES an additional argument specifying the expected outcome of the first operation (e.g., the target path of the first file move).
• The script MUST perform an internal dry run, compare the simulated result of the first operation to the expected result, and only proceed with actual changes if they match exactly.

Naming Conventions

• Directories: Use kebab-case for all directory names (e.g., line-limit, source-tracking)
  • Exceptions: Special directories like CHANGELOG, etc.
• Files: Use snake_case for all file names (e.g., line_limit.zsh, source_lib.zsh)
  • Exceptions: Special files like README.md, CONTRIBUTING.md, etc.

ZSH Startup Process Architecture

This repository uses a non-standard Zsh startup process:

1. The home directory (~/.zshenv) sets ZDOTDIR="$HOME/.zzz" and then sources $HOME/.zzz/.zshenv
2. This redirects Zsh to look for config files in ~/.zzz/ instead of the home directory
3. The startup sequence continues with:
   • ~/.zzz/.zshenv → sources ~/.zzz/1-zshenv/zshenv.zsh
   • ~/.zzz/.zshrc → sources ~/.zzz/2-zshrc/zshrc.zsh

IMPORTANT:

• NEVER create config files in the user's home directory
• All changes should be made to files within the ~/.zzz directory structure
• DO NOT create ~/.zshrc as it will cause circular sourcing issues

AI Assistance with cursor-tools

This project uses cursor-tools to integrate AI assistance into the development workflow. Here are key recommendations for optimal usage:

Optimizing Gemini Repository Context

When using cursor-tools to analyze the codebase with Gemini, use the --subdir flag to limit the context to specific subdirectories. This significantly reduces token consumption and provides more focused results:

# Analyze only the pre-commit hooks directory
cursor-tools repo "Explain the pre-commit implementation" --subdir=pre-commit/bin

# Focus on specific components
cursor-tools repo "Analyze the logger implementation" --subdir=1-zshenv/src/functions

# Reduce token usage when exploring a specific feature
cursor-tools repo "How does the configuration system work?" --subdir=2-zshrc/src/1-core/0-lib

When dealing with large codebases, always prefer using the --subdir flag over sending the entire repository context to get more relevant and detailed responses from Gemini.

Overview

This project provides a dynamic script generation system for Keyboard Maestro macros. It allows you to define macro templates and configurations that can be used to generate Keyboard Maestro macro XML files.

Features

• Preset-based architecture: Create different sets of macros organized by preset folders
• Template-based generation: Use XML templates with variables for flexible macro creation
• Type-safe configuration: Environment variables with validation and type checking
• Command-line interface: Generate macros for specific presets or all presets at once
• Enhanced error handling: Detailed error messages with context and recovery options
• Template validation: Validates templates for required placeholders and XML structure
• Improved preset discovery: Rich logging and validation of preset components
• Modular code structure: Refactored for better testability and maintainability

Recent Improvements

• Modular design: Core functions have been refactored into smaller, more focused helper functions
• Improved error reporting: More detailed error messages with context about the issue
• Better file operations: Enhanced file reading and writing with validation and recovery options
• Template validation: Ensures templates contain required placeholders and have proper XML structure
• Enhanced logging: More comprehensive logging during preset discovery and macro generation
• Improved testability: Key functions are now exported for better unit testing coverage

Project Structure

.config/keyboard-maestro/dynamic/
├── scripts/                   # Main script files
│   ├── __test__/              # Test directory
│   │   └── generate-preset.test.ts  # Tests for the generator
│   ├── env.ts                 # Environment configuration
│   ├── generate.ts            # Macro generation logic
│   └── index.ts               # CLI entry point
├── preset/                    # Preset directories
│   ├── preset-name-1/         # Example preset
│   │   ├── xml-templates/     # XML templates
│   │   │   ├── macro_template.xml
│   │   │   └── ...
│   │   ├── config/            # Configuration files
│   │   │   └── config.json    # Macro definitions
│   │   └── out/               # Generated output
│   └── preset-name-2/
│       └── ...
└── .env.local                 # Local environment variables

Installation

1. Clone this repository or copy the files to your .config/keyboard-maestro/dynamic directory:

git clone https://github.com/yourusername/keyboard-maestro-dynamic.git ~/.config/keyboard-maestro/dynamic

2. Install dependencies:

cd ~/.config/keyboard-maestro/dynamic
bun install

3. Create a .env.local file with your environment variables (see Environment Variables section)

Usage

Generating Macros

To generate macros for all presets:

bun run generate

To generate macros for a specific preset:

bun run generate preset-name

Creating Your Own Presets

1. Create a new directory in the preset folder
2. Add your XML templates in the xml-templates folder
3. Create a config.json file in the config folder with your macro definitions
4. Run the generator to create your macros

Macro Configuration Format

The config.json file should have the following structure:

{
  "macros": [
    {
      "name": "Macro Name",
      "icon": "Icon Data",
      "path": "/path/to/file",
      "subroutineUID": "UUID-OF-SUBROUTINE",
      "type": "ExecuteSubroutine"
    },
    // More macro definitions...
  ]
}

Environment Variables

The system uses environment variables for configuration. Create a .env.local file with these variables:

# Paths
TEMPLATES_DIR="xml-templates"
CONFIG_FILE="config/config.json"
OUTPUT_DIR="out"

# Template files
MACRO_TEMPLATE="macro_template.xml"
ACTION_EXECUTE_SUBROUTINE_TEMPLATE="action_execute_subroutine.xml"
ACTION_GROUP_TEMPLATE="action_group.xml"
VARIABLE_SET_VARIABLE_TO_TEXT_TEMPLATE="variable_set_variable_to_text.xml"

# ID Generation
BASE_UID_MINIMUM=11580000
BASE_UID_RANDOM_RANGE=1000000
NUM_IDS_TO_GENERATE=6

# Logging
LOG_INFO_PREFIX="[INFO]"
LOG_ERROR_PREFIX="[ERROR]"

Template Variables

Templates use {{variable_name}} syntax for replacement. Common variables include:

• {{name}} - The macro name
• {{id0}}, {{id1}}, etc. - Generated unique IDs
• {{uid}} - Unique identifier for the macro
• {{icon}} - Icon data
• {{creation_date}} - Creation timestamp
• {{modification_date}} - Modification timestamp
• {{path}} - Path to the file
• {{subroutine_uid}} - UID of the subroutine to execute

Development

Running Tests

bun test

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b new-feature
3. Commit your changes: git commit -am 'Add new feature'
4. Push to the branch: git push origin new-feature
5. Submit a pull request

License

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