id       = "gmailctl"
name     = "gmailctl"
homepage = "https://github.com/mbrt/gmailctl"
description = "This utility helps you generate and maintain Gmail filters in a declarative way."
executables   = ["gmailctl"]

[dotfiles]

# cmd/gmailctl/cmd/root_cmd.go, the --config flag: "config directory (defaults
# to $HOME/.gmailctl if it exists, else $HOME/.config/gmailctl)", and
# initConfig() implements exactly that — the legacy ~/.gmailctl when it is
# present, otherwise path.Join(xdg.ConfigHome, "gmailctl").
#
# That xdg is github.com/adrg/xdg, whose config home is not one root this
# catalog names: paths_darwin.go points it at ~/Library/Application Support and
# paths_windows.go at %LOCALAPPDATA% (not %APPDATA%), while Linux keeps
# ~/.config. So the three spellings are written out, the way apps/act.toml does
# for the same library.
#
# The file inside is config.yaml if present, else config.jsonnet —
# configFilenameFromDir() in cmd/gmailctl/cmd/config.go.
paths = [
  "~/.gmailctl/config.jsonnet",
  "~/.gmailctl/config.yaml",
  "~/.config/gmailctl/config.jsonnet",
  "~/.config/gmailctl/config.yaml",
  "~/Library/Application Support/gmailctl/config.jsonnet",
  "~/Library/Application Support/gmailctl/config.yaml",
  "%LOCALAPPDATA%/gmailctl/config.jsonnet",
  "%LOCALAPPDATA%/gmailctl/config.yaml",
]

exclude = []

# localcred/local_provider.go names both files: credentialsPath() is
# credentials.json and tokenPath() is token.json, the latter written with mode
# 0600. credentials.json is the Google Cloud OAuth client secret, handed
# straight to google.ConfigFromJSON in internal/engine/api/auth.go; token.json
# is a marshalled oauth2.Token with the access and refresh tokens in it. Both
# are credentials end to end, in whichever of the four config directories the
# machine resolved.
secret = [
  "~/.gmailctl/credentials.json",
  "~/.gmailctl/token.json",
  "~/.config/gmailctl/credentials.json",
  "~/.config/gmailctl/token.json",
  "~/Library/Application Support/gmailctl/credentials.json",
  "~/Library/Application Support/gmailctl/token.json",
  "%LOCALAPPDATA%/gmailctl/credentials.json",
  "%LOCALAPPDATA%/gmailctl/token.json",
]

# A CLI: the config is read from disk on each invocation.
side_effect = false

# No machine_lines: the config is the filter rules themselves — the addresses,
# labels and boolean expressions the user wants applied to their one Gmail
# account, which is the same account from any machine.

[commands]
format = 1
label = "Manage Gmail filters"
description = "Compare, edit or apply a gmailctl configuration. Init, download, export and test are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "readme"
kind = "manual"
url = "https://github.com/mbrt/gmailctl"
evidence = """
- Custom location: use the `--config` argument.
"""

[[commands.field]]
id = "config"
label = "Config directory"
description = "Directory holding gmailctl config; defaults to the per-user location."
type = "path"
option = ["--config"]
path = { kind = "directory", role = "input", must_exist = true }
sources = ["readme"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["config"]

[[commands.subcommand]]
path = ["diff"]
label = "Show diff"
description = "Compare the local configuration with the Gmail settings."

[[commands.subcommand.source]]
id = "src"
kind = "help"
url = "https://github.com/mbrt/gmailctl/blob/master/cmd/gmailctl/cmd/diff_cmd.go"
evidence = """
diffCmd.PersistentFlags().StringVarP(&diffFilename, "filename", "f", "", "configuration file")
diffCmd.PersistentFlags().BoolVar(&diffDebug, "debug", false, "print extra debugging information")
diffCmd.PersistentFlags().IntVar(&diffContext, "context", papply.DefaultContextLines, "number of lines of filter diff context to show")
flags: --filename -f --debug -f --context -p
"""

[[commands.subcommand.field]]
id = "filename"
label = "Config file"
type = "path"
option = ["--filename", "-f"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["src"]

[[commands.subcommand.field]]
id = "debug"
label = "Debug output"
type = "boolean"
option = ["--debug"]
sources = ["src"]

[[commands.subcommand.field]]
id = "context"
label = "Diff context lines"
type = "integer"
option = ["--context"]
sources = ["src"]

[[commands.subcommand.task]]
id = "diff"
label = "Show diff"
fields = ["filename", "debug", "context"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["filename", "debug", "context"]

[[commands.subcommand]]
path = ["apply"]
label = "Apply configuration"
description = "Apply a configuration file to Gmail settings."

[[commands.subcommand.source]]
id = "src"
kind = "help"
url = "https://github.com/mbrt/gmailctl/blob/master/cmd/gmailctl/cmd/apply_cmd.go"
evidence = """
applyCmd.PersistentFlags().StringVarP(&applyFilename, "filename", "f", "", "configuration file")
applyCmd.Flags().BoolVarP(&applyYes, "yes", "y", false, "don't ask for confirmation, just apply")
applyCmd.Flags().BoolVarP(&applyRemoveLabels, "remove-labels", "r", false, "allow removing labels")
applyCmd.Flags().BoolVar(&applySkipTests, "yolo", false, "skip configuration tests")
applyCmd.PersistentFlags().BoolVar(&applyDebug, "debug", false, "print extra debugging information")
flags: --filename -f --yes -y --remove-labels -r --yolo -f --debug -f
"""

[[commands.subcommand.field]]
id = "filename"
label = "Config file"
type = "path"
option = ["--filename", "-f"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["src"]

[[commands.subcommand.field]]
id = "yes"
label = "Skip confirmation"
type = "boolean"
option = ["--yes", "-y"]
effect = "exec"
sources = ["src"]

[[commands.subcommand.field]]
id = "remove_labels"
label = "Allow removing labels"
type = "boolean"
option = ["--remove-labels", "-r"]
effect = "delete"
sources = ["src"]

[[commands.subcommand.field]]
id = "yolo"
label = "Skip config tests"
type = "boolean"
option = ["--yolo"]
sources = ["src"]

[[commands.subcommand.field]]
id = "debug"
label = "Debug output"
type = "boolean"
option = ["--debug"]
sources = ["src"]

[[commands.subcommand.task]]
id = "apply"
label = "Apply configuration"
fields = ["filename", "yes", "remove_labels", "yolo", "debug"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["filename", "yes", "remove_labels", "yolo", "debug"]

[[commands.subcommand]]
path = ["edit"]
label = "Edit and apply"
description = "Edit the configuration and apply it to Gmail."

[[commands.subcommand.source]]
id = "src"
kind = "help"
url = "https://github.com/mbrt/gmailctl/blob/master/cmd/gmailctl/cmd/edit_cmd.go"
evidence = """
editCmd.PersistentFlags().StringVarP(&editFilename, "filename", "f", "", "configuration file")
editCmd.Flags().BoolVarP(&editSkipTests, "yolo", "", false, "skip configuration tests")
editCmd.PersistentFlags().BoolVar(&editDebug, "debug", false, "print extra debugging information")
flags: --filename -f --yolo --debug -f
"""

[[commands.subcommand.field]]
id = "filename"
label = "Config file"
type = "path"
option = ["--filename", "-f"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["src"]

[[commands.subcommand.field]]
id = "yolo"
label = "Skip config tests"
type = "boolean"
option = ["--yolo"]
sources = ["src"]

[[commands.subcommand.field]]
id = "debug"
label = "Debug output"
type = "boolean"
option = ["--debug"]
sources = ["src"]

[[commands.subcommand.task]]
id = "edit"
label = "Edit and apply"
fields = ["filename", "yolo", "debug"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["filename", "yolo", "debug"]