@axtary/config

YAML configuration loading for local Axtary runtime packages.

Early 0.x release: the runtime path is real and tested, but the API is not stable yet and may change between minor versions.

npm install @axtary/config

What It Does

• Parses axtary.yml text into a typed runtime config.
• Applies defaults for issuer, tenant, ledger path, runtime mode, adapters, and policy.
• Normalizes policy through @axtary/policy.
• Resolves ledger paths relative to the config file or current working directory.
• Emits a default config template for demos.
• Provides CachedConfigLoader for long-running local proxy sessions.

Adapter Config

GitHub defaults to fake mode:

adapters:
  github:
    mode: fake

To route allowed GitHub actions to the real REST API, set:

adapters:
  github:
    mode: rest
    tokenEnv: GITHUB_TOKEN
    apiBaseUrl: https://api.github.com
    userAgent: axtary-local-proxy

Slack and Linear follow the same fake-first pattern:

adapters:
  slack:
    mode: web
    tokenEnv: SLACK_BOT_TOKEN
    apiBaseUrl: https://slack.com/api
  linear:
    mode: graphql
    tokenEnv: LINEAR_API_KEY
    apiUrl: https://api.linear.app/graphql

The CLI reads tokens from the named environment variables. Keep fake mode for demos and tests.

Local docs are enabled by default and resolve roots relative to the config file:

adapters:
  docs:
    mode: local
    workspace: local
    roots:
      - docs
      - product
    maxSearchResults: 10
    maxReadBytes: 20000

Pair this with policy.docs.documents to scope allowed workspaces, readable path prefixes, denied prefixes, and per-action limits.

Runtime Latency Guard

runtime:
  handlerTimeoutMs: 10000

Handlers that exceed the timeout fail closed with proxy_handler_timeout:<ms>ms. Proxy responses include per-stage timings so local runs can track policy, signing, ledger, and adapter latency.

Cached Loading And Hot Reload

CachedConfigLoader caches parsed configs and checks the config file mtime on getConfig(). File-backed configs reload automatically when axtary.yml changes, which lets the local proxy pick up policy edits without a restart.

If a file-backed config disappears or becomes unreadable, the loader throws instead of silently serving stale policy. The proxy records that as a fail-closed policy-resolution denial.

Quickstart

This example runs as-is with Node 20+:

import { parseAxtaryConfigYaml, DEFAULT_AXTARY_CONFIG_YAML } from "@axtary/config";

// Parse and validate an axtary.yml (here: the scaffold `axtary init` writes).
const config = parseAxtaryConfigYaml(DEFAULT_AXTARY_CONFIG_YAML);
console.log(config.policy ? "policy loaded" : "no policy", Object.keys(config));

Design Notes

Config parsing is intentionally separate from the CLI so adapters, tests, and future MCP wrappers can all share the same file format.