Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
"""One-time consolidation of legacy FCC dotenv state."""
import json
import os
import re
import uuid
from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
from loguru import logger
from .api_keys import api_key_values, encode_api_keys, normalize_api_keys
from .custom_providers import (
CUSTOM_PROVIDERS_ENV,
decode_custom_providers,
)
from .env_files import (
ANTHROPIC_AUTH_TOKEN_ENV,
FCC_CONFIG_SCHEMA_ENV,
PROXY_AUTH_ENABLED_ENV,
dotenv_values_from_file,
dotenv_values_from_text,
legacy_explicit_env_path,
verified_checkout_env_path,
)
from .model_refs import normalize_retired_model_settings
from .paths import legacy_env_paths, managed_env_path
from .provider_catalog import PROVIDER_CATALOG
from .settings import Settings
CONFIG_SCHEMA_VERSION = "2"
LEGACY_HUGGINGFACE_TOKEN_ENV = "HF_TOKEN"
HUGGINGFACE_API_KEY_ENV = "HUGGINGFACE_API_KEY"
LEGACY_OPENCODE_PROXY_ENV = "OPENCODE_PROXY"
OPENCODE_ZEN_PROXY_ENV = "OPENCODE_ZEN_PROXY"
LEGACY_OPENCODE_SMOKE_MODEL_ENV = "FCC_SMOKE_MODEL_OPENCODE"
OPENCODE_ZEN_SMOKE_MODEL_ENV = "FCC_SMOKE_MODEL_OPENCODE_ZEN"
_SPECIAL_SMOKE_KEYS = frozenset(
{
"FCC_SMOKE_MODEL_MISTRAL_REASONING",
"FCC_SMOKE_NIM_MODELS",
"FCC_SMOKE_NIM_EXTRA_MODELS",
"FCC_SMOKE_OPENROUTER_FREE_MODELS",
"FCC_SMOKE_OPENROUTER_FREE_EXTRA_MODELS",
}
)
_DOTENV_ASSIGNMENT_RE = re.compile(
r"^(?P<prefix>\s*(?:export\s+)?)(?P<key>[A-Za-z_][A-Za-z0-9_]*)(?P<suffix>\s*(?:=|$))"
)
@dataclass(frozen=True, slots=True)
class EnvMigration:
"""A migration for one dotenv setting."""
old_key: str
new_key: str
value_map: tuple[tuple[str, str], ...] = ()
value_prefix_map: tuple[tuple[str, str], ...] = ()
@dataclass(frozen=True, slots=True)
class ConfigMigrationResult:
"""Outcome of one managed-config consolidation attempt."""
changed: bool
imported_from: tuple[Path, ...] = ()
HUGGINGFACE_TOKEN_MIGRATION = EnvMigration(
old_key=LEGACY_HUGGINGFACE_TOKEN_ENV,
new_key=HUGGINGFACE_API_KEY_ENV,
)
_LEGACY_TRUE_VALUES = ("1", "true", "t", "on", "yes", "y")
_LEGACY_FALSE_VALUES = ("0", "false", "f", "off", "no", "n")
_LEGACY_REASONING_BOOLEAN_MAP = (
*((value, "client") for value in _LEGACY_TRUE_VALUES),
*((value, "off") for value in _LEGACY_FALSE_VALUES),
)
REASONING_MIGRATIONS = (
EnvMigration(
"ENABLE_MODEL_THINKING",
"REASONING_POLICY",
_LEGACY_REASONING_BOOLEAN_MAP,
),
*(
EnvMigration(
f"ENABLE_{route}_THINKING",
f"REASONING_{route}",
(("", "inherit"), *_LEGACY_REASONING_BOOLEAN_MAP),
)
for route in ("FABLE", "OPUS", "SONNET", "HAIKU")
),
)
OPENCODE_ZEN_KEY_MIGRATIONS = (
EnvMigration(LEGACY_OPENCODE_PROXY_ENV, OPENCODE_ZEN_PROXY_ENV),
EnvMigration(
LEGACY_OPENCODE_SMOKE_MODEL_ENV,
OPENCODE_ZEN_SMOKE_MODEL_ENV,
value_prefix_map=(("opencode/", "opencode_zen/"),),
),
)
OPENCODE_ZEN_MODEL_REF_MIGRATIONS = tuple(
EnvMigration(
key,
key,
value_prefix_map=(("opencode/", "opencode_zen/"),),
)
for key in (
"MODEL",
"MODEL_FABLE",
"MODEL_OPUS",
"MODEL_SONNET",
"MODEL_HAIKU",
OPENCODE_ZEN_SMOKE_MODEL_ENV,
)
)
ENV_MIGRATIONS = (
HUGGINGFACE_TOKEN_MIGRATION,
*REASONING_MIGRATIONS,
*OPENCODE_ZEN_KEY_MIGRATIONS,
*OPENCODE_ZEN_MODEL_REF_MIGRATIONS,
)
_RETIRED_ENV_KEYS = frozenset(
migration.old_key
for migration in ENV_MIGRATIONS
if migration.old_key != migration.new_key
)
def settings_env_keys() -> frozenset[str]:
"""Return the explicit environment aliases owned by Settings."""
keys: set[str] = set()
for name, field in Settings.model_fields.items():
if name == "nim":
continue
alias = field.validation_alias
if not isinstance(alias, str):
raise AssertionError(f"Settings field {name!r} needs one string alias")
keys.add(alias)
return frozenset(keys)
def smoke_env_keys() -> frozenset[str]:
"""Return catalog-derived and special live-smoke configuration keys."""
catalog_keys = {
f"FCC_SMOKE_MODEL_{provider_id.upper()}" for provider_id in PROVIDER_CATALOG
}
return frozenset(catalog_keys) | _SPECIAL_SMOKE_KEYS
def recognized_env_keys() -> frozenset[str]:
"""Return every dotenv key FCC may import into managed configuration."""
migrated_keys = {
key
for migration in ENV_MIGRATIONS
for key in (migration.old_key, migration.new_key)
}
return (
settings_env_keys() | smoke_env_keys() | migrated_keys | {FCC_CONFIG_SCHEMA_ENV}
)
def secret_env_keys() -> frozenset[str]:
"""Return settings aliases whose values must be masked in previews."""
secret_attrs = {
name
for name in Settings.model_fields
if name.endswith(("_api_key", "_proxy", "_token"))
}
secret_attrs.update({"telegram_proxy_url", "proxy_auth_token", "custom_providers"})
secret_attrs.update(
descriptor.credential_attr
for descriptor in PROVIDER_CATALOG.values()
if descriptor.credential_attr is not None
)
return frozenset(
str(Settings.model_fields[name].validation_alias) for name in secret_attrs
)
def consolidate_managed_config(
env: Mapping[str, str] | None = None,
) -> ConfigMigrationResult:
"""Consolidate pre-schema configuration into ``~/.fcc/.env`` once."""
process = env if env is not None else os.environ
managed = managed_env_path()
base_path: Path | None = managed if managed.exists() else _legacy_base_path()
base_is_managed = base_path == managed
base_text = _read_text(base_path) if base_path is not None else ""
base_values = dotenv_values_from_text(base_text)
if base_is_managed:
schema = base_values.get(FCC_CONFIG_SCHEMA_ENV)
if schema == CONFIG_SCHEMA_VERSION:
normalized = normalize_retired_model_settings(
base_values, preserve_empty_overrides=False
)
if normalized == base_values:
return ConfigMigrationResult(changed=False)
atomic_write_managed_config(normalized, path=managed)
_log_model_repairs(base_values, normalized)
return ConfigMigrationResult(changed=True)
if schema == "1":
repaired = normalize_retired_model_settings(
base_values, preserve_empty_overrides=False
)
normalized = _normalize_credential_lists(repaired, process)
normalized[FCC_CONFIG_SCHEMA_ENV] = CONFIG_SCHEMA_VERSION
atomic_write_managed_config(normalized, path=managed)
_log_model_repairs(base_values, repaired)
return ConfigMigrationResult(changed=True)
if schema not in {None, ""}:
raise ValueError(
f"Managed config {managed} uses unsupported schema {schema!r}; "
f"this FCC version supports {CONFIG_SCHEMA_VERSION}."
)
known = recognized_env_keys()
base_values = _migrated_values(base_text)
values = (
dict(base_values)
if base_is_managed
else {key: value for key, value in base_values.items() if key in known}
)
imported: list[Path] = []
if base_path is not None and not base_is_managed:
imported.append(base_path.resolve())
explicit_path = legacy_explicit_env_path(process)
if explicit_path is not None and not _same_path(explicit_path, managed):
explicit_values = _migrated_values(_read_required_text(explicit_path))
values.update(
{key: value for key, value in explicit_values.items() if key in known}
)
imported.append(explicit_path.resolve())
for key in _RETIRED_ENV_KEYS:
values.pop(key, None)
values.pop(FCC_CONFIG_SCHEMA_ENV, None)
_materialize_auth_state(values, process, had_legacy_state=base_path is not None)
for key in tuple(values):
if key in known and key != FCC_CONFIG_SCHEMA_ENV and not values[key].strip():
values.pop(key)
values[FCC_CONFIG_SCHEMA_ENV] = CONFIG_SCHEMA_VERSION
normalized = _normalize_credential_lists(
normalize_retired_model_settings(values, preserve_empty_overrides=False),
process,
)
atomic_write_managed_config(normalized, path=managed)
_log_model_repairs(values, normalized)
return ConfigMigrationResult(changed=True, imported_from=tuple(imported))
def _normalize_credential_lists(
values: Mapping[str, str], process: Mapping[str, str]
) -> dict[str, str]:
normalized = dict(values)
owners = {
descriptor.credential_env
for descriptor in PROVIDER_CATALOG.values()
if descriptor.credential_env is not None
}
for key in owners & normalized.keys():
try:
encoded = encode_api_keys(normalize_api_keys(normalized[key]))
except ValueError as exc:
if key in process:
continue
raise ValueError(f"{key}: {exc}") from None
if encoded is None:
normalized.pop(key)
else:
normalized[key] = encoded
if CUSTOM_PROVIDERS_ENV in normalized:
try:
decoded = decode_custom_providers(normalized[CUSTOM_PROVIDERS_ENV])
if not isinstance(decoded, list):
raise ValueError("Custom providers must be a JSON array")
for definition in decoded:
if not isinstance(definition, dict):
continue
if "api_key" in definition and "api_keys" in definition:
continue # Effective Settings validation rejects this conflict.
member = "api_key" if "api_key" in definition else "api_keys"
if member in definition:
keys = api_key_values(normalize_api_keys(definition.pop(member)))
definition["api_keys"] = keys
normalized[CUSTOM_PROVIDERS_ENV] = json.dumps(
decoded, ensure_ascii=False, separators=(",", ":")
)
except ValueError:
if CUSTOM_PROVIDERS_ENV not in process:
raise
return normalized
def _log_model_repairs(before: Mapping[str, str], after: Mapping[str, str]) -> None:
changed = sorted(key for key in before if before[key] != after.get(key))
if changed:
logger.info(
"Repaired retired model selections in managed config: {}",
", ".join(changed),
)
def atomic_write_managed_config(
values: Mapping[str, str],
*,
path: Path | None = None,
mask_secrets: bool = False,
) -> str:
"""Atomically write canonical managed config and return the rendered text."""
target = path or managed_env_path()
rendered = render_managed_config(values, mask_secrets=mask_secrets)
if mask_secrets:
return rendered
target.parent.mkdir(parents=True, exist_ok=True)
temp_path = target.with_name(f".{target.name}.{uuid.uuid4().hex}.tmp")
try:
with temp_path.open("x", encoding="utf-8", newline="\n") as handle:
handle.write(rendered)
handle.flush()
os.fsync(handle.fileno())
if os.name != "nt":
temp_path.chmod(0o600)
os.replace(temp_path, target)
if os.name != "nt":
target.chmod(0o600)
finally:
temp_path.unlink(missing_ok=True)
return rendered
def render_managed_config(
values: Mapping[str, str],
*,
mask_secrets: bool = False,
) -> str:
"""Render sparse canonical FCC configuration."""
known = recognized_env_keys()
secret_keys = secret_env_keys()
canonical = dict(values)
canonical[FCC_CONFIG_SCHEMA_ENV] = CONFIG_SCHEMA_VERSION
lines = [
"# Managed by Free Claude Code.",
"# Edit settings in /admin when possible.",
f"{FCC_CONFIG_SCHEMA_ENV}={CONFIG_SCHEMA_VERSION}",
]
configured = [
key
for key in canonical
if key != FCC_CONFIG_SCHEMA_ENV and key in known and canonical[key].strip()
]
if configured:
lines.extend(("", "# Configured settings"))
for key in sorted(configured):
value = (
"********" if mask_secrets and key in secret_keys else canonical[key]
)
lines.append(f"{key}={quote_env_value(value)}")
unknown = [key for key in canonical if key not in known]
if unknown:
lines.extend(("", "# Preserved unrecognized settings"))
lines.extend(
f"{key}={quote_env_value('********' if mask_secrets else canonical[key])}"
for key in sorted(unknown)
)
return "\n".join(lines) + "\n"
def quote_env_value(value: str) -> str:
"""Quote a value when dotenv syntax requires it."""
escaped = value.replace("\\", "\\\\").replace('"', '\\"')
if (
not value
or any(char.isspace() for char in value)
or any(char in value for char in ('"', "#", "=", "$"))
):
return f'"{escaped}"'
return value
def migrate_env_setting_in_text(
text: str,
migration: EnvMigration,
) -> tuple[str, bool]:
"""Return text with one setting migration applied when safe."""
if migration.old_key != migration.new_key and _defines_key(text, migration.new_key):
return text, False
lines = text.splitlines(keepends=True)
changed = False
for index, line in enumerate(lines):
match = _DOTENV_ASSIGNMENT_RE.match(line)
if match is None or match.group("key") != migration.old_key:
continue
remainder = line[match.end() :]
if migration.value_map:
remainder = _mapped_value(remainder, migration.value_map)
for old_prefix, new_prefix in migration.value_prefix_map:
remainder = _mapped_prefix_value(remainder, old_prefix, new_prefix)
migrated_line = (
f"{match.group('prefix')}{migration.new_key}{match.group('suffix')}"
f"{remainder}"
)
if migrated_line == line:
continue
lines[index] = migrated_line
changed = True
if not changed:
return text, False
return "".join(lines), True
def env_text_needs_migration(text: str, migration: EnvMigration) -> bool:
"""Return whether one setting migration would change text."""
return migrate_env_setting_in_text(text, migration)[1]
def _legacy_base_path() -> Path | None:
for path in legacy_env_paths():
if path.is_file():
return path
return verified_checkout_env_path()
def _read_text(path: Path | None) -> str:
return "" if path is None else _read_required_text(path)
def _read_required_text(path: Path) -> str:
dotenv_values_from_file(path)
try:
return path.read_text(encoding="utf-8")
except OSError as exc:
raise OSError(f"Could not read configuration file {path}: {exc}") from exc
def _migrated_values(text: str) -> dict[str, str]:
migrated = text
for migration in ENV_MIGRATIONS:
migrated, _ = migrate_env_setting_in_text(migrated, migration)
return dotenv_values_from_text(migrated)
def _materialize_auth_state(
values: dict[str, str],
process: Mapping[str, str],
*,
had_legacy_state: bool,
) -> None:
if PROXY_AUTH_ENABLED_ENV in values:
return
if PROXY_AUTH_ENABLED_ENV in process:
return
if ANTHROPIC_AUTH_TOKEN_ENV in values:
values[PROXY_AUTH_ENABLED_ENV] = (
"true" if values[ANTHROPIC_AUTH_TOKEN_ENV].strip() else "false"
)
return
if had_legacy_state:
values[PROXY_AUTH_ENABLED_ENV] = "false"
def _same_path(left: Path, right: Path) -> bool:
try:
return left.resolve() == right.resolve()
except OSError:
return left == right
def _defines_key(text: str, key: str) -> bool:
for line in text.splitlines():
if line.lstrip().startswith("#"):
continue
match = _DOTENV_ASSIGNMENT_RE.match(line)
if match is not None and match.group("key") == key:
return True
return False
def _mapped_value(value: str, mapping: tuple[tuple[str, str], ...]) -> str:
line = value.rstrip("\r\n")
newline = value[len(line) :]
raw_value, separator, comment = line.partition("#")
normalized = raw_value.strip().strip("'\"").lower()
replacement = dict(mapping).get(normalized)
if replacement is None:
return value
suffix = f" #{comment}" if separator else ""
return f"{replacement}{suffix}{newline}"
def _mapped_prefix_value(value: str, old_prefix: str, new_prefix: str) -> str:
pattern = rf"^(?P<leading>\s*['\"]?){re.escape(old_prefix)}"
return re.sub(
pattern,
lambda match: f"{match.group('leading')}{new_prefix}",
value,
count=1,
)