@ant.sh/colony 0.1.0

package/src/parser.js

@@ -0,0 +1,381 @@
+import JSON5 from "json5";
+
+const RX_DIMS = /^@dims\s+([^;]+);/;
+const RX_INCLUDE = /^@include\s+(.+);/;
+const RX_REQUIRE = /^@require\s+([^;]+);/;
+const RX_ENVDEFAULTS = /^@envDefaults\s+([^;]+);/;
+
+// Rule: <scoped.key.path> <op> <value>;
+// Using [\s\S] instead of . to match newlines in multi-line values
+const RX_RULE = /^(.+?)\s*(\:=|\|\=|\+\=|\-\=|\=)\s*([\s\S]+)\s*;$/;
+
+// Heredoc: <<EOF ... EOF
+const RX_HEREDOC_START = /<<([A-Z_][A-Z0-9_]*)\s*$/;
+
+/**
+ * Remove block comments from text (slash-star to star-slash)
+ * @param {string} text
+ * @returns {{ text: string, lineMap: number[] }} - cleaned text and mapping from new line numbers to original
+ */
+function stripBlockComments(text) {
+  const result = [];
+  const lineMap = []; // lineMap[newLineNo] = originalLineNo
+  let inComment = false;
+  let commentDepth = 0;
+  const lines = text.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const originalLineNo = i + 1;
+    let line = lines[i];
+    let cleanLine = "";
+    let j = 0;
+
+    while (j < line.length) {
+      if (!inComment) {
+        // Check for comment start
+        if (line[j] === "/" && line[j + 1] === "*") {
+          inComment = true;
+          commentDepth = 1;
+          j += 2;
+          continue;
+        }
+        cleanLine += line[j];
+        j++;
+      } else {
+        // Inside block comment
+        if (line[j] === "/" && line[j + 1] === "*") {
+          commentDepth++;
+          j += 2;
+        } else if (line[j] === "*" && line[j + 1] === "/") {
+          commentDepth--;
+          if (commentDepth === 0) {
+            inComment = false;
+          }
+          j += 2;
+        } else {
+          j++;
+        }
+      }
+    }
+
+    result.push(cleanLine);
+    lineMap.push(originalLineNo);
+  }
+
+  return { text: result.join("\n"), lineMap };
+}
+
+/**
+ * Parse a key path with escaped dots
+ * "foo\.bar.baz" => ["foo.bar", "baz"]
+ * @param {string} keyRaw
+ * @returns {string[]}
+ */
+function parseKeyPath(keyRaw) {
+  const segments = [];
+  let current = "";
+  let i = 0;
+
+  while (i < keyRaw.length) {
+    if (keyRaw[i] === "\\" && keyRaw[i + 1] === ".") {
+      // Escaped dot - include literal dot
+      current += ".";
+      i += 2;
+    } else if (keyRaw[i] === ".") {
+      // Segment separator
+      if (current.trim()) segments.push(current.trim());
+      current = "";
+      i++;
+    } else {
+      current += keyRaw[i];
+      i++;
+    }
+  }
+
+  if (current.trim()) segments.push(current.trim());
+  return segments;
+}
+
+/**
+ * Format a parse error with line context and caret
+ * @param {string} message
+ * @param {string[]} lines
+ * @param {number} lineNo - 1-indexed line number
+ * @param {number=} col - 0-indexed column (optional)
+ * @param {string} filePath
+ * @returns {string}
+ */
+function formatParseError(message, lines, lineNo, col, filePath) {
+  const idx = lineNo - 1;
+  const contextLines = [];
+
+  // Show up to 2 lines before
+  for (let i = Math.max(0, idx - 2); i < idx; i++) {
+    contextLines.push(`  ${String(i + 1).padStart(4)} | ${lines[i]}`);
+  }
+
+  // Show the error line
+  if (idx >= 0 && idx < lines.length) {
+    contextLines.push(`> ${String(lineNo).padStart(4)} | ${lines[idx]}`);
+
+    // Show caret if column is specified
+    if (typeof col === "number" && col >= 0) {
+      const padding = " ".repeat(col + 9); // account for "> XXXX | "
+      contextLines.push(`${padding}^`);
+    }
+  }
+
+  // Show up to 1 line after
+  if (idx + 1 < lines.length) {
+    contextLines.push(`  ${String(idx + 2).padStart(4)} | ${lines[idx + 1]}`);
+  }
+
+  return `${filePath}:${lineNo}: ${message}\n\n${contextLines.join("\n")}`;
+}
+
+export function parseColony(text, { filePath = "<memory>", parseOnlyDirectives = false } = {}) {
+  // Strip block comments first, keeping track of original line numbers
+  const { text: cleanedText, lineMap } = stripBlockComments(text);
+  const lines = cleanedText.split(/\r?\n/);
+  const originalLines = text.split(/\r?\n/);
+
+  const rules = [];
+  const includes = [];
+  const requires = [];
+  const envDefaults = {};
+  let dims = null;
+
+  let buf = "";
+  let bufStartLine = 0;
+  let bufStartOriginalLine = 0;
+
+  // Heredoc state
+  let inHeredoc = false;
+  let heredocDelimiter = "";
+  let heredocContent = "";
+  let heredocStartLine = 0;
+  let heredocKey = "";
+  let heredocOp = "";
+
+  const getOriginalLine = (lineNo) => lineMap[lineNo - 1] || lineNo;
+
+  const flush = () => {
+    const raw = buf.trim();
+    buf = "";
+    if (!raw) return;
+
+    const origLine = bufStartOriginalLine;
+
+    const mDims = raw.match(RX_DIMS);
+    if (mDims) {
+      dims = mDims[1].split(",").map((s) => s.trim()).filter(Boolean);
+      return;
+    }
+
+    const mInc = raw.match(RX_INCLUDE);
+    if (mInc) {
+      includes.push(stripQuotes(mInc[1].trim()));
+      return;
+    }
+
+    const mReq = raw.match(RX_REQUIRE);
+    if (mReq) {
+      const keys = mReq[1]
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      requires.push(...keys);
+      return;
+    }
+
+    const mEnvDef = raw.match(RX_ENVDEFAULTS);
+    if (mEnvDef) {
+      const parts = mEnvDef[1]
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+
+      for (const p of parts) {
+        const idx = p.indexOf("=");
+        if (idx === -1) {
+          throw new Error(formatParseError(
+            `Bad @envDefaults entry: ${p}`,
+            originalLines,
+            origLine,
+            undefined,
+            filePath
+          ));
+        }
+        const k = p.slice(0, idx).trim();
+        const vRaw = p.slice(idx + 1).trim();
+        envDefaults[k] = stripQuotes(vRaw);
+      }
+      return;
+    }
+
+    if (parseOnlyDirectives) return;
+
+    const mRule = raw.match(RX_RULE);
+    if (!mRule) {
+      throw new Error(formatParseError(
+        "Invalid statement",
+        originalLines,
+        origLine,
+        undefined,
+        filePath
+      ));
+    }
+
+    const keyRaw = mRule[1].trim();
+    const op = mRule[2];
+    const valueRaw = mRule[3].trim();
+
+    const keySegments = parseKeyPath(keyRaw);
+    if (keySegments.length === 0) {
+      throw new Error(formatParseError(
+        "Empty key",
+        originalLines,
+        origLine,
+        0,
+        filePath
+      ));
+    }
+
+    const value = parseValue(valueRaw, { filePath, line: origLine, lines: originalLines });
+
+    rules.push({
+      filePath,
+      line: origLine,
+      col: 0,
+      keyRaw,
+      keySegments,
+      op,
+      value,
+    });
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNo = i + 1;
+    const originalLineNo = getOriginalLine(lineNo);
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Handle heredoc mode
+    if (inHeredoc) {
+      if (trimmed === heredocDelimiter) {
+        // End of heredoc
+        const keySegments = parseKeyPath(heredocKey);
+        if (keySegments.length === 0) {
+          throw new Error(formatParseError(
+            "Empty key in heredoc",
+            originalLines,
+            heredocStartLine,
+            0,
+            filePath
+          ));
+        }
+
+        rules.push({
+          filePath,
+          line: heredocStartLine,
+          col: 0,
+          keyRaw: heredocKey,
+          keySegments,
+          op: heredocOp,
+          value: heredocContent,
+        });
+
+        inHeredoc = false;
+        heredocContent = "";
+        continue;
+      }
+
+      // Add line to heredoc content
+      heredocContent += (heredocContent ? "\n" : "") + line;
+      continue;
+    }
+
+    // Skip empty lines and line comments
+    if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("//")) continue;
+
+    // Check for heredoc start: key = <<EOF
+    const heredocMatch = trimmed.match(/^(.+?)\s*(\:=|\|\=|\+\=|\-\=|\=)\s*<<([A-Z_][A-Z0-9_]*)$/);
+    if (heredocMatch) {
+      inHeredoc = true;
+      heredocKey = heredocMatch[1].trim();
+      heredocOp = heredocMatch[2];
+      heredocDelimiter = heredocMatch[3];
+      heredocStartLine = originalLineNo;
+      heredocContent = "";
+      continue;
+    }
+
+    if (!buf) {
+      bufStartLine = lineNo;
+      bufStartOriginalLine = originalLineNo;
+    }
+    buf += (buf ? "\n" : "") + line;
+
+    if (trimmed.endsWith(";")) flush();
+  }
+
+  if (inHeredoc) {
+    throw new Error(formatParseError(
+      `Unterminated heredoc (missing ${heredocDelimiter})`,
+      originalLines,
+      heredocStartLine,
+      undefined,
+      filePath
+    ));
+  }
+
+  if (buf.trim()) {
+    throw new Error(formatParseError(
+      "Unterminated statement (missing ';')",
+      originalLines,
+      bufStartOriginalLine,
+      undefined,
+      filePath
+    ));
+  }
+
+  return { dims, includes, requires, envDefaults, rules };
+}
+
+function parseValue(raw, { filePath, line, lines }) {
+  const r = raw.trim();
+
+  if (/^(true|false|null)$/.test(r)) return JSON5.parse(r);
+  if (/^-?\d+(\.\d+)?$/.test(r)) return Number(r);
+
+  const starts = r[0];
+  const ends = r[r.length - 1];
+  const looksJsonish =
+    (starts === "{" && ends === "}") ||
+    (starts === "[" && ends === "]") ||
+    (starts === `"` && ends === `"`) ||
+    (starts === `'` && ends === `'`);
+
+  if (looksJsonish) {
+    try {
+      return JSON5.parse(r);
+    } catch (e) {
+      throw new Error(formatParseError(
+        `Bad JSON5 value: ${e.message}`,
+        lines,
+        line,
+        undefined,
+        filePath
+      ));
+    }
+  }
+
+  return r; // bareword => string
+}
+
+function stripQuotes(s) {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}

package/src/providers/aws.js

@@ -0,0 +1,112 @@
+/**
+ * AWS Secrets Manager provider for colony
+ */
+
+/**
+ * @class AwsSecretsProvider
+ * @property {string} prefix - Provider prefix ("AWS")
+ */
+export class AwsSecretsProvider {
+  prefix = "AWS";
+
+  /**
+   * @param {object} options
+   * @param {string=} options.region - AWS region (default: process.env.AWS_REGION or "us-east-1")
+   */
+  constructor(options = {}) {
+    this.region = options.region ?? process.env.AWS_REGION ?? "us-east-1";
+    this.client = null;
+    this.clientPromise = null;
+    this.GetSecretValueCommand = null;
+  }
+
+  /**
+   * Get or create the AWS client (lazy initialization)
+   * @returns {Promise<object>}
+   */
+  async getClient() {
+    if (this.client) return this.client;
+    if (this.clientPromise) return this.clientPromise;
+
+    this.clientPromise = (async () => {
+      // Dynamic import to avoid requiring AWS SDK if not used
+      const { SecretsManagerClient, GetSecretValueCommand } = await import(
+        "@aws-sdk/client-secrets-manager"
+      );
+      this.client = new SecretsManagerClient({ region: this.region });
+      this.GetSecretValueCommand = GetSecretValueCommand;
+      return this.client;
+    })();
+
+    return this.clientPromise;
+  }
+
+  /**
+   * Fetch a secret value
+   * @param {string} key - Secret key, optionally with JSON path: "secret-name#json.path"
+   * @returns {Promise<string>}
+   */
+  async fetch(key) {
+    const client = await this.getClient();
+
+    // Support key with JSON path: secret-name#json.path
+    const [secretId, jsonPath] = key.split("#");
+
+    const command = new this.GetSecretValueCommand({ SecretId: secretId });
+    const response = await client.send(command);
+
+    let value = response.SecretString;
+    if (!value && response.SecretBinary) {
+      value = Buffer.from(response.SecretBinary).toString("utf-8");
+    }
+
+    // Extract JSON path if specified
+    if (jsonPath && value) {
+      try {
+        const parsed = JSON.parse(value);
+        value = getJsonPath(parsed, jsonPath);
+      } catch {
+        // Not JSON or invalid path, return as-is
+      }
+    }
+
+    return value ?? "";
+  }
+
+  /**
+   * Validate provider configuration
+   * @returns {Promise<void>}
+   */
+  async validate() {
+    // Try to initialize client to verify SDK is available
+    await this.getClient();
+  }
+
+  /**
+   * Cleanup resources
+   * @returns {Promise<void>}
+   */
+  async dispose() {
+    if (this.client?.destroy) {
+      this.client.destroy();
+    }
+    this.client = null;
+    this.clientPromise = null;
+  }
+}
+
+/**
+ * Get a value from an object using dot notation path
+ * @param {object} obj - Object to traverse
+ * @param {string} path - Dot-separated path (e.g., "database.password")
+ * @returns {string|undefined}
+ */
+function getJsonPath(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    current = current[part];
+  }
+  return typeof current === "string" ? current : JSON.stringify(current);
+}

package/src/providers/openbao.js

@@ -0,0 +1,32 @@
+/**
+ * OpenBao provider for colony
+ * OpenBao is an API-compatible fork of HashiCorp Vault
+ */
+
+import { VaultCompatibleProvider } from "./vault-base.js";
+
+/**
+ * @class OpenBaoProvider
+ * @property {string} prefix - Provider prefix ("OPENBAO")
+ */
+export class OpenBaoProvider extends VaultCompatibleProvider {
+  /**
+   * @param {object} options
+   * @param {string=} options.addr - OpenBao address (default: process.env.BAO_ADDR or "http://127.0.0.1:8200")
+   * @param {string=} options.token - OpenBao token (default: process.env.BAO_TOKEN)
+   * @param {string=} options.namespace - OpenBao namespace (default: process.env.BAO_NAMESPACE)
+   * @param {number=} options.timeout - Request timeout in ms (default: 30000)
+   */
+  constructor(options = {}) {
+    super(
+      {
+        prefix: "OPENBAO",
+        addrEnvVar: "BAO_ADDR",
+        tokenEnvVar: "BAO_TOKEN",
+        namespaceEnvVar: "BAO_NAMESPACE",
+        errorPrefix: "OpenBao",
+      },
+      options
+    );
+  }
+}

package/src/providers/vault-base.js

@@ -0,0 +1,92 @@
+/**
+ * Base class for Vault-compatible secret providers (Vault, OpenBao)
+ * Both use the same HTTP API, differing only in environment variables and naming.
+ */
+
+/**
+ * @class VaultCompatibleProvider
+ * @property {string} prefix - Provider prefix
+ */
+export class VaultCompatibleProvider {
+  /**
+   * @param {object} config
+   * @param {string} config.prefix - Provider prefix (e.g., "VAULT", "OPENBAO")
+   * @param {string} config.addrEnvVar - Environment variable for address
+   * @param {string} config.tokenEnvVar - Environment variable for token
+   * @param {string} config.namespaceEnvVar - Environment variable for namespace
+   * @param {string} config.errorPrefix - Prefix for error messages
+   * @param {object} options - User options
+   * @param {string=} options.addr - Server address
+   * @param {string=} options.token - Auth token
+   * @param {string=} options.namespace - Namespace
+   * @param {number=} options.timeout - Request timeout in ms (default: 30000)
+   */
+  constructor(config, options = {}) {
+    this.prefix = config.prefix;
+    this.errorPrefix = config.errorPrefix;
+    this.addr = options.addr ?? process.env[config.addrEnvVar] ?? "http://127.0.0.1:8200";
+    this.token = options.token ?? process.env[config.tokenEnvVar];
+    this.namespace = options.namespace ?? process.env[config.namespaceEnvVar];
+    this.timeout = options.timeout ?? 30000;
+    this.tokenEnvVar = config.tokenEnvVar;
+  }
+
+  /**
+   * Fetch a secret value
+   * @param {string} key - Secret path, optionally with field: "secret/data/myapp#password"
+   * @returns {Promise<string>}
+   */
+  async fetch(key) {
+    const [path, field] = key.split("#");
+
+    const url = `${this.addr}/v1/${path}`;
+    const headers = {
+      "X-Vault-Token": this.token,
+    };
+    if (this.namespace) {
+      headers["X-Vault-Namespace"] = this.namespace;
+    }
+
+    const response = await fetch(url, {
+      headers,
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (response.status === 404) {
+      const err = new Error(`Secret not found: ${key}`);
+      err.code = "NOT_FOUND";
+      throw err;
+    }
+
+    if (!response.ok) {
+      throw new Error(`${this.errorPrefix} error: ${response.status} ${response.statusText}`);
+    }
+
+    const data = await response.json();
+
+    // KV v2 returns data.data.data, KV v1 returns data.data
+    const secretData = data.data?.data ?? data.data;
+
+    if (field) {
+      return String(secretData?.[field] ?? "");
+    }
+
+    if (typeof secretData === "object" && secretData !== null) {
+      const values = Object.values(secretData);
+      if (values.length === 1) return String(values[0]);
+      return JSON.stringify(secretData);
+    }
+
+    return String(secretData ?? "");
+  }
+
+  /**
+   * Validate provider configuration
+   * @returns {Promise<void>}
+   */
+  async validate() {
+    if (!this.token) {
+      throw new Error(`${this.tokenEnvVar} is required`);
+    }
+  }
+}

package/src/providers/vault.js

@@ -0,0 +1,31 @@
+/**
+ * HashiCorp Vault provider for colony
+ */
+
+import { VaultCompatibleProvider } from "./vault-base.js";
+
+/**
+ * @class VaultProvider
+ * @property {string} prefix - Provider prefix ("VAULT")
+ */
+export class VaultProvider extends VaultCompatibleProvider {
+  /**
+   * @param {object} options
+   * @param {string=} options.addr - Vault address (default: process.env.VAULT_ADDR or "http://127.0.0.1:8200")
+   * @param {string=} options.token - Vault token (default: process.env.VAULT_TOKEN)
+   * @param {string=} options.namespace - Vault namespace (default: process.env.VAULT_NAMESPACE)
+   * @param {number=} options.timeout - Request timeout in ms (default: 30000)
+   */
+  constructor(options = {}) {
+    super(
+      {
+        prefix: "VAULT",
+        addrEnvVar: "VAULT_ADDR",
+        tokenEnvVar: "VAULT_TOKEN",
+        namespaceEnvVar: "VAULT_NAMESPACE",
+        errorPrefix: "Vault",
+      },
+      options
+    );
+  }
+}