path: root/src/main.zig

const options = @import("options");
const std = @import("std");
const assert = std.debug.assert;

const cli = @import("cli.zig");
const fs = @import("fs.zig");
const conf = @import("conf.zig");
const tmpl = @import("template.zig");
const tree = @import("tree.zig");
const port = @import("port.zig");
const git = @import("git.zig");
const Env = @import("env.zig");
const Time = @import("time.zig").Time;

const default_tree_name = "default";

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();

    var main_cmd: Main_Command = undefined;
    var args: cli.Args = try .init(allocator, "porteur", &main_cmd);
    defer args.deinit(allocator);
    try main_cmd.execute(allocator, &args);
}

const Main_Command = struct {
    pub const help = cli.Command_Help{
        .name = "porteur",
        .synopsis = &.{
            "porteur [--etc=⟨path⟩] tree ⟨command⟩ [options] [⟨args⟩]",
            "porteur [--etc=⟨path⟩] tmpl ⟨command⟩ [options] [⟨args⟩]",
            "porteur [--etc=⟨path⟩] port ⟨command⟩ [options] [⟨args⟩]",
            "porteur help [⟨command⟩ [⟨subcommand⟩]]",
        },
        .short_description = "Build your own ports.",
        .long_description = std.fmt.comptimePrint(
            \\Porteur is a tool for managing and creating custom ports from a Git repository.
            \\Each port is part of a ports tree and results in a FreeBSD port usable by
            \\`make` or `poudriere`. It uses a template to generate the files that describe
            \\how to build the application from source code.
            \\
            \\To add a new port some basic information (e.g. name, category) needs to be
            \\provided including a Git repository where the source code can be found. Porteur
            \\always uses the configured branch of the Git repository and operates only on
            \\that version of the source code. When a port is updated, porteur checks the
            \\latest commit on this branch and updates the port information accordingly.
            \\
            \\Each port lives in a ports tree which can be used by the FreeBSD ports system.
            \\When operating on ports there must always be a tree specified. If no tree name
            \\is provided explicitly the default tree `{[default_tree]s}` will be used.
        , .{ .default_tree = default_tree_name }),
        .extra_sections = &.{
            .{
                .heading = "TEMPLATES",
                .body =
                \\Each FreeBSD port consists of a collection of files that automate the
                \\compilation of an application. Since each port in the FreeBSD ports
                \\tree requires its own set of files, maintaining them can be tedious,
                \\especially when large parts of the content is identical.
                \\
                \\To make the definition of such files reusable, porteur uses templates,
                \\located in the `⟨etc⟩/porteur/tmpl/` directory (see FILES). Each port
                \\must reference a template and defines the variables used within it.
                \\
                \\A template is a collection of files that will used to render a port
                \\usable by FreeBSD. Each file can use variables to render port specific
                \\data, where a variable `v` can be referenced with the placeholder
                \\`{{v}}`. It is also possible to use variables in filenames. For more
                \\information how to define variables, see the VARIABLES section.
                \\
                \\Normally, the processed template files are used to create the port
                \\files, the distribution file is created, and a distinfo is generated.
                \\To have more control over this process, a template can define a file
                \\named `.config` in its root directory. For a documentation of all
                \\configurable options, see the sample configuration file (see FILES).
                ,
            },
            .{
                .heading = "VARIABLES",
                .body =
                \\Variables are used to substitute port specific values in templates.
                \\Defining variables is file-based and has the following syntax:
                \\
                \\    key = value
                \\
                \\Keys define the variable name that can later be referenced (e.g. in
                \\a template file) and the assigned value is the string that replaces
                \\this key. Leading and trailing whitespace in a value is trimmed.
                \\Normally, a key/value pair is defined on a single line, but multi-line
                \\values are also supported:
                \\
                \\    key = value line one
                \\        = value line two
                \\        =
                \\        = value line three
                \\
                \\Each continuation line starts with an empty key and is rendered as a
                \\separate line in the template. This also allows empty lines to be
                \\part of the value. Again, leading and trailing whitespace of each line
                \\is trimmed.
                \\
                \\To avoid redefining common information already known (e.g., port name,
                \\port version), porteur predefines certain variables. All predefined
                \\variable names start with a dot (`.`), so it is recommended not to use
                \\custom variables starting with a dot.
                \\
                \\List of predefined variables:
                \\
                \\    .portname    - Name of the port
                \\    .portversion - Current version of the port
                \\    .category    - Category of the port
                \\    .distdir     - Directory containing all distfiles
                \\    .distname    - Name of the archive file containing the distribution
                ,
            },
            .{
                .heading = "DISTFILES",
                .body =
                \\To compile a port, a distribution is necessary that contains the source
                \\code. Porteur creates a gzipped archive of the Git repository and puts
                \\it in the configured `distfiles-dir`. The filename of this archive is
                \\provided in the `.dist.name` variable and the directory where its put in
                \\is provided in the `.dist.dir` variable (see VARIABLES). So the template
                \\can reference the archive's location and tell FreeBSD where to find the
                \\source code.
                \\
                \\Sometimes it is necessary to do extra steps before the distribution is
                \\created (e.g. vendoring). These steps can be defined as a target in the
                \\port Makefile of the template. When porteur executes this target it will
                \\set ${WRKSRC} to the port's source tree. The target name can be defined
                \\with `dist-prepare-target` in the template's configuration file (see
                \\TEMPLATES).
                ,
            },
            .{
                .heading = "FILES",
                .body = std.fmt.comptimePrint(
                    \\Porteur uses two locations where data will be stored. The first location
                    \\is `{[prefix]s}/etc/` and contains all configuration files (ports and
                    \\templates). This location can be overwritten with the --etc flag. The
                    \\second location is `{[prefix]s}/porteur/` and contains a copy of the
                    \\sources and all generated port files that FreeBSD uses.
                    \\
                    \\The following directory structure is used:
                    \\
                    \\    {[prefix]s}/etc/porteur/porteur.conf
                    \\        Configuration file for porteur.
                    \\
                    \\    {[prefix]s}/etc/porteur/porteur.conf.sample
                    \\        Sample configuration file for porteur.
                    \\
                    \\    {[prefix]s}/etc/porteur/template.conf.sample
                    \\        Sample configuration file for a template.
                    \\
                    \\    {[prefix]s}/etc/porteur/ports/<tree>/
                    \\        Configuration for each port.
                    \\
                    \\    {[prefix]s}/etc/porteur/tmpl/⟨template⟩/
                    \\        Template definitions used by the ports.
                    \\
                    \\    {[prefix]s}/porteur/ports/⟨tree⟩/
                    \\        Generated ports tree used by FreeBSD.
                    \\
                    \\    {[prefix]s}/porteur/src/⟨tree⟩/
                    \\        Copies of the sources for each port.
                    \\
                    \\    {[prefix]s}/porteur/.wrk/
                    \\        Working directory for porteur.
                , .{ .prefix = options.path_prefix }),
            },
        },
    };

    options: struct {
        etc: cli.Option([]const u8, .{
            .name = "etc",
            .argument_name = "path",
            .short_description = "The path to porteur's configuration directory.",
            .long_description = std.fmt.comptimePrint(
                \\The path of the directory porteur is storing its configuration.
                \\Defaults to `{[prefix]s}/etc/`. See the FILES section for more
                \\information.
            , .{ .prefix = options.path_prefix }),
            .default_value = options.path_prefix ++ "/etc/",
        }),
    },

    pub const Subcommands = union(enum) {
        help: Help_Command,
        tmpl: Tmpl_Command,
        tree: Tree_Command,
        port: Port_Command,
    };

    pub fn execute(self: *Main_Command, allocator: std.mem.Allocator, args: *cli.Args) !void {
        const subcmd = args.next_subcommand(Main_Command) orelse {
            cli.print_usage(cli.stdout, Main_Command);
            return;
        };

        const etc_path = self.options.etc.value_or_default();
        const env: Env = .init(allocator, etc_path, args);
        switch (subcmd) {
            .help => |cmd| cmd.execute(env),
            .tmpl => |cmd| cmd.execute(env),
            .tree => |cmd| cmd.execute(env),
            .port => |cmd| cmd.execute(env),
        }
    }
};

const Help_Command = struct {
    pub const help = cli.Command_Help{
        .name = "porteur help",
        .synopsis = &.{
            "porteur help [⟨command⟩ [⟨subcommand⟩]]",
        },
        .short_description = "Display help information.",
        .long_description =
        \\Without ⟨command⟩ and ⟨subcommand⟩ given, the synopsis of the porteur command
        \\will be printed. This is equivalent to using `porteur` without any arguments.
        \\
        \\When ⟨command⟩ is specified without ⟨subcommand⟩, a detailed description of this
        \\command is printed. An additional ⟨subcommand⟩ prints the detailed description of
        \\the subcommand.
        \\
        \\The `porteur help ...` and `porteur ... --help` commands are identical.
        \\
        \\This help text can be displayed with `porteur help help` or `porteur help --help`.
        ,
    };

    pub const Subcommands = Help_Subcommands(Main_Command.Subcommands);

    fn execute(self: Help_Command, env: Env) void {
        _ = self;
        const subcmd = env.args.next_subcommand(Help_Command) orelse {
            cli.print_usage(cli.stdout, Main_Command);
            return;
        };

        switch (subcmd) {
            inline else => |cmd| execute_subcmd(env.args, @TypeOf(cmd)),
        }
    }

    fn execute_subcmd(args: *cli.Args, comptime Command: type) void {
        if (@hasDecl(Command, "Subcommands")) {
            if (args.next_subcommand(Command)) |subcmd| {
                switch (subcmd) {
                    inline else => |cmd| {
                        execute_subcmd(args, @TypeOf(cmd));
                        return;
                    },
                }
            }
        }
        cli.print_help(Command);
    }

    fn Help_Subcommands(comptime Subcmds: type) type {
        assert(@typeInfo(Subcmds) == .@"union");
        const union_info = @typeInfo(Subcmds).@"union";

        var fields: [union_info.fields.len]std.builtin.Type.UnionField = undefined;
        for (union_info.fields, 0..) |field, i| {
            fields[i] = .{
                .name = field.name,
                .alignment = field.alignment,
                .type = struct {
                    pub const help = field.type.help;
                },
            };
        }
        return @Type(.{ .@"union" = .{
            .layout = union_info.layout,
            .tag_type = union_info.tag_type,
            .fields = &fields,
            .decls = &.{},
        } });
    }
};

const Tmpl_Command = struct {
    pub const help = cli.Command_Help{
        .name = "porteur tmpl",
        .synopsis = &.{
            "porteur tmpl ⟨command⟩ [options] [⟨args⟩]",
        },
        .short_description = "Provide management of port templates.",
        .long_description =
        \\This command manages port templates. A port template defines the files
        \\a port uses to automate the compilation of its source code. To use a
        \\template with multiple ports variables can be used which are defined
        \\for each port and later replaced when the port will be updated.
        \\
        \\A variable definition within a template file has the form `{{key}}`,
        \\where the value of `key` can be defined for each port using this
        \\template. If no such value is defined for a port, it will simply be
        \\replaced by an empty string.
        \\
        \\For more information about defining and using templates, see the
        \\TEMPLATES section in `porteur --help`.
        ,
    };

    pub const Subcommands = union(enum) {
        list: Tmpl_Ls,
        conf: Tmpl_Conf,
    };

    pub fn execute(self: Tmpl_Command, env: Env) void {
        _ = self;
        const subcmd = env.args.next_subcommand(Tmpl_Command) orelse {
            cli.fatal_with_usage(Tmpl_Command, "missing subcommand", .{});
        };

        switch (subcmd) {
            .list => |cmd| cmd.execute(env) catch |err| fatal_err(err, "failed to list templates"),
            .conf => |cmd| cmd.execute(env) catch |err| fatal_err(err, "failed to update template configuration"),
        }
    }

    const Tmpl_Ls = struct {
        pub const help = cli.Command_Help{
            .name = "porteur tmpl ls",
            .synopsis = &.{
                "porteur tmpl [options] ls",
            },
            .short_description = "List all port templates.",
            .long_description =
            \\This command lists the names of all port templates that are known by
            \\porteur.
            ,
        };
        options: struct {
            long: cli.Option(bool, .{
                .name = "long",
                .short_name = 'l',
                .short_description = "List templates in the long format.",
                .long_description =
                \\List the templates in a longer format that includes more information
                \\about each template. In the long format a template is listed with its
                \\path.
                ,
                .default_value = false,
            }),
        },

        fn execute(self: Tmpl_Ls, env: Env) !void {
            const long = self.options.long.value_or_default();
            const print_opts: cli.Print_Options = .{ .hanging_indent = 4 };
            var iter = try tmpl.iterate(env);
            defer iter.deinit();
            if (long) {
                while (try iter.next()) |template| {
                    cli.stdout.printf_line("{s} {s}", .{ template.name, template.path.name() }, print_opts);
                }
            } else {
                while (try iter.next()) |template| {
                    cli.stdout.print_line(template.name, print_opts);
                }
            }
            cli.stdout.flush();
        }
    };

    const Tmpl_Conf = struct {
        pub const help = cli.Command_Help{
            .name = "porteur tmpl conf",
            .synopsis = &.{
                "porteur tmpl [options] conf ⟨template⟩",
                "porteur tmpl [options] conf (--edit | -e) ⟨template⟩",
                "porteur tmpl [options] conf --import=⟨path⟩ ⟨template⟩",
            },
            .short_description = "Manage the configuration for a template.",
            .long_description =
            \\Manage the configuration for a template. Without a flag specified it lists
            \\the current configuration values for this template. To edit the configuration
            \\either use the --edit or the --import option. With the --edit option set,
            \\the existing configuration can be modified interactively using an editor.
            \\The --import flag imports an external configuration from a file and overwrites
            \\the existing one. The configuration file consists of a list of variables (see
            \\the VARIABLES section in `porteur --help`). A documentation of possible
            \\configuration values can be found in `⟨etc⟩/porteur/template.conf.sample`.
            ,
        };
        options: struct {
            edit: cli.Option(bool, .{
                .name = "edit",
                .short_name = 'e',
                .short_description = "Edit the template configuration interactively.",
                .long_description =
                \\Edit the existing configuration for the template interactively. An
                \\editor will be invoked where the existing configuration can be updated.
                \\After exiting the editor the updates need to be confirmed. This
                \\flag is mutual exclusive with --import.
                ,
            }),
            import: cli.Option([]const u8, .{
                .name = "import",
                .argument_name = "path",
                .short_description = "Import new configuration from the given file.",
                .long_description =
                \\Import the new configuration for the template from the specified file.
                \\This file must contain valid variable definitions and will overwrite
                \\the existing configuration for the template. This flag is mutual
                \\exclusive with --edit.
                ,
            }),
        },

        fn execute(self: Tmpl_Conf, env: Env) !void {
            const template_name = env.args.next_positional() orelse {
                cli.fatal_with_usage(@This(), "missing template name", .{});
            };

            const edit = self.options.edit.value;
            const import = self.options.import.value;
            if (edit != null and import != null) {
                cli.fatal("can either edit or import configuration", .{});
            }

            if (edit) |_| {
                try tmpl.edit_config(env, template_name);
            } else if (import) |filename| {
                try tmpl.import_config(env, template_name, .init(filename));
            } else {
                const template = try tmpl.must_get(env, template_name);
                const config = try tmpl.read_config(env, template);
                defer config.deinit();
                var iter = config.raw.iterate();
                while (iter.next()) |c| {
                    cli.stdout.write_line("{f}", .{c});
                }
                cli.stdout.flush();
            }
        }
    };
};

const Tree_Command = struct {
    pub const help = cli.Command_Help{
        .name = "porteur tree",
        .synopsis = &.{
            "porteur tree ⟨command⟩ [options] [⟨args⟩]",
        },
        .short_description = "Provide management of ports trees.",
        .long_description =
        \\This command manages ports trees. A ports tree is a collection of your own
        \\ports which can be used with the FreeBSD ports system. A port is a collection
        \\of files that automate the compilation of an application from its source code.
        ,
    };

    pub const Subcommands = union(enum) {
        list: Tree_Ls,
        rm: Tree_Rm,
    };

    pub fn execute(self: Tree_Command, env: Env) void {
        _ = self;
        const subcmd = env.args.next_subcommand(Tree_Command) orelse {
            cli.fatal_with_usage(Tree_Command, "missing subcommand", .{});
        };

        switch (subcmd) {
            .list => |cmd| cmd.execute(env) catch |err| fatal_err(err, "failed to iterate ports trees"),
            .rm => |cmd| cmd.execute(env) catch |err| fatal_err(err, "failed to remove ports trees"),
        }
    }

    const Tree_Ls = struct {
        pub const help = cli.Command_Help{
            .name = "porteur tree ls",
            .synopsis = &.{
                "porteur tree ls",
            },
            .short_description = "List all existing ports trees.",
            .long_description =
            \\This command lists the names of all ports trees that are initialized with
            \\porteur. The name is used to specify a specific tree when dealing with
            \\ports.
            \\
            \\It simply prints all tree names line by line. For more information about
            \\a specific tree use the `porteur tree info` command.
            ,
        };

        fn execute(self: Tree_Ls, env: Env) !void {
            _ = self;
            var iter = try tree.iterate(env);
            defer iter.deinit();
            while (try iter.next()) |t| {
                cli.stdout.print_line(t.name, .{});
            }
            cli.stdout.flush();
        }
    };

    const Tree_Rm = struct {
        pub const help = cli.Command_Help{
            .name = "porteur tree rm",
            .synopsis = &.{
                "porteur tree rm ⟨tree⟩",
            },
            .short_description = "Remove an existing ports tree.",
            .long_description =
            \\This command removes an existing ports tree and deletes all its ports.
            \\It asks for confirmation before deleting a tree.
            ,
        };
        options: struct {
            force: cli.Option(bool, .{
                .name = "force",
                .short_name = 'f',
                .short_description = "Do not prompt for confirmation.",
                .long_description =
                \\Attempt to remove a ports tree without prompting for confirmation.
                \\If the tree does not exist, do not report an error.
                ,
                .default_value = false,
            }),
        },

        fn execute(self: Tree_Rm, env: Env) !void {
            const force = self.options.force.value_or_default();
            const name = env.args.next_positional() orelse {
                if (force) std.process.exit(0);
                cli.fatal_with_usage(@This(), "missing tree name", .{});
            };

            const ports_tree = try tree.get(env, name) orelse {
                if (force) return;
                cli.fatal("tree not found", .{});
            };

            if (!force) {
                const confirmed = cli.ask_confirmation("Remove tree {s}?", .{ports_tree.name}, .no);
                if (!confirmed) return;
            }

            try port.remove_all(.{
                .env = env,
                .tree = ports_tree,
            });
            tree.remove(env, ports_tree) catch {};
        }
    };
};

const Port_Command = struct {
    pub const help = cli.Command_Help{
        .name = "porteur port",
        .synopsis = &.{
            "porteur port [--tree=⟨tree⟩ | -t ⟨tree⟩] ⟨command⟩ [options] [⟨args⟩]",
        },
        .short_description = "Provide management of ports in a ports tree.",
        .long_description =
        \\This command manages the ports of a ports tree. A port is a collection of
        \\files that automate the compilation of an application from its source code.
        \\It references a Git repository that contains the source code and a template 
        \\which is used to generate the port files from.
        ,
    };

    options: struct {
        tree: cli.Option([]const u8, .{
            .name = "tree",
            .short_name = 't',
            .argument_name = "tree",
            .short_description = "The name of the ports tree.",
            .long_description = std.fmt.comptimePrint(
                \\The name of the ports tree. If this option is not specified the default
                \\tree `{[default_tree]s}` will be used.
            , .{ .default_tree = default_tree_name }),
            .default_value = default_tree_name,
        }),
    },

    pub const Subcommands = union(enum) {
        list: Port_Ls,
        info: Port_Info,
        add: Port_Add,
        vars: Port_Vars,
        update: Port_Update,
        bump_version: Port_Bump_Version,
        history: Port_History,
        rollback: Port_Rollback,
        rm: Port_Rm,
    };

    pub fn execute(self: Port_Command, env: Env) void {
        const subcmd = env.args.next_subcommand(Port_Command) orelse {
            cli.fatal_with_usage(Port_Command, "missing subcommand", .{});
        };

        const tree_name = self.options.tree.value_or_default();
        const ports_tree = tree.get(env, tree_name) catch |err| fatal_err(err, "failed to get tree");
        if (ports_tree == null) cli.fatal("ports tree not found: {s}", .{tree_name});

        const ctx = port.Ctx{
            .env = env,
            .tree = ports_tree.?,
        };

        switch (subcmd) {
            .list => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to list ports"),
            .info => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to fetch port"),
            .add => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to write port"),
            .vars => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to update port variables"),
            .update => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to update port"),
            .bump_version => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to bump the port version"),
            .history => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to list distfile history"),
            .rollback => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to roll back the port version"),
            .rm => |cmd| cmd.execute(ctx) catch |err| fatal_err(err, "failed to delete port"),
        }
    }

    const Port_Ls = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port ls",
            .synopsis = &.{
                "porteur port [options] ls",
            },
            .short_description = "List all ports of a ports tree.",
            .long_description =
            \\This command lists all ports the ports tree contains. It simply prints
            \\all port names along with the port versions line by line. For more
            \\information about a specific port see the `porteur port info` command.
            ,
        };
        options: struct {
            long: cli.Option(bool, .{
                .name = "long",
                .short_name = 'l',
                .short_description = "List ports in the long format.",
                .long_description =
                \\List the ports in a longer format that includes more information about
                \\each port. In the long format a port is listed with its current version
                \\and its category.
                ,
                .default_value = false,
            }),
        },

        fn execute(self: Port_Ls, ctx: port.Ctx) !void {
            const long = self.options.long.value_or_default();
            const print_opts: cli.Print_Options = .{ .hanging_indent = 4 };
            var iter = try port.iterate(ctx);
            defer iter.deinit();
            if (long) {
                while (try iter.next()) |p| {
                    const version = try port.read_version(ctx, p);
                    cli.stdout.printf_line("{s}@{f} {s}", .{ p.name, version, p.category }, print_opts);
                }
            } else {
                while (try iter.next()) |p| {
                    cli.stdout.print_line(p.name, print_opts);
                }
            }
            cli.stdout.flush();
        }
    };

    const Port_Info = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port info",
            .synopsis = &.{
                "porteur port [options] info ⟨port⟩",
            },
            .short_description = "Show information about a port.",
            .long_description =
            \\This command prints information about the specified port of a ports
            \\tree. Variables for this port are not listed here. To show them use
            \\the `porteur port vars` command. If the port cannot be found in the
            \\ports tree an error will be reported.
            ,
        };
        fn execute(self: Port_Info, ctx: port.Ctx) !void {
            _ = self;
            const port_name = ctx.env.args.next_positional() orelse {
                cli.fatal_with_usage(@This(), "missing port name", .{});
            };
            const p = try port.must_get(ctx, port_name);
            defer p.deinit();
            const version = try port.read_version(ctx, p);
            const source = try port.read_source(ctx, p);
            defer source.deinit();
            const distdir = ctx.env.ports_dist_dir(ctx.tree.name, p.name);
            cli.stdout.printf_line("Name:        {s}", .{p.name}, .{});
            cli.stdout.printf_line("Category:    {s}", .{p.category}, .{});
            cli.stdout.printf_line("Template:    {s}", .{p.template}, .{});
            cli.stdout.printf_line("Version:     {f}", .{version}, .{});
            cli.stdout.printf_line("Git Repo:    {s}", .{source.repo.url}, .{});
            cli.stdout.printf_line("Git Branch:  {s}", .{source.repo.branch}, .{});
            if (source.commit.hash.len > 0) {
                cli.stdout.printf_line("Commit Hash: {s}", .{source.commit.hash}, .{});
                cli.stdout.printf_line("Commit Time: {f}", .{Time.from_timestamp(source.commit.timestamp)}, .{});
            } else {
                cli.stdout.printf_line("Commit Hash: -", .{}, .{});
                cli.stdout.printf_line("Commit Time: -", .{}, .{});
            }
            cli.stdout.printf_line("Distdir:     {s}", .{distdir.name()}, .{});
            cli.stdout.flush();
        }
    };

    const Port_Add = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port add",
            .synopsis = &.{
                "porteur port [options] add",
            },
            .short_description = "Add a new port to the ports tree.",
            .long_description =
            \\This command adds a new port to the ports tree. A port needs to reference a
            \\Git repository that holds the source code for distribution and compilation.
            \\Porteur creates a local clone of this repository.
            \\
            \\When adding a new port there will be no variables defined and no FreeBSD
            \\ports tree files generated. To add variables for the new port, use the
            \\`porteur port vars` command. If everything is set up correctly, execute
            \\a `porteur port update` to initially render the port.
            \\
            \\This command is interactive.
            ,
        };

        fn execute(self: Port_Add, ctx: port.Ctx) !void {
            _ = self;
            if (!try tmpl.exists_any(ctx.env)) {
                const tmpl_dir = tmpl.etc_dir(ctx.env);
                cli.stderr.print_line("No templates found.", .{});
                cli.fatal("Please define a template in `{s}`.", .{tmpl_dir.name()});
            }

            const namebuf = try ctx.env.allocator.alloc(u8, 64);
            defer ctx.env.allocator.free(namebuf);
            const name = while (true) {
                const input = cli.ask("Name: ", .{}, namebuf) orelse {
                    cli.stderr.print_line("ERROR: The port name is required.", .{});
                    cli.stderr.flush();
                    continue;
                };
                if (std.mem.indexOfAny(u8, input, "/\\\t ")) |_| {
                    cli.stderr.print_line("ERROR: The port name must not contain slash, backslash, or space.", .{});
                    cli.stderr.flush();
                    continue;
                }
                break input;
            };

            var catbuf: [128]u8 = undefined;
            var default_cat_buf: [128]u8 = undefined;
            const default_cat = if (ctx.env.default_category) |cat|
                try std.fmt.bufPrint(&default_cat_buf, " [{s}]", .{cat})
            else
                "";
            const category = while (true) {
                const input = cli.ask("Category{s}: ", .{default_cat}, &catbuf) orelse default_cat: {
                    if (ctx.env.default_category) |c| break :default_cat c;
                    cli.stderr.print_line("ERROR: The port category is required.", .{});
                    cli.stderr.flush();
                    continue;
                };
                if (std.mem.indexOfAny(u8, input, "/\\\t ")) |_| {
                    cli.stderr.print_line("ERROR: The port category must not contain slash, backslash, or space.", .{});
                    cli.stderr.flush();
                    continue;
                }
                break input;
            };

            var verbuf: [64]u8 = undefined;
            const version = while (true) {
                const input = cli.ask("Initial Version [0.1.0]: ", .{}, &verbuf) orelse "0.1.0";
                const ver = port.Version.parse_semver(input) catch {
                    cli.stderr.print_line("ERROR: The port version must be in the format `⟨major⟩[[.⟨minor⟩[.⟨patch⟩]`.", .{});
                    cli.stderr.flush();
                    continue;
                };
                break ver;
            };

            var repourlbuf: [std.fs.max_path_bytes]u8 = undefined;
            const repo_url = while (true) {
                const input = cli.ask("Git Repository: ", .{}, &repourlbuf) orelse {
                    cli.stderr.print_line("ERROR: The Git repository is required.", .{});
                    cli.stderr.flush();
                    continue;
                };
                break input;
            };

            var repobranchbuf: [64]u8 = undefined;
            const repo_branch = while (true) {
                const default_branch = ctx.env.default_repo_branch;
                const input = cli.ask("Git Branch [{s}]: ", .{default_branch}, &repobranchbuf) orelse default_branch;
                if (!git.is_valid_branch_name(input)) {
                    cli.stderr.print_line("ERROR: Invalid Git branch name.", .{});
                    cli.stderr.flush();
                    continue;
                }
                break input;
            };

            var templatebuf: [64]u8 = undefined;
            const template = while (true) {
                const input = cli.ask("Template: ", .{}, &templatebuf) orelse {
                    cli.stderr.print_line("ERROR: The template is required.", .{});
                    cli.stderr.flush();
                    continue;
                };
                if (!try tmpl.exists(ctx.env, input)) {
                    cli.stderr.print_line("ERROR: Template does not exist.", .{});
                    cli.stderr.flush();
                    continue;
                }
                break input;
            };

            cli.stderr.print_line("", .{});
            cli.stderr.printf_line("Name:             {s}", .{name}, .{});
            cli.stderr.printf_line("Category:         {s}", .{category}, .{});
            cli.stderr.printf_line("Initial Version:  {f}", .{version}, .{});
            cli.stderr.printf_line("Git Repository:   {s}", .{repo_url}, .{});
            cli.stderr.printf_line("Git Branch:       {s}", .{repo_branch}, .{});
            cli.stderr.printf_line("Template:         {s}", .{template}, .{});
            cli.stderr.flush();

            const ok = cli.ask_confirmation("OK?", .{}, .yes);
            if (ok) {
                const new_port: port.Info = .init(ctx.tree, name, category, template);
                try port.create(ctx, new_port, .{
                    .repo_url = repo_url,
                    .repo_branch = repo_branch,
                    .initial_version = version,
                });

                cli.stderr.print_line("", .{});
                cli.stderr.printf_line("port created: {s}", .{new_port.name}, .{});
                cli.stderr.print_line("", .{});
                cli.stderr.print_line("Next steps:", .{});
                cli.stderr.print_line("(1) use `porteur port vars` to define variables", .{ .margin = 2 });
                cli.stderr.print_line("(2) use `porteur port update` to initially render the port", .{ .margin = 2 });
                cli.stderr.flush();
            }
        }
    };

    const Port_Vars = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port vars",
            .synopsis = &.{
                "porteur port [options] vars ⟨port⟩",
                "porteur port [options] vars (--edit | -e) ⟨port⟩",
                "porteur port [options] vars --import=⟨path⟩ ⟨port⟩",
            },
            .short_description = "Manage variables for a port.",
            .long_description =
            \\Manage the variables for a port. Without a flag specified it lists all
            \\existing variables for this port. To edit the variables either use the
            \\--edit or the --import option. With the --edit option set, all existing
            \\variables can be modified interactively using an editor. The --import
            \\flag imports the variables from a file and overwrites all existing ones.
            \\For more information on how to format the variables see the VARIABLES
            \\section in `porteur --help`.
            ,
        };
        options: struct {
            edit: cli.Option(bool, .{
                .name = "edit",
                .short_name = 'e',
                .short_description = "Edit the port variables interactively.",
                .long_description =
                \\Edit the existing variables for the port interactively. An editor
                \\will be invoked where the existing variables can be updated. After
                \\exiting the editor the updates need to be confirmed. This flag is
                \\mutual exclusive with --import.
                ,
            }),
            import: cli.Option([]const u8, .{
                .name = "import",
                .argument_name = "path",
                .short_description = "Import new port variables from the given file.",
                .long_description =
                \\Import the new variables for the port from the specified file. This
                \\file must contain valid variable definitions. It will overwrite all
                \\existing port variables. This flag is mutual exclusive with --edit.
                ,
            }),
        },

        fn execute(self: Port_Vars, ctx: port.Ctx) !void {
            const port_name = ctx.env.args.next_positional() orelse {
                cli.fatal_with_usage(@This(), "missing port name", .{});
            };

            const edit = self.options.edit.value;
            const import = self.options.import.value;
            if (edit != null and import != null) {
                cli.fatal("can either edit or import variables", .{});
            }

            if (edit) |_| {
                try port.edit_vars(ctx, port_name);
            } else if (import) |filename| {
                try port.import_vars(ctx, port_name, .init(filename));
            } else {
                const p = try port.must_get(ctx, port_name);
                defer p.deinit();
                const vars = try port.read_vars(ctx, p);
                defer vars.deinit();
                var iter = vars.iterate();
                while (iter.next()) |v| {
                    cli.stdout.write_line("{f}", .{v});
                }
                cli.stdout.flush();
            }
        }
    };

    const Port_Update = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port update",
            .synopsis = &.{
                "porteur port [options] update [⟨port⟩ ...]",
            },
            .short_description = "Update ports in a ports tree.",
            .long_description =
            \\This command updates one or more ports in the ports tree. For each port, it
            \\checks if there is a new commit for the configured Git branch. If so, the
            \\files in the ports tree will be generated from the template and the new
            \\distribution files will be created. A Git commit is considered new if it has
            \\a newer date than the last commit from which the port files were generated
            \\or if the date is the same, but the commit hash is different.
            \\
            \\If no port name is provided it updates all existing ports in the ports tree.
            ,
        };
        options: struct {
            force: cli.Option(bool, .{
                .name = "force",
                .short_name = 'f',
                .short_description = "Force the port update.",
                .long_description =
                \\Attempt to do the port update although the current commit for the branch
                \\is not newer than the last one. This option forces a rerender for the
                \\port based on the branch's latest commit.
                ,
                .default_value = false,
            }),
        },

        fn execute(self: Port_Update, ctx: port.Ctx) !void {
            const opts: port.Update_Options = .{
                .force = self.options.force.value_or_default(),
            };
            var count: usize = 0;
            while (ctx.env.args.next_positional()) |port_name| {
                count += 1;
                try update_single_port(ctx, port_name, opts);
            }
            if (count == 0) {
                var iter = try port.iterate(ctx);
                defer iter.deinit();
                while (try iter.next()) |p| {
                    try update_single_port(ctx, p.name, opts);
                }
            }
        }

        fn update_single_port(ctx: port.Ctx, port_name: []const u8, opts: port.Update_Options) !void {
            if (try port.update_version(ctx, port_name, opts)) |new_version| {
                cli.stderr.printf_line("updated {s} to {f}", .{ port_name, new_version }, .{});
            } else {
                cli.stderr.printf_line("already up to date: {s}", .{port_name}, .{});
            }
            cli.stderr.flush();
        }
    };

    const Port_Bump_Version = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port bump-version",
            .synopsis = &.{
                "porteur port [options] bump-version [--major | --minor | --patch] ⟨port⟩",
            },
            .short_description = "Increment the version of a port.",
            .long_description =
            \\This command increments the version of a port without updating its sources.
            \\It is possible to increment the major version, the minor version, or the
            \\patch version. By default, the patch version will be incremented.
            ,
        };
        options: struct {
            major: cli.Option(bool, .{
                .name = "major",
                .short_description = "Increment the major version.",
                .long_description =
                \\Increment the major version of the port by one and reset the minor and patch
                \\version to zero. This flag in mutual exclusive with --minor and --patch.
                ,
                .default_value = false,
            }),
            minor: cli.Option(bool, .{
                .name = "minor",
                .short_description = "Increment the minor version.",
                .long_description =
                \\Increment the minor version of the port by one and reset the patch version
                \\to zero. The major version stays untouched. This flag in mutual exclusive
                \\with --major and --patch.
                ,
                .default_value = false,
            }),
            patch: cli.Option(bool, .{
                .name = "patch",
                .short_description = "Increment the patch version.",
                .long_description =
                \\Increment the patch version of the port by one. The major and minior version
                \\stays untouched. This flag in mutual exclusive with --major and --minor.
                ,
                .default_value = false,
            }),
        },

        fn execute(self: Port_Bump_Version, ctx: port.Ctx) !void {
            const bump_major: u8 = @intFromBool(self.options.major.value_or_default());
            const bump_minor: u8 = @intFromBool(self.options.minor.value_or_default());
            const bump_patch: u8 = @intFromBool(self.options.patch.value_or_default());
            switch (bump_major + bump_minor + bump_patch) {
                0, 1 => {},
                else => cli.fatal("can either bump major, minor, or patch version", .{}),
            }

            const port_name = ctx.env.args.next_positional() orelse {
                cli.fatal_with_usage(@This(), "missing port name", .{});
            };

            const new_version = try port.bump_version(ctx, port_name, .{
                .which = if (bump_major != 0) .major else if (bump_minor != 0) .minor else .patch,
            });

            cli.stderr.printf_line("port version bumped to {f}", .{new_version}, .{});
            cli.stderr.flush();
        }
    };

    const Port_History = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port history",
            .synopsis = &.{
                "porteur port [options] history ⟨port⟩",
            },
            .short_description = "List all existing distfile version of a port.",
            .long_description =
            \\This command lists all existing distfile versions for the given port.
            \\The number of distfiles kept can be configured in `porteur.conf`.
            ,
        };
        options: struct {
            long: cli.Option(bool, .{
                .name = "long",
                .short_name = 'l',
                .short_description = "List distfile version in the long format.",
                .long_description =
                \\List the distfile version in a longer format that also includes the
                \\distfile locations.
                ,
                .default_value = false,
            }),
        },

        fn execute(self: Port_History, ctx: port.Ctx) !void {
            const long = self.options.long.value_or_default();
            const port_name = ctx.env.args.next_positional() orelse {
                cli.fatal_with_usage(@This(), "missing port name", .{});
            };
            var distfiles = try port.list_distfiles(ctx, port_name);
            defer distfiles.deinit(ctx.env.allocator);

            if (long) {
                const version_strings = try ctx.env.allocator.alloc(port.Version_String, distfiles.items.len);
                defer ctx.env.allocator.free(version_strings);
                var max_version_len: usize = 0;
                for (distfiles.items, 0..) |distfile, i| {
                    version_strings[i] = distfile.version.to_string();
                    max_version_len = @max(max_version_len, version_strings[i].len);
                }

                const spaces = [_]u8{' '} ** 64;
                for (distfiles.items, version_strings) |distfile, version| {
                    const fill = spaces[0 .. max_version_len - version.len];
                    cli.stdout.write_line("{s}{s}  {s}", .{ version.slice(), fill, distfile.path.name() });
                }
            } else {
                for (distfiles.items) |d| {
                    cli.stdout.write_line("{f}", .{d.version});
                }
            }
            cli.stdout.flush();
        }
    };

    const Port_Rollback = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port rollback",
            .synopsis = &.{
                "porteur port [options] rollback ⟨port⟩ ⟨version⟩",
            },
            .short_description = "Roll back a port to a specific version.",
            .long_description =
            \\This command rolls back an existing ports to the given version.
            \\The distfile of this version must still be in the port's history.
            \\It asks for confirmation before rolling back a port.
            ,
        };

        fn execute(self: Port_Rollback, ctx: port.Ctx) !void {
            _ = self;
            const port_name = ctx.env.args.next_positional() orelse {
                cli.fatal_with_usage(@This(), "missing port name", .{});
            };
            const version_str = ctx.env.args.next_positional() orelse {
                cli.fatal_with_usage(@This(), "missing version", .{});
            };
            const version = port.Version.parse(version_str) catch {
                cli.fatal("incorrect version: {s}", .{version_str});
            };

            try port.rollback(ctx, port_name, version);
        }
    };

    const Port_Rm = struct {
        pub const help = cli.Command_Help{
            .name = "porteur port rm",
            .synopsis = &.{
                "porteur port [options] rm ⟨port⟩ [⟨port⟩ ...]",
            },
            .short_description = "Remove ports from a ports tree.",
            .long_description =
            \\This command removes one or more existing ports from the ports tree.
            \\It asks for confirmation before deleting a port.
            ,
        };
        options: struct {
            force: cli.Option(bool, .{
                .name = "force",
                .short_name = 'f',
                .short_description = "Do not prompt for confirmation.",
                .long_description =
                \\Attempt to remove ports without prompting for confirmation. If the port
                \\does not exist, do not report an error.
                ,
                .default_value = false,
            }),
        },

        fn execute(self: Port_Rm, ctx: port.Ctx) !void {
            const force = self.options.force.value_or_default();

            var count: usize = 0;
            var exit_code: u8 = 0;
            while (ctx.env.args.next_positional()) |port_name| {
                count += 1;
                if (!force) {
                    const confirmed = cli.ask_confirmation("Remove port {s}?", .{port_name}, .no);
                    if (!confirmed) continue;
                }
                const deleted = try port.remove(ctx, port_name);
                if (!deleted and !force) {
                    cli.stderr.printf_line("port not found: {s}", .{port_name}, .{});
                    cli.stderr.flush();
                    exit_code = 1;
                }
            }
            if (count == 0 and !force) {
                cli.fatal_with_usage(Port_Rm, "missing port name", .{});
            } else if (exit_code != 0) {
                std.process.exit(exit_code);
            }
        }
    };
};

fn fatal_err(err: anyerror, comptime errmsg: []const u8) noreturn {
    cli.fatal(errmsg ++ ": {s}", .{@errorName(err)});
}

test {
    std.testing.refAllDecls(@This());
}