config.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Config",
  "description": "Root configuration struct for biwa.",
  "type": "object",
  "properties": {
    "clean": {
      "description": "Cleanup configuration for stale remote directories.",
      "$ref": "#/$defs/CleanConfig",
      "default": {
        "auto": true,
        "max_age": "30days",
        "quota_thresholds": {}
      }
    },
    "env": {
      "description": "Environment variables configuration.",
      "$ref": "#/$defs/EnvConfig",
      "default": {
        "forward_method": "export",
        "vars": []
      }
    },
    "hooks": {
      "description": "Lifecycle hooks for synchronization.",
      "$ref": "#/$defs/HooksConfig",
      "default": {
        "post_sync": null,
        "pre_sync": null
      }
    },
    "ssh": {
      "description": "SSH connection configuration.",
      "$ref": "#/$defs/SshConfig",
      "default": {
        "host": "cse.unsw.edu.au",
        "key_path": null,
        "password": false,
        "port": 22,
        "umask": "077",
        "user": "z1234567"
      }
    },
    "sync": {
      "description": "Remote synchronization configuration.",
      "$ref": "#/$defs/SyncConfig",
      "default": {
        "auto": true,
        "engine": "sftp",
        "exclude": [
          "**/.git/**",
          "**/target/**",
          "**/node_modules/**"
        ],
        "remote_root": "~/.cache/biwa/projects",
        "sftp": {
          "max_files_to_sync": 100,
          "permissions": "recreate"
        },
        "sync_root": null
      }
    }
  },
  "$defs": {
    "CleanConfig": {
      "description": "Cleanup configuration for stale remote directories.",
      "type": "object",
      "properties": {
        "auto": {
          "description": "Enable automatic background cleanup after `run`/`sync`.",
          "type": "boolean",
          "default": true
        },
        "max_age": {
          "description": "Hard age limit: directories older than this are always removed during auto-cleanup.\nInternally stored as the 0% quota threshold.\nAccepts duration strings like \"30d\", \"12h\", \"45m\", \"60s\" or a plain number (= minutes).",
          "$ref": "#/$defs/HumanDuration",
          "default": "30days"
        },
        "quota_thresholds": {
          "description": "Quota-based cleanup thresholds.\n\nKeys are disk quota usage percentages (0-100), values are maximum directory ages.\nWhen quota usage exceeds a threshold percentage, directories older than the\ncorresponding age are removed. The `max_age` value is merged as the 0% threshold.\n\nExample: `{ 80 = \"5d\" }` means clean dirs older than 5 days when quota ≥ 80%.",
          "type": "object",
          "additionalProperties": false,
          "default": {},
          "patternProperties": {
            "^\\d+$": {
              "$ref": "#/$defs/HumanDuration"
            }
          }
        }
      }
    },
    "EnvConfig": {
      "description": "Environment settings.",
      "type": "object",
      "properties": {
        "forward_method": {
          "description": "Forwarding strategy for environment variables.",
          "$ref": "#/$defs/EnvForwardMethod",
          "default": "export"
        },
        "vars": {
          "description": "Environment variables to send to the remote process.\n\nSupports exact names and values such as\n`vars = [\"NODE_ENV\", \"API_KEY=secret\"]`, wildcard rules such as\n`vars = [\"NODE_*\", \"!*PATH\"]`, and `[env.vars]` table forms.",
          "$ref": "#/$defs/EnvVars",
          "default": []
        }
      }
    },
    "EnvForwardMethod": {
      "description": "Strategy used to forward environment variables to the remote process.",
      "oneOf": [
        {
          "description": "Prefix the command with shell `export` statements.",
          "type": "string",
          "const": "export"
        },
        {
          "description": "Send environment variables through SSH `setenv` requests.",
          "type": "string",
          "const": "setenv"
        }
      ]
    },
    "EnvVarConfigValue": {
      "description": "Config value used in table and inline-table env var forms.",
      "anyOf": [
        {
          "description": "`true` means inherit the local value.",
          "type": "boolean"
        },
        {
          "description": "String values are sent literally.",
          "type": "string"
        }
      ]
    },
    "EnvVarItem": {
      "description": "An entry inside the array form of `env.vars`.",
      "anyOf": [
        {
          "description": "String form such as `NODE_ENV` or `NODE_ENV=production`.",
          "type": "string"
        },
        {
          "description": "Inline table form such as `{ API_KEY = \"secret\" }`.",
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/EnvVarConfigValue"
          }
        }
      ]
    },
    "EnvVars": {
      "description": "Config representation for `env.vars`.\n\nRegardless of the config form used, rules are always evaluated in a\ndeterministic order:\n1. Inherit patterns (e.g., `\"NODE_*\" = true`)\n2. Exact specifications (e.g., `\"API_KEY\" = \"secret\"`, `\"NODE_ENV\" = true`)\n3. Exclusions (e.g., `\"!*PATH\" = true`)\n\nThis means explicit values always override pattern-inherited values, and\nexclusions always apply last.",
      "anyOf": [
        {
          "description": "Array form such as `vars = [\"NODE_ENV\", \"API_KEY=secret\"]`.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/EnvVarItem"
          }
        },
        {
          "description": "Table form such as `[env.vars] NODE_ENV = true`.\n\nFlattened into rules before evaluation, just like the array form.",
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/EnvVarConfigValue"
          }
        }
      ]
    },
    "HooksConfig": {
      "description": "Hook settings.",
      "type": "object",
      "properties": {
        "post_sync": {
          "description": "Command to run after synchronization.",
          "type": [
            "string",
            "null"
          ]
        },
        "pre_sync": {
          "description": "Command to run before synchronization.",
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "HumanDuration": {
      "type": "string"
    },
    "PasswordConfig": {
      "description": "Password authentication configuration.\n\n- `false` (default): No password authentication.\n- `true`: Interactively prompt for a password.\n- `\"string\"`: Use the provided password value.",
      "anyOf": [
        {
          "description": "Interactive prompt (`true`) or disabled (`false`).",
          "type": "boolean"
        },
        {
          "description": "A literal password value.",
          "type": "string"
        }
      ]
    },
    "SftpPermissions": {
      "description": "Strategy for enforcing file permissions during SFTP upload.",
      "oneOf": [
        {
          "description": "Delete the file before creating it with the correct permissions.\nThis is the most compatible strategy as it works on all SFTP servers.",
          "type": "string",
          "const": "recreate"
        },
        {
          "description": "Use the SFTP `setstat` operation to set permissions after writing.\nSome servers (e.g. UNSW CSE) reject this operation.",
          "type": "string",
          "const": "setstat"
        }
      ]
    },
    "SshConfig": {
      "description": "SSH connection settings.",
      "type": "object",
      "properties": {
        "host": {
          "description": "Hostname or IP address of the remote host.",
          "type": "string",
          "default": "cse.unsw.edu.au"
        },
        "key_path": {
          "description": "Optional path to the SSH private key.",
          "type": [
            "string",
            "null"
          ]
        },
        "password": {
          "description": "Password authentication: `false` (default), `true` (prompt), or a string value.",
          "$ref": "#/$defs/PasswordConfig",
          "default": false
        },
        "port": {
          "description": "Port to connect to on the remote host.",
          "type": "integer",
          "default": 22,
          "maximum": 65535,
          "minimum": 0
        },
        "umask": {
          "description": "Umask to apply before executing commands and creating directories (3-digit octal: owner/group/other).\nTo set the first digit (setuid/setgid/sticky), run `umask` manually on the remote server.\nNote that you cannot loosen the default umask set by the server (e.g., 027 in UNSW CSE).\nYou need to use `chmod` manually if you want looser permissions. However, this umask setting\ncannot restrict manual permission modifications via `chmod` (be careful with `chmod +x` or `+r`).",
          "$ref": "#/$defs/Umask",
          "default": "077"
        },
        "user": {
          "description": "Username for the SSH connection.",
          "type": "string",
          "default": "z1234567"
        }
      }
    },
    "SyncConfig": {
      "description": "Synchronization settings.",
      "type": "object",
      "properties": {
        "auto": {
          "description": "Automatically synchronize the project before running remote commands.",
          "type": "boolean",
          "default": true
        },
        "engine": {
          "description": "The synchronization engine to use.",
          "$ref": "#/$defs/SyncEngine",
          "default": "sftp"
        },
        "exclude": {
          "description": "Files and directories to exclude during synchronization using globset patterns.",
          "type": "array",
          "default": [
            "**/.git/**",
            "**/target/**",
            "**/node_modules/**"
          ],
          "items": {
            "type": "string"
          }
        },
        "remote_root": {
          "description": "Remote directory to sync the project to.",
          "type": "string",
          "default": "~/.cache/biwa/projects"
        },
        "sftp": {
          "description": "SFTP engine specific configuration.",
          "$ref": "#/$defs/SyncSftpConfig",
          "default": {
            "max_files_to_sync": 100,
            "permissions": "recreate"
          }
        },
        "sync_root": {
          "description": "Base directory to start the synchronization from. If not specified, uses the current working directory.",
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "SyncEngine": {
      "description": "The synchronization engine to use.",
      "oneOf": [
        {
          "description": "Use SFTP for synchronization.",
          "type": "string",
          "const": "sftp"
        },
        {
          "description": "Use Mutagen for synchronization.",
          "type": "string",
          "const": "mutagen"
        }
      ]
    },
    "SyncSftpConfig": {
      "description": "SFTP synchronization engine settings.",
      "type": "object",
      "properties": {
        "max_files_to_sync": {
          "description": "Abort synchronization if the number of files to sync exceeds this limit.",
          "type": "integer",
          "default": 100,
          "minimum": 0
        },
        "permissions": {
          "description": "Strategy for enforcing file permissions on uploaded files.",
          "$ref": "#/$defs/SftpPermissions",
          "default": "recreate"
        }
      }
    },
    "Umask": {
      "description": "Umask value for SSH execution and sync, stored as a normalized 3-digit octal string.\n\nDeserializes from a string parsed as octal (e.g. `\"077\"`, `\"022\"`). Only the lower three\ndigits (owner/group/other) are supported. To set the first digit (setuid/setgid/sticky),\nrun `umask` manually on the remote server. Always serialized as a 3-digit octal string.",
      "type": "string"
    }
  }
}