Skip to content

Developer Guide

This guide is for ChatArch packages that want to use ChatEnv. ChatEnv owns typed env/profile mechanics; leaf packages own their service variables, connectivity tests, and runtime token semantics.

Responsibilities

ChatEnv provides:

  • EnvField for environment variable metadata.
  • BaseEnvConfig for typed schemas and automatic registry.
  • EnvStore for active .env and named profile files.
  • TokenStore for tokens/<Service>/<profile>.json runtime state with safe metadata.
  • chatenv CLI commands for env profiles and runtime tokens.
  • chatenv.configs discovery for schema providers.
  • chatenv.token_refreshers discovery for service-owned refresh hooks.

Leaf packages provide:

  • Their own BaseEnvConfig subclasses.
  • _aliases and _storage_dir.
  • chatenv.configs entry points.
  • Optional login/refresh functions registered through chatenv.token_refreshers.
  • Service-specific test() implementations.

Integrating a package

Depend on ChatEnv:

[project]
dependencies = [
    "chatenv>=0.2.8,<0.3.0",
]

Define a schema:

from chatenv import BaseEnvConfig, EnvField

class FooConfig(BaseEnvConfig):
    _title = "Foo Configuration"
    _aliases = ["foo", "chatfoo"]
    _storage_dir = "Foo"

    FOO_API_BASE = EnvField("FOO_API_BASE", desc="Foo API base URL")
    FOO_API_KEY = EnvField("FOO_API_KEY", desc="Foo API key", is_sensitive=True)

Register the provider:

[project.entry-points."chatenv.configs"]
chatfoo = "chatfoo.config"

Runtime token refresh providers

If a package needs access tokens, web sessions, cookies, or CSRF state, stable env/profile values should contain only re-authentication inputs. The runtime values should be generated by a service-owned refresh function:

[project.entry-points."chatenv.token_refreshers"]
Foo = "chatfoo.tokens:refresh_chatenv_token"

from chatenv import TokenRefreshResult

def refresh_chatenv_token(*, service, profile, home, env_store, token_store):
    return TokenRefreshResult(
        values={"access_token": "[REDACTED]"},
        token_type="oauth_access_token",
        summary={"account": "operator", "base_url": "https://foo.example"},
        expires_at="2026-08-11T23:00:00Z",
    )

chatenv token refresh Foo work invokes the hook and writes the token-store file. token import is only an explicit migration or external-refresh handoff path.

Local development

python -m pip install -e /path/to/ChatEnv
python -m pip install -e /path/to/chatfoo
chatenv status --detail
chatenv list
chatenv init -t foo -i
chatenv cat -t foo
chatenv test -t foo