Framed is a CLI tool that simplifies the organization and management of files and directories in a reusable and architectural manner. It provides YAML templates for defining project structures and enables workflows based on those.

To always be in sync with the YAML template, Framed provides a built-in test command that can be used in CI/CD pipelines to verify the project structure.

• YAML Templates: Framed uses YAML templates to define the entire project structure.

• Always in Sync: Framed provides a built-in test command that can be used in CI/CD pipelines to verify the project structure and ensure that it is always in sync with the YAML template.

• Consistency Across Projects: Framed offers a consistent way of organizing files and directories across different projects.

To get started with Framed, you can use the following example:

# Framed Configuration
name: framed

structure:
  name: root
  maxDepth: 5 # Disallow dirs deeper than 5
  files:
    - README.md
    - framed.yaml
    - main.go
    - go.mod
    - go.sum
    - .gitignore
  dirs:
    - name: cmd
      allowedPatterns:
        - ".go"
      forbiddenPatterns:
        - "_test.go" # Disallow tests in /src
    - name: pipelines
      maxCount: 2
      allowedPatterns:
        - ".yml"
        - ".yaml" # only yaml files allowed
      files:
        - pr.yaml
    - name: dockerfiles
      minCount: 1 # At least one file has to be there
      allowChildren: false # Allow subdirectories creation, default true
      allowedPatterns:
        - ".dockerfile"
    - name: docs
      maxCount: 10 # No more than 10 files per dir
      allowedPatterns:
        - ".md"
        - ".txt"
      dirs:
        - name: design
    - name: examples

Framed allows you to define the desired structure of your project using a YAML-based configuration file. The configuration specifies the required files and directories that should exist in the project.

The structure section defines the files that are required at the root level of the project. These files must be present for the project to be considered valid.

The dirs section allows you to define nested directories within the project structure. Each subdirectory can have its own set of required files and directories.

You can specify file requirements using the files property. It ensures that specific files are present within the designated directory.

The allowedPatterns property enables you to define file patterns using glob syntax. This allows for more flexible matching of files based on their extensions or naming conventions.

The forbiddenPatterns property lets you specify file patterns that are not allowed within a directory. This can be useful for enforcing certain naming conventions or excluding specific types of files.

The minCount property allows you to set a minimum count for files within a directory. It ensures that a certain number of files must be present in the directory.

The maxCount property allows you to set a maximum count for files within a directory. It limits the number of files that can exist within the directory.

The allowChildren property, when set to true, permits the presence of additional directories within a specified directory. This provides flexibility for organizing files and directories within the project.

1. Open a terminal and run the following command:

   brew tap mactat/mactat
   brew install framed

1. Download the framed-darwin-amd64-<version>.tar.gz package from release page.

2. Extract the package by double-clicking on the downloaded file or using a tool like tar in your terminal:

   tar -xzf framed-darwin-amd64-<version>.tar.gz

3. This will extract the framed binary.

4. Open a terminal and navigate to the extracted directory:

   cd framed-darwin-amd64-<version>

5. Make the binary executable by running the following command:

   chmod +x framed

6. Move the framed binary to a directory in your system's PATH so that it can be accessed from anywhere. For example:

   sudo mv framed /usr/local/bin/

7. You can now use the framed command to execute the application.

1. Download the framed-linux-amd64-<version>.tar.gz package from release page.

2. Extract the package using the following command in your terminal:

   tar -xzf framed-linux-amd64-<version>.tar.gz

3. This will extract the framed binary.

4. Open a terminal and navigate to the extracted directory:

   cd framed-linux-amd64-<version>

5. Make the binary executable by running the following command:

   chmod +x framed

6. Move the framed binary to a directory in your system's PATH so that it can be accessed from anywhere. For example:

   sudo mv framed /usr/local/bin/

7. You can now use the framed command to execute the application.

1. Download the framed-windows-amd64-<version>.tar.gz package from release page.

2. Extract the package using a file extraction tool like 7-Zip or WinRAR.

3. This will extract the framed.exe binary.

4. Move the framed.exe binary to a directory that is included in your system's PATH, such as C:\Windows or C:\Windows\System32.

5. You can now use the framed command to execute the application from the Command Prompt or PowerShell.

Please note that the exact steps may vary depending on your system configuration.

Note: The following commands assume that you have already installed Framed and added it to your system's PATH environment variable.

Note: By default template file is framed.yaml. You can specify a different template file using the --template flag f.e --template path/to/my-template.yaml.

To create a new project structure using a YAML template, run the following command:

framed create

If you also want to create required files, run the following command:

framed create --files

To capture the current project structure as a YAML template, run the following command:

framed capture --output <template-file>

To test the project structure for consistency and compliance with the YAML template, run the following command:

framed verify

For a complete list of available commands and usage examples, refer to the documentation.

To visualize the project structure, run the following command:

framed visualize

To import the project structure from url, run the following command:

framed import --url <url>

url has to be pointing to a yaml file with valid structure.

To import an example project structure, run the following command:

framed import --example <example-name>

Currently available examples:

• python
• golang

See examples for more details.

To run framed from docker, run the following command:

docker run --rm -v $(pwd):/app --user $(id -u):$(id -g) mactat/framed framed <command>

example:

docker run --rm -v $(pwd):/app --user $(id -u):$(id -g) mactat/framed framed import --example python

Images can be found on dockerhub.

You can use framed as a github action to verify your project structure. Minimal example:

name: Verify Project Structure
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Verify Project Structure
        uses: mactat/[email protected]
        with:
          template: './framed.yaml' # Optional, default is framed.yaml
          version: 'v0.0.8'         # Optional, default is v0.0.8

• Add support from importing part of the structure from url or file like:

  name: framed
  
  structure:
    name: root
    dirs:
      - name: other
        template: other.yaml # Use another template for this dir
      - name: another
        template: https://yourfile.com/framed.yaml # Share templates between projects

• Add some tests

• Add contributing guidelines

• Add more examples

• Create a github action for running tests

• Move remaining business logic to a separate package