Configuration & Environment Bootstrap

Configuration Model Overview

• .xtraqconfig – version-controlled JSON that captures non-sensitive defaults (for example target framework or schema allow-list) and records the resolved namespace/output folder. Every clone reads this file so the entire team works from the same baseline.
• .xtraqconfig.local – optional untracked overlay for machine- or environment-specific defaults. Uses the same schema as .xtraqconfig, lives beside it, and is ignored by Git by default.
• .env – private developer file used strictly for the generator connection string and logging/diagnostic toggles. It stays out of source control and should remain minimal.
• ProjectEnvironmentBootstrapper – helper that scaffolds a minimal .env, derives .xtraqconfig from CLI inputs, and updates both without clobbering intentional values.

Generated output is disposable

• Xtraq/ is regenerated on every xtraq build. Do not place handwritten code or configuration files there because the folder may be deleted or overwritten at any time.
• .xtraq/ stores snapshots, cache entries, and optional telemetry. Treat it as an ephemeral working directory and keep custom assets elsewhere.
• Keep custom extensions in your own projects or packages and reference the generated output instead of editing it in place.

Resolution Order

1. CLI arguments (for example xtraq build --output Generated)
2. Process environment variables (only secrets/logging toggles such as XTRAQ_GENERATOR_DB, XTRAQ_LOG_LEVEL, XTRAQ_VERBOSE, etc.)
3. .xtraqconfig.local (optional overlay for machine-local defaults)
4. .xtraqconfig (canonical team defaults)
5. Built-in defaults baked into the CLI

.env simply seeds the process environment with the few allowed secrets and logging flags listed above. Configuration values such as namespaces, schema filters, target frameworks, API toggles, and EF integration settings now come exclusively from .xtraqconfig / .xtraqconfig.local or explicit CLI switches.

Editing .xtraqconfig

xtraq init writes .xtraqconfig automatically, but you can edit it directly to capture project-wide changes. The CLI always persists the Namespace because downstream generators treat it as mandatory; if you omit --namespace, init resolves the value from the nearest .csproj and falls back to the directory name when that fails. Other properties remain optional—OutputDir still defaults to Xtraq, and arrays such as BuildSchemas can be skipped entirely. Even when every other value relies on defaults, the file keeps the $schema reference together with the resolved Namespace so future commands remain deterministic.

{
  "Namespace": "Contoso.Billing",
  "OutputDir": "Xtraq",
  "TargetFramework": "net8.0",
  "BuildSchemas": ["core", "identity"]
}

These properties are now sourced exclusively from .xtraqconfig / .xtraqconfig.local or explicit CLI switches—the runtime no longer mirrors them into environment variables or auxiliary payloads.

Recommendations:

• Commit .xtraqconfig with every intentional change so teammates receive the same defaults.
• Prefer arrays for BuildSchemas even when only one schema is included; the bootstrapper preserves ordering and removes duplicates.
• When experimenting, edit .xtraqconfig, run xtraq build, review the diff, and commit the configuration and generated artefacts together.

.xtraqconfig Standard Payload

When the file stores configuration directly, the tracked JSON exposes only non-sensitive knobs. Secrets such as XTRAQ_GENERATOR_DB are never written to .xtraqconfig; they stay exclusively in .env or external secrets stores. Environment overrides for configuration (for example XTRAQ_NAMESPACE, XTRAQ_BUILD_SCHEMAS) were removed—edit the JSON directly or use CLI switches instead.

Schema & IntelliSense

Editors that support JSON Schema can surface completions for .xtraqconfig and .xtraqconfig.local. Reference the published schema to enable IntelliSense:

{
  "$schema": "https://nuetzliches.github.io/xtraq/xtraqconfig.schema.json"
}

You can also point to a local copy at docs/public/xtraqconfig.schema.json if you prefer offline validation.

The CLI adds the $schema reference automatically when writing .xtraqconfig; keep it if you want IDE completions to stay active.

.xtraqconfig.local (Optional Overlay)

Create .xtraqconfig.local alongside the tracked file when you need local defaults that should never be committed—common examples include alternative output folders, experimental namespace prefixes, or a reduced schema list while iterating. The loader merges the files by taking any value present in .xtraqconfig.local and falling back to .xtraqconfig when absent.

{
  "Namespace": "Contoso.Billing.Experimental",
  "OutputDir": "Xtraq.Local",
  "BuildSchemas": ["identity"]
}

• The file shares the exact schema with .xtraqconfig; copy only the keys you want to override locally.
• Git ignores the file automatically (ProjectEnvironmentBootstrapper.EnsureProjectGitignore writes a dedicated # Xtraq block containing .xtraqconfig.local).
• CI or other shared environments should continue to rely on .xtraqconfig; .xtraqconfig.local is explicitly for per-developer tweaks and should stay out of automation.

.xtraqconfig Redirect Mode (Optional)

If the file contains a ProjectPath property, xtraq treats it as a redirect. The value can be:

• "." to point at the same directory (used by xtraq init during bootstrap).
• A relative path to another directory that hosts the real .xtraqconfig and .env.
• An absolute path when the tracked configuration lives outside the repository.

In redirect mode all other properties in the file are ignored. Redirect chains up to ten levels are supported; circular references resolve to the last visited directory to avoid infinite loops. Redirects are mainly used to avoid generating artefacts in the execution directory—for example when .xtraqconfig lives under src/ while commands run from the repository root.

Required Keys

Logging Toggles Available in .env

Only diagnostic switches are allowed alongside XTRAQ_GENERATOR_DB. Use them sparingly and remove them when no longer needed.

Remove the entry after finishing the investigation so future runs fall back to the tracked defaults.

Process Environment Toggles (set outside .env)

Some operational switches remain environment-driven for CI or integration scenarios, but the .env loader no longer imports them. Configure these via your shell, CI variables, or launch profiles:

Minimal .env Responsibilities

The bootstrapper copies .env.example, but only a handful of keys are required for day-to-day work. Keep everything else commented unless you are actively testing a preview feature.

XTRAQ_GENERATOR_DB=Server=localhost;Database=AppDb;Trusted_Connection=True;TrustServerCertificate=True;
# Optional diagnostics
# XTRAQ_LOG_LEVEL=debug
# XTRAQ_VERBOSE=1

Bootstrap Workflow

Running xtraq init or invoking commands that require configuration triggers the bootstrapper:

1. Ensures a .env exists; if missing, offers to create a minimal file and copies comments from .env.example verbatim.
2. Applies CLI parameters (namespace, schemas, output directory) to the tracked configuration.
3. Writes or updates .xtraqconfig, carrying forward existing values to avoid accidental resets.
4. Prints a summary instructing you to review secrets before continuing.

Re-run xtraq init --force whenever template keys change upstream or you want to rebuild .env from scratch while preserving .xtraqconfig.

Maintenance Checklist

• When adjusting namespaces or output folders, update .xtraqconfig first, then regenerate artefacts.
• Keep .env.example aligned with the keys that the CLI understands; every documented key should include a sentence in this page.
• If CI needs different settings, adjust .xtraqconfig (or maintain a dedicated branch) instead of leaning on environment variables—only secrets and diagnostics remain environment-driven.

Security Guidelines

• Never commit secrets. If a credential slips into source control, rotate it immediately and force-push a scrubbed history when appropriate.
• Use least-privilege SQL accounts for generator operations.
• Document credential rotation in team runbooks and treat .env as disposable.

FAQ

Can .env live outside the repository?

Yes. Pass XTRAQ_CONFIG_PATH and XTRAQ_GENERATOR_DB as process environment variables in CI/CD or containerised environments. The CLI resolves relative hints against the working directory when needed.

How do I absorb new keys from the template?

Pull the latest changes, run xtraq init --force, review the resulting .env diff, and update this page if new keys are promoted to tracked configuration.

Validation Checklist

• .env exists in every project that runs the current CLI and contains at least XTRAQ_GENERATOR_DB (plus temporary logging toggles when required—never other configuration keys).
• CI and local scripts resolve secrets from environment variables or .env, while every deterministic setting flows through .xtraqconfig.
• .xtraqconfig changes are reviewed like code and committed alongside feature work so every clone shares the same defaults.