@ant.sh/colony 0.1.0

package/dist/esm/index.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Type definitions for colony
+ */
+
+export interface SandboxOptions {
+  /** Restrict @include paths to this directory */
+  basePath?: string;
+  /** Whitelist of allowed environment variables for ${ENV:*} (null = allow all) */
+  allowedEnvVars?: string[] | null;
+  /** Whitelist of allowed custom variables for ${VAR:*} (null = allow all) */
+  allowedVars?: string[] | null;
+  /** Maximum depth for nested includes (default: 50) */
+  maxIncludeDepth?: number;
+  /** Maximum file size in bytes for included files */
+  maxFileSize?: number;
+}
+
+/**
+ * Secret provider interface for custom integrations
+ */
+export interface SecretProvider {
+  /** Unique prefix for this provider (e.g., "AWS", "VAULT") */
+  readonly prefix: string;
+  /** Fetch a secret value by key/path */
+  fetch(key: string): Promise<string>;
+  /** Optional: validate configuration on registration */
+  validate?(): Promise<void>;
+  /** Optional: cleanup resources */
+  dispose?(): Promise<void>;
+}
+
+export interface SecretCacheOptions {
+  /** Enable caching (default: true) */
+  enabled?: boolean;
+  /** Cache TTL in milliseconds (default: 300000 = 5 minutes) */
+  ttl?: number;
+  /** Maximum number of cached secrets (default: 100) */
+  maxSize?: number;
+}
+
+export interface SecretsOptions {
+  /** Secret providers to use (e.g., AwsSecretsProvider) */
+  providers?: SecretProvider[];
+  /** Whitelist of allowed secret patterns (glob supported, null = allow all) */
+  allowedSecrets?: string[] | null;
+  /** Cache settings */
+  cache?: SecretCacheOptions;
+  /** Behavior when secret not found: 'empty' returns "", 'warn' adds warning, 'error' throws */
+  onNotFound?: "empty" | "warn" | "error";
+}
+
+export interface LoadColonyOptions {
+  /** Entry colony file path */
+  entry: string;
+  /** Dimension names (e.g., ["env", "realm", "region"]) */
+  dims?: string[];
+  /** Context values for scope matching */
+  ctx?: Record<string, string>;
+  /** Custom variables for ${VAR:*} interpolation */
+  vars?: Record<string, string>;
+  /** Schema validation hook (supports sync and async) */
+  schema?: (cfg: ColonyConfig) => ColonyConfig | Promise<ColonyConfig>;
+  /** Security sandbox options */
+  sandbox?: SandboxOptions;
+  /** Warn when skipping already-visited includes */
+  warnOnSkippedIncludes?: boolean;
+  /** Secrets provider options */
+  secrets?: SecretsOptions;
+}
+
+export interface Warning {
+  type:
+    | "blocked_env_var"
+    | "blocked_var"
+    | "unknown_var"
+    | "unknown_ctx"
+    | "unknown_interpolation"
+    | "skipped_include"
+    | "blocked_secret"
+    | "secret_not_found"
+    | "secret_fetch_error"
+    | "unknown_provider";
+  message: string;
+  var?: string;
+  file?: string;
+  pattern?: string;
+  /** Provider name (for secret warnings) */
+  provider?: string;
+  /** Secret key (for secret warnings) */
+  key?: string;
+}
+
+export interface TraceInfo {
+  /** Operator used (=, :=, |=, +=, -=) */
+  op: string;
+  /** Scope segments that matched */
+  scope: string[];
+  /** Specificity score (number of non-* segments) */
+  specificity: number;
+  /** File path where the rule was defined */
+  filePath: string;
+  /** Line number in the file */
+  line: number;
+  /** Column number in the file */
+  col: number;
+  /** Raw key from the rule */
+  keyRaw: string;
+  /** Source location string (filePath:line:col) */
+  source: string;
+}
+
+export interface DiffResult {
+  /** Keys present in other but not in this config */
+  added: string[];
+  /** Keys present in this config but not in other */
+  removed: string[];
+  /** Keys present in both but with different values */
+  changed: Array<{
+    key: string;
+    from: unknown;
+    to: unknown;
+  }>;
+}
+
+export interface ColonyConfig {
+  /** Get a value by dot-notation path */
+  get(path: string): unknown;
+  /** Get trace info for how a key was set */
+  explain(path: string): TraceInfo | null;
+  /** Serialize to plain object */
+  toJSON(): Record<string, unknown>;
+  /** List all leaf keys in dot notation */
+  keys(): string[];
+  /** Compare with another config */
+  diff(other: ColonyConfig | Record<string, unknown>): DiffResult;
+  /** Internal trace data */
+  readonly _trace: Map<string, TraceInfo>;
+  /** Warnings generated during resolution */
+  readonly _warnings: Warning[];
+  /** Allow indexing with any string key */
+  [key: string]: unknown;
+}
+
+export interface ValidationResult {
+  /** Whether all files are valid */
+  valid: boolean;
+  /** List of all files that were checked */
+  files: string[];
+  /** List of errors found */
+  errors: Array<{
+    file: string;
+    error: string;
+  }>;
+}
+
+export interface DiffColonyOptions extends Omit<LoadColonyOptions, "ctx"> {
+  /** First context to compare */
+  ctx1: Record<string, string>;
+  /** Second context to compare */
+  ctx2: Record<string, string>;
+}
+
+export interface DiffColonyResult {
+  /** Config resolved with ctx1 */
+  cfg1: ColonyConfig;
+  /** Config resolved with ctx2 */
+  cfg2: ColonyConfig;
+  /** Differences between the two configs */
+  diff: DiffResult;
+}
+
+/**
+ * Load and resolve a colony configuration file
+ */
+export function loadColony(options: LoadColonyOptions): Promise<ColonyConfig>;
+
+/**
+ * Validate syntax of colony files without resolving
+ */
+export function validateColony(entry: string): Promise<ValidationResult>;
+
+/**
+ * List all files that would be included (dry run)
+ */
+export function dryRunIncludes(entry: string): Promise<string[]>;
+
+/**
+ * Compare configs loaded with different contexts
+ */
+export function diffColony(options: DiffColonyOptions): Promise<DiffColonyResult>;
+
+export interface LintIssue {
+  /** Type of issue found */
+  type: "parse_error" | "shadowed_rule" | "overridden_wildcard" | "empty_include";
+  /** Severity level */
+  severity: "error" | "warning" | "info";
+  /** Human-readable message */
+  message: string;
+  /** File where the issue was found */
+  file?: string;
+  /** Line number in the file */
+  line?: number;
+}
+
+export interface LintColonyOptions {
+  /** Entry colony file path */
+  entry: string;
+  /** Dimension names (e.g., ["env", "realm", "region"]) */
+  dims?: string[];
+}
+
+export interface LintColonyResult {
+  /** List of issues found */
+  issues: LintIssue[];
+}
+
+/**
+ * Lint colony files for potential issues
+ */
+export function lintColony(options: LintColonyOptions): Promise<LintColonyResult>;
+
+// ============================================================================
+// Secrets Management
+// ============================================================================
+
+/**
+ * Register a secret provider globally (available to all loadColony calls)
+ */
+export function registerSecretProvider(provider: SecretProvider): void;
+
+/**
+ * Unregister a secret provider by prefix
+ */
+export function unregisterSecretProvider(prefix: string): boolean;
+
+/**
+ * Clear all globally registered secret providers
+ */
+export function clearSecretProviders(): void;
+
+/**
+ * AWS Secrets Manager provider
+ *
+ * @example
+ * ```ts
+ * import { loadColony, AwsSecretsProvider } from "@ant.sh/colony";
+ *
+ * const cfg = await loadColony({
+ *   entry: "./config/app.colony",
+ *   secrets: {
+ *     providers: [new AwsSecretsProvider({ region: "us-east-1" })],
+ *   },
+ * });
+ * ```
+ *
+ * Config usage:
+ * ```
+ * *.db.password = "${AWS:myapp/db#password}";
+ * ```
+ */
+export class AwsSecretsProvider implements SecretProvider {
+  readonly prefix: "AWS";
+
+  /**
+   * @param options.region - AWS region (default: process.env.AWS_REGION or "us-east-1")
+   */
+  constructor(options?: { region?: string });
+
+  fetch(key: string): Promise<string>;
+  validate(): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+/**
+ * HashiCorp Vault provider
+ *
+ * @example
+ * ```ts
+ * import { loadColony, VaultProvider } from "@ant.sh/colony";
+ *
+ * const cfg = await loadColony({
+ *   entry: "./config/app.colony",
+ *   secrets: {
+ *     providers: [new VaultProvider({ addr: "https://vault.example.com" })],
+ *   },
+ * });
+ * ```
+ *
+ * Config usage:
+ * ```
+ * *.api.key = "${VAULT:secret/data/myapp#api_key}";
+ * ```
+ */
+export class VaultProvider implements SecretProvider {
+  readonly prefix: "VAULT";
+
+  /**
+   * @param options.addr - Vault address (default: process.env.VAULT_ADDR or "http://127.0.0.1:8200")
+   * @param options.token - Vault token (default: process.env.VAULT_TOKEN)
+   * @param options.namespace - Vault namespace (default: process.env.VAULT_NAMESPACE)
+   * @param options.timeout - Request timeout in ms (default: 30000)
+   */
+  constructor(options?: { addr?: string; token?: string; namespace?: string; timeout?: number });
+
+  fetch(key: string): Promise<string>;
+  validate(): Promise<void>;
+}
+
+/**
+ * OpenBao provider (API-compatible Vault fork)
+ *
+ * @example
+ * ```ts
+ * import { loadColony, OpenBaoProvider } from "@ant.sh/colony";
+ *
+ * const cfg = await loadColony({
+ *   entry: "./config/app.colony",
+ *   secrets: {
+ *     providers: [new OpenBaoProvider({ addr: "https://bao.example.com" })],
+ *   },
+ * });
+ * ```
+ *
+ * Config usage:
+ * ```
+ * *.api.key = "${OPENBAO:secret/data/myapp#api_key}";
+ * ```
+ */
+export class OpenBaoProvider implements SecretProvider {
+  readonly prefix: "OPENBAO";
+
+  /**
+   * @param options.addr - OpenBao address (default: process.env.BAO_ADDR or "http://127.0.0.1:8200")
+   * @param options.token - OpenBao token (default: process.env.BAO_TOKEN)
+   * @param options.namespace - OpenBao namespace (default: process.env.BAO_NAMESPACE)
+   * @param options.timeout - Request timeout in ms (default: 30000)
+   */
+  constructor(options?: { addr?: string; token?: string; namespace?: string; timeout?: number });
+
+  fetch(key: string): Promise<string>;
+  validate(): Promise<void>;
+}

package/dist/esm/index.js

@@ -0,0 +1,347 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+import { parseColony } from "./parser.js";
+import { resolveRules } from "./resolver.js";
+import {
+  applySecretsDeep,
+  SecretCache,
+  hasGlobalProviders,
+  registerSecretProvider,
+  unregisterSecretProvider,
+  clearSecretProviders
+} from "./secrets.js";
+import { AwsSecretsProvider } from "./providers/aws.js";
+import { VaultProvider } from "./providers/vault.js";
+import { OpenBaoProvider } from "./providers/openbao.js";
+async function loadColony(opts) {
+  const entry = opts?.entry;
+  if (!entry) throw new Error("loadColony: opts.entry is required");
+  const sandbox = opts.sandbox ?? {};
+  const basePath = sandbox.basePath ? path.resolve(sandbox.basePath) : null;
+  const maxIncludeDepth = sandbox.maxIncludeDepth ?? 50;
+  const maxFileSize = sandbox.maxFileSize ?? null;
+  const warnOnSkippedIncludes = opts.warnOnSkippedIncludes ?? false;
+  const visited = /* @__PURE__ */ new Set();
+  const warnings = [];
+  const files = await expandIncludes(entry, visited, {
+    basePath,
+    maxIncludeDepth,
+    maxFileSize,
+    warnOnSkippedIncludes,
+    warnings
+  });
+  const parsed = [];
+  for (const file of files) {
+    const text = await fs.readFile(file, "utf8");
+    parsed.push(parseColony(text, { filePath: file }));
+  }
+  const dims = (Array.isArray(opts.dims) && opts.dims.length ? opts.dims : null) ?? parsed.find((p) => p.dims?.length)?.dims ?? ["env"];
+  const envDefaults = mergeEnvDefaults(parsed.map((p) => p.envDefaults ?? {}));
+  const ctx = {
+    ...envDefaults,
+    env: process.env.NODE_ENV ?? "dev",
+    ...opts.ctx
+  };
+  const vars = { ROOT: process.cwd(), ...opts.vars ?? {} };
+  const requires = parsed.flatMap((p) => p.requires ?? []);
+  const allRules = parsed.flatMap((p) => p.rules);
+  const allowedEnvVars = sandbox.allowedEnvVars ?? null;
+  const allowedVars = sandbox.allowedVars ?? null;
+  let cfg = resolveRules({ rules: allRules, dims, ctx, vars, allowedEnvVars, allowedVars, warnings });
+  const secretsOpts = opts.secrets ?? {};
+  if (secretsOpts.providers?.length || hasGlobalProviders()) {
+    const cacheOpts = secretsOpts.cache ?? {};
+    const cache = cacheOpts.enabled !== false ? new SecretCache(cacheOpts.maxSize ?? 100) : null;
+    const secretified = await applySecretsDeep(cfg, {
+      providers: secretsOpts.providers ?? [],
+      allowedSecrets: secretsOpts.allowedSecrets ?? null,
+      cache,
+      cacheTtl: cacheOpts.ttl ?? 3e5,
+      onNotFound: secretsOpts.onNotFound ?? "warn",
+      warnings
+    });
+    copyConfigMethods(secretified, cfg, warnings);
+    cfg = secretified;
+  }
+  const missing = [];
+  for (const reqKey of requires) {
+    if (cfg.get(reqKey) === void 0) missing.push(reqKey);
+  }
+  if (missing.length) {
+    throw new Error(
+      `COLONY @require failed (missing keys):
+` + missing.map((k) => `  - ${k}`).join("\n")
+    );
+  }
+  Object.defineProperty(cfg, "_warnings", { enumerable: false, value: warnings });
+  if (typeof opts.schema === "function") {
+    const result = opts.schema(cfg);
+    if (result && typeof result.then === "function") {
+      const validated = await result;
+      if (validated && validated !== cfg) {
+        copyConfigMethods(validated, cfg, warnings);
+        return validated;
+      }
+    } else if (result && result !== cfg) {
+      copyConfigMethods(result, cfg, warnings);
+      return result;
+    }
+  }
+  return cfg;
+}
+function copyConfigMethods(target, source, warnings) {
+  Object.defineProperties(target, {
+    get: { enumerable: false, value: source.get },
+    explain: { enumerable: false, value: source.explain },
+    toJSON: { enumerable: false, value: source.toJSON },
+    keys: { enumerable: false, value: source.keys },
+    diff: { enumerable: false, value: source.diff },
+    _trace: { enumerable: false, value: source._trace },
+    _warnings: { enumerable: false, value: warnings }
+  });
+}
+function mergeEnvDefaults(list) {
+  const out = {};
+  for (const m of list) {
+    for (const [k, v] of Object.entries(m)) out[k] = v;
+  }
+  return out;
+}
+async function expandIncludes(entry, visited, { basePath, maxIncludeDepth, maxFileSize, warnOnSkippedIncludes, warnings }) {
+  const absEntry = path.resolve(entry);
+  const out = [];
+  await dfs(absEntry, 0);
+  return out;
+  async function dfs(file, depth) {
+    if (depth > maxIncludeDepth) {
+      throw new Error(`COLONY: Max include depth (${maxIncludeDepth}) exceeded at: ${file}`);
+    }
+    const abs = path.resolve(file);
+    if (visited.has(abs)) {
+      if (warnOnSkippedIncludes) {
+        warnings.push({ type: "skipped_include", file: abs, message: `Skipping already-visited include: ${abs}` });
+      }
+      return;
+    }
+    visited.add(abs);
+    if (maxFileSize !== null) {
+      const stat = await fs.stat(abs);
+      if (stat.size > maxFileSize) {
+        throw new Error(`COLONY: File size (${stat.size} bytes) exceeds maxFileSize (${maxFileSize} bytes): ${abs}`);
+      }
+    }
+    const text = await fs.readFile(abs, "utf8");
+    const { includes } = parseColony(text, { filePath: abs, parseOnlyDirectives: true });
+    for (const inc of includes) {
+      const incAbs = path.resolve(path.dirname(abs), inc);
+      if (basePath !== null) {
+        const normalizedInc = path.normalize(incAbs);
+        if (!normalizedInc.startsWith(basePath + path.sep) && normalizedInc !== basePath) {
+          throw new Error(
+            `COLONY: Path traversal blocked. Include "${inc}" resolves to "${normalizedInc}" which is outside basePath "${basePath}"`
+          );
+        }
+      }
+      const matches = await fg(incAbs.replace(/\\/g, "/"), { dot: true });
+      for (const m of matches.sort((a, b) => a.localeCompare(b))) {
+        if (basePath !== null) {
+          const normalizedMatch = path.normalize(m);
+          if (!normalizedMatch.startsWith(basePath + path.sep) && normalizedMatch !== basePath) {
+            throw new Error(
+              `COLONY: Path traversal blocked. Glob match "${m}" is outside basePath "${basePath}"`
+            );
+          }
+        }
+        await dfs(m, depth + 1);
+      }
+    }
+    out.push(abs);
+  }
+}
+async function validateColony(entry) {
+  const visited = /* @__PURE__ */ new Set();
+  const files = [];
+  const errors = [];
+  await validateDfs(path.resolve(entry));
+  return {
+    valid: errors.length === 0,
+    files,
+    errors
+  };
+  async function validateDfs(file) {
+    const abs = path.resolve(file);
+    if (visited.has(abs)) return;
+    visited.add(abs);
+    try {
+      const text = await fs.readFile(abs, "utf8");
+      const { includes } = parseColony(text, { filePath: abs });
+      files.push(abs);
+      for (const inc of includes) {
+        const incAbs = path.resolve(path.dirname(abs), inc);
+        const matches = await fg(incAbs.replace(/\\/g, "/"), { dot: true });
+        for (const m of matches.sort((a, b) => a.localeCompare(b))) {
+          await validateDfs(m);
+        }
+      }
+    } catch (e) {
+      errors.push({ file: abs, error: e.message });
+    }
+  }
+}
+async function dryRunIncludes(entry) {
+  const visited = /* @__PURE__ */ new Set();
+  const files = [];
+  await dryRunDfs(path.resolve(entry));
+  return files;
+  async function dryRunDfs(file) {
+    const abs = path.resolve(file);
+    if (visited.has(abs)) return;
+    visited.add(abs);
+    const text = await fs.readFile(abs, "utf8");
+    const { includes } = parseColony(text, { filePath: abs, parseOnlyDirectives: true });
+    for (const inc of includes) {
+      const incAbs = path.resolve(path.dirname(abs), inc);
+      const matches = await fg(incAbs.replace(/\\/g, "/"), { dot: true });
+      for (const m of matches.sort((a, b) => a.localeCompare(b))) {
+        await dryRunDfs(m);
+      }
+    }
+    files.push(abs);
+  }
+}
+async function diffColony(opts) {
+  const { ctx1, ctx2, ...baseOpts } = opts;
+  if (!ctx1 || !ctx2) {
+    throw new Error("diffColony: both ctx1 and ctx2 are required");
+  }
+  const cfg1 = await loadColony({ ...baseOpts, ctx: ctx1 });
+  const cfg2 = await loadColony({ ...baseOpts, ctx: ctx2 });
+  return {
+    cfg1,
+    cfg2,
+    diff: cfg1.diff(cfg2)
+  };
+}
+async function lintColony(opts) {
+  const entry = opts?.entry;
+  if (!entry) throw new Error("lintColony: opts.entry is required");
+  const issues = [];
+  const visited = /* @__PURE__ */ new Set();
+  const allRules = [];
+  const allFiles = [];
+  let foundDims = null;
+  await collectRules(path.resolve(entry));
+  async function collectRules(file) {
+    const abs = path.resolve(file);
+    if (visited.has(abs)) return;
+    visited.add(abs);
+    try {
+      const text = await fs.readFile(abs, "utf8");
+      const parsed = parseColony(text, { filePath: abs });
+      allFiles.push(abs);
+      if (!foundDims && parsed.dims?.length) {
+        foundDims = parsed.dims;
+      }
+      for (const rule of parsed.rules) {
+        allRules.push({ ...rule, filePath: abs });
+      }
+      for (const inc of parsed.includes) {
+        const incAbs = path.resolve(path.dirname(abs), inc);
+        const matches = await fg(incAbs.replace(/\\/g, "/"), { dot: true });
+        for (const m of matches.sort((a, b) => a.localeCompare(b))) {
+          await collectRules(m);
+        }
+      }
+    } catch (e) {
+      issues.push({
+        type: "parse_error",
+        severity: "error",
+        message: e.message,
+        file: abs
+      });
+    }
+  }
+  const dims = opts.dims ?? foundDims ?? ["env"];
+  const rulesByKey = /* @__PURE__ */ new Map();
+  for (const rule of allRules) {
+    const scope = rule.keySegments.slice(0, dims.length).join(".");
+    const keyPath = rule.keySegments.slice(dims.length).join(".");
+    const key = `${scope}|${keyPath}`;
+    if (!rulesByKey.has(key)) {
+      rulesByKey.set(key, []);
+    }
+    rulesByKey.get(key).push(rule);
+  }
+  for (const [key, rules] of rulesByKey.entries()) {
+    if (rules.length > 1) {
+      const locations = rules.map((r) => `${r.filePath}:${r.line}`);
+      const uniqueLocations = new Set(locations);
+      if (uniqueLocations.size > 1) {
+        const [scope, keyPath] = key.split("|");
+        issues.push({
+          type: "shadowed_rule",
+          severity: "warning",
+          message: `Rule "${scope}.${keyPath}" is defined ${rules.length} times. Later rule wins.`,
+          file: rules[rules.length - 1].filePath,
+          line: rules[rules.length - 1].line
+        });
+      }
+    }
+  }
+  for (const rule of allRules) {
+    const scope = rule.keySegments.slice(0, dims.length);
+    const keyPath = rule.keySegments.slice(dims.length).join(".");
+    if (scope.every((s) => s === "*")) {
+      const moreSpecific = allRules.filter((r) => {
+        const rKeyPath = r.keySegments.slice(dims.length).join(".");
+        if (rKeyPath !== keyPath) return false;
+        const rScope = r.keySegments.slice(0, dims.length);
+        return rScope.some((s) => s !== "*") && r !== rule;
+      });
+      if (moreSpecific.length > 0) {
+        issues.push({
+          type: "overridden_wildcard",
+          severity: "info",
+          message: `Wildcard rule for "${keyPath}" is overridden by ${moreSpecific.length} more specific rule(s)`,
+          file: rule.filePath,
+          line: rule.line
+        });
+      }
+    }
+  }
+  for (const file of allFiles) {
+    try {
+      const text = await fs.readFile(file, "utf8");
+      const parsed = parseColony(text, { filePath: file });
+      for (const inc of parsed.includes) {
+        const incAbs = path.resolve(path.dirname(file), inc);
+        const matches = await fg(incAbs.replace(/\\/g, "/"), { dot: true });
+        if (matches.length === 0) {
+          issues.push({
+            type: "empty_include",
+            severity: "warning",
+            message: `Include pattern "${inc}" matches no files`,
+            file
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  return { issues };
+}
+export {
+  AwsSecretsProvider,
+  OpenBaoProvider,
+  VaultProvider,
+  clearSecretProviders,
+  diffColony,
+  dryRunIncludes,
+  lintColony,
+  loadColony,
+  registerSecretProvider,
+  unregisterSecretProvider,
+  validateColony
+};
+//# sourceMappingURL=index.js.map