2026-01-14 03:09:18 +00:00
|
|
|
# Path Resolution API\n\nThis document describes the path resolution system used throughout the provisioning infrastructure for discovering configurations, extensions, and\nresolving workspace paths.\n\n## Overview\n\nThe path resolution system provides a hierarchical and configurable mechanism for:\n\n- Configuration file discovery and loading\n- Extension discovery (providers, task services, clusters)\n- Workspace and project path management\n- Environment variable interpolation\n- Cross-platform path handling\n\n## Configuration Resolution Hierarchy\n\nThe system follows a specific hierarchy for loading configuration files:\n\n```\n1. System defaults (config.defaults.toml)\n2. User configuration (config.user.toml)\n3. Project configuration (config.project.toml)\n4. Infrastructure config (infra/config.toml)\n5. Environment config (config.{env}.toml)\n6. Runtime overrides (CLI arguments, ENV vars)\n```\n\n### Configuration Search Paths\n\nThe system searches for configuration files in these locations:\n\n```\n# Default search paths (in order)\n/usr/local/provisioning/config.defaults.toml\n$HOME/.config/provisioning/config.user.toml\n$PWD/config.project.toml\n$PROVISIONING_KLOUD_PATH/config.infra.toml\n$PWD/config.{PROVISIONING_ENV}.toml\n```\n\n## Path Resolution API\n\n### Core Functions\n\n#### `resolve-config-path(pattern: string, search_paths: list<string>) -> string`\n\nResolves configuration file paths using the search hierarchy.\n\n**Parameters:**\n\n- `pattern`: File pattern to search for (for example, "config.*.toml")\n- `search_paths`: Additional paths to search (optional)\n\n**Returns:**\n\n- Full path to the first matching configuration file\n- Empty string if no file found\n\n**Example:**\n\n```\nuse path-resolution.nu *\nlet config_path = (resolve-config-path "config.user.toml" [])\n# Returns: "/home/user/.config/provisioning/config.user.toml"\n```\n\n#### `resolve-extension-path(type: string, name: string) -> record`\n\nDiscovers extension paths (providers, taskservs, clusters).\n\n**Parameters:**\n\n- `type`: Extension type ("provider", "taskserv", "cluster")\n- `name`: Extension name (for example, "upcloud", "kubernetes", "buildkit")\n\n**Returns:**\n\n```\n{\n base_path: "/usr/local/provisioning/providers/upcloud",\n schemas_path: "/usr/local/provisioning/providers/upcloud/schemas",\n nulib_path: "/usr/local/provisioning/providers/upcloud/nulib",\n templates_path: "/usr/local/provisioning/providers/upcloud/templates",\n exists: true\n}\n```\n\n#### `resolve-workspace-paths() -> record`\n\nGets current workspace path configuration.\n\n**Returns:**\n\n```\n{\n base: "/usr/local/provisioning",\n current_infra: "/workspace/infra/production",\n kloud_path: "/workspace/kloud",\n providers: "/usr/local/provisioning/providers",\n taskservs: "/usr/local/provisioning/taskservs",\n clusters: "/usr/local/provisioning/cluster",\n extensions: "/workspace/extensions"\n}\n```\n\n### Path Interpolation\n\nThe system supports variable interpolation in configuration paths:\n\n#### Supported Variables\n\n- `{{paths.base}}` - Base provisioning path\n- `{{paths.kloud}}` - Current kloud path\n- `{{env.HOME}}` - User home directory\n- `{{env.PWD}}` - Current working directory\n- `{{now.date}}` - Current date (YYYY-MM-DD)\n- `{{now.time}}` - Current time (HH:MM:SS)\n- `{{git.branch}}` - Current git branch\n- `{{git.commit}}` - Current git commit hash\n\n#### `interpolate-path(template: string, context: record) -> string`\n\nInterpolates variables in path templates.\n\n**Parameters:**\n\n- `template`: Path template with variables\n- `context`: Variable context record\n\n**Example:**\n\n```\nlet template = "{{paths.base}}/infra/{{env.USER}}/{{git.branch}}"\nlet result = (interpolate-path $template {\n paths: { base: "/usr/local/provisioning" },\n env: { USER: "admin" },\n git: { branch: "main" }\n})\n# Returns: "/usr/local/provisioning/infra/admin/main"\n```\n\n## Extension Discovery API\n\n### Provider Discovery\n\n#### `discover-providers() -> list<record>`\n\nDiscovers
|
