cnos 1.11.4__py3-none-any.whl

cnos/__init__.py

@@ -0,0 +1,181 @@
+"""CNOS Python runtime — public API.
+
+Module-level functions mirror Go's singleton.go delegating functions.
+Call cnos.ready() or cnos.load() before using the module-level read functions.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+# Re-export the main public types
+from cnos.errors import CnosError
+from cnos.exports import (
+    config_hash,
+    format_message,
+    log_message,
+    to_env,
+    to_namespace,
+    to_object,
+    to_public_env,
+    to_server_projection,
+)
+from cnos.inspect import InspectResult
+from cnos.loader import (
+    CnosOptions,
+    bootstrap_default_runtime,
+    default_runtime,
+    load,
+    load_projection,
+    load_projection_file,
+    ready,
+    set_default_runtime,
+)
+from cnos.projection import ServerProjection
+from cnos.runtime import CnosRuntime
+from cnos.types import (
+    ConfigOrigin,
+    DerivedFormula,
+    SecretReference,
+    SecretVaultProvider,
+    SecretVaultProviderFactory,
+    ToEnvOptions,
+    ToPublicEnvOptions,
+    VaultAuthConfig,
+    VaultAuthDefinition,
+    VaultAuthSource,
+    VaultDefinition,
+)
+
+# ---------------------------------------------------------------------------
+# Module-level singleton API — mirror Go's package-level functions
+# ---------------------------------------------------------------------------
+
+def read(key: str) -> Tuple[Any, bool]:
+    return default_runtime().read(key)
+
+
+def require(key: str) -> Any:
+    return default_runtime().require(key)
+
+
+def read_or(key: str, fallback: Any) -> Any:
+    return default_runtime().read_or(key, fallback)
+
+
+def value(path: str) -> Tuple[Any, bool]:
+    return default_runtime().value(path)
+
+
+def secret(path: str) -> Tuple[Any, bool]:
+    return default_runtime().secret(path)
+
+
+def meta(path: str) -> Tuple[Any, bool]:
+    return default_runtime().meta(path)
+
+
+def public(path: str) -> Tuple[Any, bool]:
+    return default_runtime().public(path)
+
+
+def inspect(key: str) -> InspectResult:
+    return default_runtime().inspect(key)
+
+
+def get_to_object() -> Dict[str, Any]:
+    return to_object(default_runtime())
+
+
+def get_to_namespace(namespace: str) -> Dict[str, Any]:
+    return to_namespace(default_runtime(), namespace)
+
+
+def get_to_env(options: Optional[ToEnvOptions] = None) -> Dict[str, str]:
+    return to_env(default_runtime(), options)
+
+
+def get_to_public_env(options: Optional[ToPublicEnvOptions] = None) -> Dict[str, str]:
+    return to_public_env(default_runtime(), options)
+
+
+def get_to_server_projection() -> ServerProjection:
+    return to_server_projection(default_runtime())
+
+
+def get_format(message: str) -> str:
+    return format_message(default_runtime(), message)
+
+
+def get_log(message: str) -> str:
+    return log_message(default_runtime(), message)
+
+
+def refresh_secrets() -> None:
+    default_runtime().refresh_secrets()
+
+
+def refresh_secret(path: str) -> None:
+    default_runtime().refresh_secret(path)
+
+
+def register_runtime_provider(namespace: str, provider: Any) -> None:
+    default_runtime().register_runtime_provider(namespace, provider)
+
+
+def register_secret_vault_providers(*factories: SecretVaultProviderFactory) -> None:
+    default_runtime().register_secret_vault_providers(*factories)
+
+
+# Bootstrap eagerly (mirrors Go's init())
+bootstrap_default_runtime()
+
+__all__ = [
+    # Error
+    "CnosError",
+    # Main classes
+    "CnosRuntime",
+    "CnosOptions",
+    "ServerProjection",
+    "InspectResult",
+    # Types
+    "DerivedFormula",
+    "SecretReference",
+    "VaultDefinition",
+    "VaultAuthConfig",
+    "VaultAuthDefinition",
+    "VaultAuthSource",
+    "ConfigOrigin",
+    "ToEnvOptions",
+    "ToPublicEnvOptions",
+    "SecretVaultProvider",
+    "SecretVaultProviderFactory",
+    # Loader
+    "load",
+    "load_projection",
+    "load_projection_file",
+    "ready",
+    "set_default_runtime",
+    "default_runtime",
+    # Module-level read API
+    "read",
+    "require",
+    "read_or",
+    "value",
+    "secret",
+    "meta",
+    "public",
+    "inspect",
+    # Export API
+    "get_to_object",
+    "get_to_namespace",
+    "get_to_env",
+    "get_to_public_env",
+    "get_to_server_projection",
+    "get_format",
+    "get_log",
+    "config_hash",
+    "refresh_secrets",
+    "refresh_secret",
+    "register_runtime_provider",
+    "register_secret_vault_providers",
+]

cnos/_internal/__init__.py

@@ -0,0 +1 @@
+# internal package

cnos/_internal/entry.py

@@ -0,0 +1,31 @@
+"""Internal runtime entry and provenance types."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Optional
+
+from cnos.types import ConfigOrigin, SecretReference
+
+
+@dataclass
+class RuntimeProvenance:
+    source_id: str = ""
+    plugin_id: str = ""
+    workspace_id: str = ""
+    value: Any = None
+    origin: Optional[ConfigOrigin] = None
+
+
+@dataclass
+class RuntimeEntry:
+    key: str = ""
+    namespace: str = ""
+    value: Any = None
+    alias_to: str = ""
+    promoted_from: str = ""
+    formula: Optional[Any] = None  # ParsedFormula — avoid circular import
+    formula_cached: bool = False
+    formula_cache: Any = None
+    secret_ref: Optional[SecretReference] = None
+    winner: RuntimeProvenance = field(default_factory=RuntimeProvenance)
+    overridden: List[RuntimeProvenance] = field(default_factory=list)

cnos/derive.py

@@ -0,0 +1,399 @@
+"""Derived formula parser and evaluator — mirrors Go's derive.go exactly."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple
+
+from cnos.errors import CnosError
+from cnos.jscompat import js_stringify_value, js_strict_equal
+from cnos.types import DerivedFormula
+
+
+# ---------------------------------------------------------------------------
+# AST node
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ExprNode:
+    kind: str = ""        # "literal" | "ref" | "call"
+    value: Any = None     # for kind="literal"
+    path: str = ""        # for kind="ref"
+    name: str = ""        # for kind="call"
+    args: List["ExprNode"] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Parsed formula (internal)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ParsedFormula:
+    raw: str = ""
+    refs: List[str] = field(default_factory=list)
+    deps: List[str] = field(default_factory=list)
+    runtime_refs: List[str] = field(default_factory=list)
+    runtime_dependent: bool = False
+    ast: Optional[ExprNode] = None
+
+
+_DERIVE_BUILTINS: Set[str] = {"concat", "coalesce", "when", "exists", "eq", "ne"}
+
+
+# ---------------------------------------------------------------------------
+# Parser state
+# ---------------------------------------------------------------------------
+
+class _ParserState:
+    def __init__(self, source: str) -> None:
+        self.source = source
+        self.index = 0
+
+    def errorf(self, message: str) -> CnosError:
+        return CnosError(f"cnos: {message} at position {self.index + 1}")
+
+
+def _is_whitespace(ch: str) -> bool:
+    return ch in " \n\r\t"
+
+
+def _skip_whitespace(state: _ParserState) -> None:
+    while state.index < len(state.source) and _is_whitespace(state.source[state.index]):
+        state.index += 1
+
+
+def _is_identifier_start(ch: str) -> bool:
+    return ch.isalpha() or ch == "_"
+
+
+def _is_identifier_part(ch: str) -> bool:
+    return ch.isalpha() or ch.isdigit() or ch in "._-"
+
+
+def _is_valid_template_ref(value: str) -> bool:
+    if not value or not _is_identifier_start(value[0]):
+        return False
+    for ch in value[1:]:
+        if not _is_identifier_part(ch):
+            return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Parser functions
+# ---------------------------------------------------------------------------
+
+def _parse_string_literal(state: _ParserState) -> ExprNode:
+    state.index += 1  # consume opening '
+    chars: List[str] = []
+    while state.index < len(state.source):
+        ch = state.source[state.index]
+        if ch == "\\":
+            if state.index + 1 >= len(state.source):
+                raise state.errorf("Unterminated escape sequence")
+            chars.append(state.source[state.index + 1])
+            state.index += 2
+            continue
+        if ch == "'":
+            state.index += 1
+            return ExprNode(kind="literal", value="".join(chars))
+        chars.append(ch)
+        state.index += 1
+    raise state.errorf("Unterminated string literal")
+
+
+def _parse_number_literal(state: _ParserState) -> ExprNode:
+    start = state.index
+    while state.index < len(state.source) and state.source[state.index].isdigit():
+        state.index += 1
+    if state.index < len(state.source) and state.source[state.index] == ".":
+        state.index += 1
+        while state.index < len(state.source) and state.source[state.index].isdigit():
+            state.index += 1
+    raw = state.source[start:state.index]
+    try:
+        return ExprNode(kind="literal", value=float(raw))
+    except ValueError as exc:
+        raise CnosError(f"cnos: invalid number literal: {raw}") from exc
+
+
+def _parse_identifier(state: _ParserState) -> str:
+    if state.index >= len(state.source) or not _is_identifier_start(state.source[state.index]):
+        raise state.errorf("Expected identifier")
+    start = state.index
+    state.index += 1
+    while state.index < len(state.source) and _is_identifier_part(state.source[state.index]):
+        state.index += 1
+    return state.source[start:state.index]
+
+
+def _parse_arguments(state: _ParserState) -> List[ExprNode]:
+    args: List[ExprNode] = []
+    _skip_whitespace(state)
+    if state.index < len(state.source) and state.source[state.index] == ")":
+        state.index += 1
+        return args
+    while state.index < len(state.source):
+        node = _parse_expression_node(state)
+        args.append(node)
+        _skip_whitespace(state)
+        if state.index >= len(state.source):
+            break
+        ch = state.source[state.index]
+        if ch == ",":
+            state.index += 1
+            _skip_whitespace(state)
+        elif ch == ")":
+            state.index += 1
+            return args
+        else:
+            raise state.errorf('Expected "," or ")"')
+    raise state.errorf("Unterminated function call")
+
+
+def _parse_identifier_or_call(state: _ParserState) -> ExprNode:
+    identifier = _parse_identifier(state)
+    _skip_whitespace(state)
+    if state.index < len(state.source) and state.source[state.index] == "(":
+        if identifier not in _DERIVE_BUILTINS:
+            raise CnosError(f"cnos: unknown derive function: {identifier}")
+        state.index += 1  # consume '('
+        args = _parse_arguments(state)
+        return ExprNode(kind="call", name=identifier, args=args)
+    # keywords or ref
+    if identifier == "true":
+        return ExprNode(kind="literal", value=True)
+    if identifier == "false":
+        return ExprNode(kind="literal", value=False)
+    if identifier == "null":
+        return ExprNode(kind="literal", value=None)
+    return ExprNode(kind="ref", path=identifier)
+
+
+def _parse_expression_node(state: _ParserState) -> ExprNode:
+    _skip_whitespace(state)
+    if state.index >= len(state.source):
+        raise state.errorf("Unexpected token")
+    ch = state.source[state.index]
+    if ch == "'":
+        return _parse_string_literal(state)
+    if ch.isdigit():
+        return _parse_number_literal(state)
+    if _is_identifier_start(ch):
+        return _parse_identifier_or_call(state)
+    raise state.errorf("Unexpected token")
+
+
+def _parse_template(source: str) -> ExprNode:
+    parts: List[ExprNode] = []
+    cursor = 0
+    while cursor < len(source):
+        start = source.find("${", cursor)
+        if start == -1:
+            if cursor < len(source):
+                parts.append(ExprNode(kind="literal", value=source[cursor:]))
+            break
+        if start > cursor:
+            parts.append(ExprNode(kind="literal", value=source[cursor:start]))
+        end = source.find("}", start + 2)
+        if end == -1:
+            raise CnosError(
+                f"cnos: invalid derivation template: unclosed ${{...}} at position {start + 1}"
+            )
+        ref = source[start + 2:end].strip()
+        if not ref:
+            raise CnosError(
+                f"cnos: invalid derivation template: empty reference at position {start + 1}"
+            )
+        if not _is_valid_template_ref(ref):
+            raise CnosError(
+                f"cnos: invalid derivation template reference {ref!r}"
+            )
+        parts.append(ExprNode(kind="ref", path=ref))
+        cursor = end + 1
+
+    if not parts:
+        return ExprNode(kind="literal", value="")
+    if len(parts) == 1:
+        return parts[0]
+    return ExprNode(kind="call", name="concat", args=parts)
+
+
+def parse_derived_source(source: str) -> ExprNode:
+    if "${" in source:
+        return _parse_template(source)
+    state = _ParserState(source)
+    node = _parse_expression_node(state)
+    _skip_whitespace(state)
+    if state.index != len(state.source):
+        raise state.errorf("Unexpected trailing input")
+    return node
+
+
+def parse_derived_formula(formula: DerivedFormula) -> ParsedFormula:
+    ast = parse_derived_source(formula.expr)
+    refs = list(formula.deps) + list(formula.runtime_refs)
+    unique_refs = _unique_sorted(refs)
+    return ParsedFormula(
+        raw=formula.expr,
+        refs=unique_refs,
+        deps=list(formula.deps),
+        runtime_refs=list(formula.runtime_refs),
+        runtime_dependent=len(formula.runtime_refs) > 0,
+        ast=ast,
+    )
+
+
+def parse_raw_derived_value(value: Any) -> ParsedFormula:
+    """Parse a $derive value from a graph entry."""
+    source = _derive_source_from_value(value)
+    ast = parse_derived_source(source)
+    refs = _extract_refs(ast, [])
+    unique_refs = _unique_sorted(refs)
+    return ParsedFormula(
+        raw=source,
+        refs=unique_refs,
+        deps=unique_refs,
+        ast=ast,
+    )
+
+
+def _derive_source_from_value(value: Any) -> str:
+    if not isinstance(value, dict):
+        raise CnosError(
+            "cnos: derived value requires either a template string or { expr } object"
+        )
+    raw = value.get("$derive")
+    if raw is None:
+        raise CnosError(
+            "cnos: derived value requires either a template string or { expr } object"
+        )
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, dict):
+        source = raw.get("expr", "")
+        if not isinstance(source, str) or not source.strip():
+            raise CnosError(
+                "cnos: derived value requires either a template string or { expr } object"
+            )
+        return source
+    raise CnosError("cnos: derived value requires either a template string or { expr } object")
+
+
+def is_derived_value(value: Any) -> bool:
+    return isinstance(value, dict) and "$derive" in value
+
+
+def _extract_refs(node: ExprNode, refs: List[str]) -> List[str]:
+    if node.kind == "ref":
+        refs.append(node.path)
+    elif node.kind == "call":
+        for arg in node.args:
+            refs = _extract_refs(arg, refs)
+    return refs
+
+
+# ---------------------------------------------------------------------------
+# Evaluator
+# ---------------------------------------------------------------------------
+
+ResolveRef = Callable[[str], Tuple[Any, bool]]
+
+
+def evaluate_derived_formula(
+    key: str,
+    formula: ParsedFormula,
+    resolve_ref: ResolveRef,
+) -> Any:
+    value, found, err = _evaluate_node(formula.ast, resolve_ref)
+    if err:
+        raise CnosError(err)
+    if formula.ast is not None and formula.ast.kind == "ref" and not found:
+        raise CnosError(
+            f"cnos: unable to resolve derived config key {key} because {formula.ast.path} is missing"
+        )
+    return value
+
+
+def _evaluate_node(
+    node: ExprNode,
+    resolve_ref: ResolveRef,
+) -> Tuple[Any, bool, Optional[str]]:
+    if node.kind == "literal":
+        return node.value, True, None
+    if node.kind == "ref":
+        val, found = resolve_ref(node.path)
+        return val, found, None
+    if node.kind == "call":
+        values: List[Any] = []
+        flags: List[bool] = []
+        for arg in node.args:
+            val, found, err = _evaluate_node(arg, resolve_ref)
+            if err:
+                return None, False, err
+            values.append(val)
+            flags.append(found)
+        val, found, err = _evaluate_call(node.name, values, flags)
+        return val, found, err
+    return None, False, f"cnos: unsupported derive AST node {node.kind!r}"
+
+
+def _evaluate_call(
+    name: str, values: List[Any], flags: List[bool]
+) -> Tuple[Any, bool, Optional[str]]:
+    if name == "concat":
+        parts = [js_stringify_value(v) for v in values]
+        return "".join(parts), True, None
+    if name == "coalesce":
+        for v in values:
+            if v is not None:
+                return v, True, None
+        return None, True, None
+    if name == "when":
+        when_true = values[1] if len(values) > 1 else None
+        when_false = values[2] if len(values) > 2 else None
+        if _is_truthy(values[0] if values else None):
+            return when_true, True, None
+        return when_false, True, None
+    if name == "exists":
+        if not values:
+            return False, True, None
+        return (flags[0] and values[0] is not None), True, None
+    if name == "eq":
+        left = values[0] if values else None
+        right = values[1] if len(values) > 1 else None
+        return js_strict_equal(left, right), True, None
+    if name == "ne":
+        left = values[0] if values else None
+        right = values[1] if len(values) > 1 else None
+        return not js_strict_equal(left, right), True, None
+    return None, False, f"cnos: unknown derive function: {name}"
+
+
+def _is_truthy(value: Any) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return bool(value)
+    if isinstance(value, (int, float)):
+        return value != 0
+    return True
+
+
+def _unique_sorted(values: List[str]) -> List[str]:
+    seen: Set[str] = set()
+    result: List[str] = []
+    for v in values:
+        if v and v not in seen:
+            seen.add(v)
+            result.append(v)
+    return sorted(result)
+
+
+def formula_type(formula: Optional[ParsedFormula]) -> str:
+    if formula is None:
+        return ""
+    if formula.raw and "${" in formula.raw:
+        return "template"
+    return "expression"

cnos/discover.py

@@ -0,0 +1,49 @@
+"""Projection file discovery — mirrors Go's discover.go."""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+PROJECTION_FILE_NAME = ".cnos-server.json"
+
+
+def find_projection_path(working_dir: str = "") -> Optional[str]:
+    """Find .cnos-server.json by checking cwd then walking up 3 levels near .cnosrc.yml."""
+    cwd = _resolve_working_dir(working_dir)
+
+    # Direct candidate at cwd
+    direct = os.path.join(cwd, PROJECTION_FILE_NAME)
+    if _file_exists(direct):
+        return direct
+
+    # Walk up looking for .cnosrc.yml alongside .cnos-server.json
+    current = cwd
+    for _ in range(4):  # depth 0..3
+        rc_candidate = os.path.join(current, ".cnosrc.yml")
+        if _file_exists(rc_candidate):
+            proj_candidate = os.path.join(current, PROJECTION_FILE_NAME)
+            if _file_exists(proj_candidate):
+                return proj_candidate
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+
+    return None
+
+
+def _resolve_working_dir(working_dir: str) -> str:
+    if working_dir:
+        return os.path.abspath(working_dir)
+    return os.getcwd()
+
+
+def _file_exists(path: str) -> bool:
+    return os.path.isfile(path)
+
+
+def resolve_path_from_working_dir(working_dir: str, target: str) -> str:
+    if os.path.isabs(target):
+        return target
+    base = _resolve_working_dir(working_dir)
+    return os.path.join(base, target)

cnos/env.py

@@ -0,0 +1,38 @@
+"""Environment abstraction — mirrors Go's environment struct."""
+from __future__ import annotations
+
+import os
+from typing import Dict, Optional, Tuple
+
+
+class Environment:
+    """Wraps real or injected environment variables."""
+
+    def __init__(self, override: Optional[Dict[str, str]] = None) -> None:
+        if override is None:
+            self._override: Optional[Dict[str, str]] = None
+            self._use_os = True
+        else:
+            self._override = dict(override)
+            self._use_os = False
+
+    def get(self, key: str) -> Tuple[Optional[str], bool]:
+        """Return (value, found)."""
+        if self._use_os:
+            value = os.environ.get(key)
+            return value, value is not None
+        if self._override is not None:
+            if key in self._override:
+                return self._override[key], True
+        return None, False
+
+    def process_env(self) -> Dict[str, str]:
+        """Return a merged dict of os.environ + any override."""
+        values: Dict[str, str] = dict(os.environ)
+        if not self._use_os and self._override:
+            values.update(self._override)
+        return values
+
+    @property
+    def use_os(self) -> bool:
+        return self._use_os