docdex 0.1.11 → 0.2.2

package/lib/installer_logging.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+"use strict";
+
+const DEFAULT_COMPONENT = "docdex-installer";
+
+function parseBooleanEnv(value, defaultValue) {
+  if (value == null) return defaultValue;
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized) return defaultValue;
+  if (["1", "true", "yes", "y", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "n", "off"].includes(normalized)) return false;
+  return defaultValue;
+}
+
+function redactAuthHeader(value) {
+  if (typeof value !== "string") return value;
+  return value.replace(/\b(Bearer)\s+([^\s]+)/gi, "$1 [REDACTED]");
+}
+
+function shouldRedactKey(key) {
+  return /token|authorization|password|secret|signature|sig|credential|private[_-]?key|api[_-]?key/i.test(String(key));
+}
+
+function shouldRedactUrlParam(key) {
+  const k = String(key).toLowerCase();
+  if (k.startsWith("x-amz-")) return true;
+  return /token|access_token|auth|signature|sig|key|credential|session/i.test(k);
+}
+
+function redactUrl(url) {
+  if (typeof url !== "string") return url;
+  const value = url.trim();
+  if (!value) return value;
+
+  try {
+    const parsed = new URL(value);
+    parsed.username = "";
+    parsed.password = "";
+    for (const [k] of parsed.searchParams.entries()) {
+      if (shouldRedactUrlParam(k)) parsed.searchParams.set(k, "REDACTED");
+    }
+    return parsed.toString();
+  } catch {
+    // Best-effort redaction for non-URL strings.
+    return value
+      .replace(/\/\/([^/@:\s]+):([^/@\s]+)@/g, "//REDACTED:REDACTED@")
+      .replace(/([?&])(token|access_token|auth|signature|sig|key|credential)=([^&]+)/gi, "$1$2=REDACTED");
+  }
+}
+
+function redactValue(value, depth = 0) {
+  if (depth > 6) return "[REDACTED_DEPTH]";
+  if (value == null) return value;
+
+  if (typeof value === "string") {
+    const withRedactedUrls = value.replace(/https?:\/\/[^\s"'()<>]+/gi, (match) => redactUrl(match));
+    const maybeUrl = /^https?:\/\//i.test(withRedactedUrls) ? redactUrl(withRedactedUrls) : withRedactedUrls;
+    return redactAuthHeader(maybeUrl);
+  }
+
+  if (Array.isArray(value)) return value.map((v) => redactValue(v, depth + 1));
+
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (shouldRedactKey(k)) {
+        out[k] = "[REDACTED]";
+        continue;
+      }
+      if (/url$/i.test(k) || /_url$/i.test(k) || /url_/i.test(k) || /Url$/.test(k)) {
+        out[k] = redactUrl(typeof v === "string" ? v : String(v ?? ""));
+        continue;
+      }
+      out[k] = redactValue(v, depth + 1);
+    }
+    return out;
+  }
+
+  return value;
+}
+
+function safeJsonStringify(value) {
+  const seen = new WeakSet();
+  return JSON.stringify(value, (key, val) => {
+    if (val && typeof val === "object") {
+      if (seen.has(val)) return "[Circular]";
+      seen.add(val);
+    }
+    return val;
+  });
+}
+
+function createInstallerStructuredLogger({
+  component = DEFAULT_COMPONENT,
+  baseFields = {},
+  enabled = parseBooleanEnv(process.env.DOCDEX_INSTALLER_STRUCTURED_LOG, false),
+  sink = process.stderr
+} = {}) {
+  function emit({ level = "info", event, message, fields, error } = {}) {
+    if (!enabled) return;
+    const payload = {
+      ts: new Date().toISOString(),
+      level,
+      component,
+      event: typeof event === "string" ? event : "installer.event",
+      message: typeof message === "string" ? message : null,
+      ...redactValue(baseFields),
+      ...redactValue(fields || {})
+    };
+
+    if (error) {
+      payload.error = redactValue({
+        name: error?.name || null,
+        code: typeof error?.code === "string" ? error.code : null,
+        message: error?.message || String(error)
+      });
+    }
+
+    try {
+      sink.write(`${safeJsonStringify(payload)}\n`);
+    } catch {
+      // Best-effort: never fail install due to logging.
+    }
+  }
+
+  return { emit, enabled };
+}
+
+module.exports = {
+  createInstallerStructuredLogger,
+  parseBooleanEnv,
+  redactUrl,
+  redactValue
+};

package/lib/platform.js

@@ -1,48 +1,303 @@
 "use strict";
 
+const fs = require("node:fs");
+
+const {
+  PLATFORM_ENTRY_BY_KEY,
+  PUBLISHED_PLATFORM_KEYS,
+  PUBLISHED_TARGET_TRIPLES,
+  assetNameForPlatformKey
+} = require("./platform_matrix");
+
+class UnsupportedPlatformError extends Error {
+  /**
+   * @param {{
+   *   platform: string,
+   *   arch: string,
+   *   libc?: (null|"gnu"|"musl"),
+   *   candidatePlatformKey?: (string|null),
+   *   candidateTargetTriple?: (string|null),
+   *   reason?: (string|null),
+   *   supportedPlatformKeys: string[],
+   *   supportedTargetTriples: string[]
+   * }} options
+   */
+  constructor({
+    platform,
+    arch,
+    libc = null,
+    candidatePlatformKey = null,
+    candidateTargetTriple = null,
+    reason = null,
+    supportedPlatformKeys,
+    supportedTargetTriples
+  }) {
+    super(`Unsupported platform: ${platform}/${arch}`);
+    this.name = "UnsupportedPlatformError";
+    this.code = "DOCDEX_UNSUPPORTED_PLATFORM";
+    this.exitCode = 3;
+    this.details = {
+      targetTriple: null,
+      manifestVersion: null,
+      assetName: null,
+      platform,
+      arch,
+      libc,
+      candidatePlatformKey,
+      candidateTargetTriple,
+      reason,
+      supportedPlatformKeys: supportedPlatformKeys || [],
+      supportedTargetTriples: supportedTargetTriples || []
+    };
+  }
+}
+
+const SUPPORTED_PLATFORM_KEYS = PUBLISHED_PLATFORM_KEYS;
+const SUPPORTED_TARGET_TRIPLES = PUBLISHED_TARGET_TRIPLES;
+
+function normalizeLibc(value) {
+  if (value == null) return null;
+  const libc = String(value).toLowerCase().trim();
+  if (!libc) return null;
+  if (libc === "glibc") return "gnu";
+  if (libc === "musl" || libc === "gnu") return libc;
+  return null;
+}
+
+function readFileSliceSync(fsModule, filePath, offset, length) {
+  const fd = fsModule.openSync(filePath, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    const bytesRead = fsModule.readSync(fd, buf, 0, length, offset);
+    return bytesRead === length ? buf : buf.subarray(0, bytesRead);
+  } finally {
+    fsModule.closeSync(fd);
+  }
+}
+
+function detectLibcFromElfInterpreter(execPath, fsModule) {
+  if (!execPath || typeof execPath !== "string") return null;
+  try {
+    const header = readFileSliceSync(fsModule, execPath, 0, 64);
+    if (header.length < 64) return null;
+    if (header[0] !== 0x7f || header[1] !== 0x45 || header[2] !== 0x4c || header[3] !== 0x46) return null;
+
+    const eiClass = header[4]; // 1=32-bit, 2=64-bit
+    const eiData = header[5]; // 1=little-endian
+    if (eiData !== 1) return null;
+
+    const PT_INTERP = 3;
+
+    let phoff;
+    let phentsize;
+    let phnum;
+
+    if (eiClass === 2) {
+      phoff = Number(header.readBigUInt64LE(32));
+      phentsize = header.readUInt16LE(54);
+      phnum = header.readUInt16LE(56);
+    } else if (eiClass === 1) {
+      phoff = header.readUInt32LE(28);
+      phentsize = header.readUInt16LE(42);
+      phnum = header.readUInt16LE(44);
+    } else {
+      return null;
+    }
+
+    if (!phoff || !phentsize || !phnum) return null;
+    if (phnum > 64) return null;
+    if (phentsize < 32 || phentsize > 128) return null;
+
+    const tableSize = phentsize * phnum;
+    const phTable = readFileSliceSync(fsModule, execPath, phoff, tableSize);
+    if (phTable.length < tableSize) return null;
+
+    for (let i = 0; i < phnum; i++) {
+      const base = i * phentsize;
+      const pType = phTable.readUInt32LE(base);
+      if (pType !== PT_INTERP) continue;
+
+      let pOffset;
+      let pFileSz;
+
+      if (eiClass === 2) {
+        pOffset = Number(phTable.readBigUInt64LE(base + 8));
+        pFileSz = Number(phTable.readBigUInt64LE(base + 32));
+      } else {
+        pOffset = phTable.readUInt32LE(base + 4);
+        pFileSz = phTable.readUInt32LE(base + 16);
+      }
+
+      if (!pOffset || !pFileSz || pFileSz > 4096) return null;
+      const interpBytes = readFileSliceSync(fsModule, execPath, pOffset, pFileSz);
+      const interp = interpBytes.toString("utf8").split("\0")[0];
+      if (!interp) return null;
+      if (interp.includes("ld-musl")) return "musl";
+      if (interp.includes("ld-linux")) return "gnu";
+      return null;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
 function detectLibc() {
-  const override = process.env.DOCDEX_LIBC;
-  if (override) {
-    const libc = override.toLowerCase();
-    if (libc === "musl" || libc === "gnu") {
-      return libc;
+  return detectLibcFromRuntime();
+}
+
+function detectLibcFromRuntime(options) {
+  const env = options?.env ?? process.env;
+  const fsModule = options?.fs ?? fs;
+
+  const overrideRaw = env?.DOCDEX_LIBC;
+  if (overrideRaw != null && String(overrideRaw).trim() !== "") {
+    const override = normalizeLibc(overrideRaw);
+    if (!override) {
+      throw new Error(`Invalid DOCDEX_LIBC=${overrideRaw}; expected "gnu", "musl", or "glibc"`);
     }
+    return override;
   }
 
-  const report = typeof process.report?.getReport === "function" ? process.report.getReport() : null;
+  const report =
+    options?.report ??
+    (typeof process.report?.getReport === "function" ? process.report.getReport() : null);
+
   const glibcVersion = report?.header?.glibcVersionRuntime;
-  return glibcVersion ? "gnu" : "musl";
+  if (typeof glibcVersion === "string" && glibcVersion.trim()) return "gnu";
+
+  // Some Node builds include a `musl` field in the report header. Treat it as a positive signal.
+  if (report?.header?.musl != null) return "musl";
+
+  // Alpine is musl-based by default; use it as a strong hint.
+  try {
+    if (typeof fsModule.existsSync === "function" && fsModule.existsSync("/etc/alpine-release")) return "musl";
+  } catch {}
+
+  const execPath = options?.execPath ?? process.execPath;
+  const fromElf = detectLibcFromElfInterpreter(execPath, fsModule);
+  if (fromElf) return fromElf;
+
+  // Deterministic fallback: musl binaries are typically more portable on glibc than the reverse.
+  return "musl";
 }
 
-function detectPlatformKey() {
-  const platform = process.platform;
-  const arch = process.arch;
+function detectPlatformKey(options) {
+  const platform = options?.platform ?? process.platform;
+  const arch = options?.arch ?? process.arch;
+  let libc = null;
+  let candidatePlatformKey = null;
+  let candidateTargetTriple = null;
 
   if (platform === "darwin") {
-    if (arch === "arm64") return "darwin-arm64";
-    if (arch === "x64") return "darwin-x64";
+    if (arch === "arm64") candidatePlatformKey = "darwin-arm64";
+    if (arch === "x64") candidatePlatformKey = "darwin-x64";
   }
 
   if (platform === "linux") {
-    const libc = detectLibc();
-    if (arch === "arm64") return `linux-arm64-${libc}`;
-    if (arch === "x64") return `linux-x64-${libc}`;
+    libc = normalizeLibc(options?.libc) ?? detectLibcFromRuntime(options);
+    if (arch === "arm64") candidatePlatformKey = `linux-arm64-${libc}`;
+    if (arch === "x64") candidatePlatformKey = `linux-x64-${libc}`;
   }
 
   if (platform === "win32") {
-    if (arch === "x64") return "win32-x64";
-    if (arch === "arm64") return "win32-arm64";
+    if (arch === "x64") candidatePlatformKey = "win32-x64";
+    if (arch === "arm64") candidatePlatformKey = "win32-arm64";
   }
 
-  throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  if (candidatePlatformKey) {
+    const entry = PLATFORM_ENTRY_BY_KEY[candidatePlatformKey];
+    candidateTargetTriple = entry?.targetTriple ?? null;
+    if (entry?.published) return candidatePlatformKey;
+    if (entry && entry.published === false) {
+      throw new UnsupportedPlatformError({
+        platform,
+        arch,
+        libc,
+        candidatePlatformKey,
+        candidateTargetTriple,
+        reason: "target_not_published",
+        supportedPlatformKeys: SUPPORTED_PLATFORM_KEYS,
+        supportedTargetTriples: SUPPORTED_TARGET_TRIPLES
+      });
+    }
+  }
+
+  throw new UnsupportedPlatformError({
+    platform,
+    arch,
+    libc,
+    candidatePlatformKey,
+    candidateTargetTriple,
+    reason: "unknown_or_unsupported_runtime",
+    supportedPlatformKeys: SUPPORTED_PLATFORM_KEYS,
+    supportedTargetTriples: SUPPORTED_TARGET_TRIPLES
+  });
 }
 
 function artifactName(platformKey) {
-  return `docdexd-${platformKey}.tar.gz`;
+  return assetNameForPlatformKey(platformKey);
+}
+
+/**
+ * Human-readable release asset naming pattern for `docdexd` archives.
+ * @param {string|null} [platformKey]
+ * @param {{includeExample?: boolean, exampleAssetName?: string}} [options]
+ */
+function assetPatternForPlatformKey(platformKey, options) {
+  const includeExample = options?.includeExample !== false;
+  const exampleAssetName =
+    typeof options?.exampleAssetName === "string" && options.exampleAssetName.trim()
+      ? options.exampleAssetName.trim()
+      : null;
+  const base = "docdexd-<platformKey>.tar.gz";
+  if (!platformKey || typeof platformKey !== "string") return base;
+  if (!includeExample) return base;
+  return `${base} (e.g. ${exampleAssetName || assetNameForPlatformKey(platformKey)})`;
+}
+
+function targetTripleForPlatformKey(platformKey) {
+  const triple = PLATFORM_ENTRY_BY_KEY[platformKey]?.targetTriple;
+  if (triple) return triple;
+  throw new Error(
+    `Unsupported platform key: ${platformKey}. Supported: ${Object.keys(PLATFORM_ENTRY_BY_KEY).sort().join(", ")}`
+  );
+}
+
+function detectTargetTriple(options) {
+  return targetTripleForPlatformKey(detectPlatformKey(options));
+}
+
+/**
+ * Resolve the full platform support policy (runtime → supported? → target triple + asset naming).
+ * Consumers should use this as the single source of truth for distinguishing unsupported platforms
+ * from missing release artifacts (supported-but-missing).
+ *
+ * @param {Parameters<typeof detectPlatformKey>[0]} [options]
+ */
+function resolvePlatformPolicy(options) {
+  const platform = options?.platform ?? process.platform;
+  const arch = options?.arch ?? process.arch;
+  const platformKey = detectPlatformKey(options);
+  const targetTriple = targetTripleForPlatformKey(platformKey);
+  return {
+    detected: { platform, arch },
+    platformKey,
+    targetTriple,
+    expectedAssetName: artifactName(platformKey),
+    expectedAssetPattern: assetPatternForPlatformKey(platformKey)
+  };
 }
 
 module.exports = {
   detectLibc,
+  detectLibcFromRuntime,
   detectPlatformKey,
-  artifactName
+  UnsupportedPlatformError,
+  artifactName,
+  assetPatternForPlatformKey,
+  targetTripleForPlatformKey,
+  detectTargetTriple,
+  resolvePlatformPolicy
 };

package/lib/platform_matrix.js

@@ -0,0 +1,127 @@
+"use strict";
+
+/**
+ * Single source of truth for:
+ *   detected runtime (platform/arch/libc) -> platformKey -> Rust target triple -> release asset naming.
+ * Contract: docs/contracts/installer_platform_mapping_v1.md
+ *
+ * Notes:
+ * - `platformKey` is the suffix used in release assets: `docdexd-<platformKey>.tar.gz`.
+ * - Some mappings are defined but marked `published: false` when the release workflow does not
+ *   currently publish a matching binary artifact; these MUST be treated as unsupported at install/runtime.
+ */
+
+/** @type {{platform: string, arch: string, libc: (null|"gnu"|"musl"), platformKey: string, targetTriple: string, published: boolean}[]} */
+const PLATFORM_MATRIX = Object.freeze([
+  {
+    platform: "darwin",
+    arch: "arm64",
+    libc: null,
+    platformKey: "darwin-arm64",
+    targetTriple: "aarch64-apple-darwin",
+    published: true
+  },
+  {
+    platform: "darwin",
+    arch: "x64",
+    libc: null,
+    platformKey: "darwin-x64",
+    targetTriple: "x86_64-apple-darwin",
+    published: true
+  },
+  {
+    platform: "linux",
+    arch: "x64",
+    libc: "gnu",
+    platformKey: "linux-x64-gnu",
+    targetTriple: "x86_64-unknown-linux-gnu",
+    published: true
+  },
+  {
+    platform: "linux",
+    arch: "x64",
+    libc: "musl",
+    platformKey: "linux-x64-musl",
+    targetTriple: "x86_64-unknown-linux-musl",
+    published: true
+  },
+  {
+    platform: "linux",
+    arch: "arm64",
+    libc: "gnu",
+    platformKey: "linux-arm64-gnu",
+    targetTriple: "aarch64-unknown-linux-gnu",
+    published: true
+  },
+  {
+    platform: "linux",
+    arch: "arm64",
+    libc: "musl",
+    platformKey: "linux-arm64-musl",
+    targetTriple: "aarch64-unknown-linux-musl",
+    published: false
+  },
+  {
+    platform: "win32",
+    arch: "x64",
+    libc: null,
+    platformKey: "win32-x64",
+    targetTriple: "x86_64-pc-windows-msvc",
+    published: true
+  },
+  {
+    platform: "win32",
+    arch: "arm64",
+    libc: null,
+    platformKey: "win32-arm64",
+    targetTriple: "aarch64-pc-windows-msvc",
+    published: false
+  }
+]);
+
+const PLATFORM_ENTRY_BY_KEY = Object.freeze(
+  PLATFORM_MATRIX.reduce((acc, entry) => {
+    acc[entry.platformKey] = entry;
+    return acc;
+  }, {})
+);
+
+const PUBLISHED_PLATFORM_KEYS = Object.freeze(
+  PLATFORM_MATRIX.filter((e) => e.published)
+    .map((e) => e.platformKey)
+    .slice()
+    .sort()
+);
+
+const PUBLISHED_TARGET_TRIPLES = Object.freeze(
+  [...new Set(PLATFORM_MATRIX.filter((e) => e.published).map((e) => e.targetTriple))].sort()
+);
+
+function archiveBaseForPlatformKey(platformKey) {
+  return `docdexd-${platformKey}`;
+}
+
+function assetNameForPlatformKey(platformKey) {
+  return `${archiveBaseForPlatformKey(platformKey)}.tar.gz`;
+}
+
+/**
+ * Default target list for release-manifest generation (published targets only).
+ * Shape matches scripts/generate_release_manifest.cjs `targets` input.
+ */
+const PUBLISHED_RELEASE_TARGETS = Object.freeze(
+  PLATFORM_MATRIX.filter((e) => e.published)
+    .map((e) => ({ targetTriple: e.targetTriple, archiveBase: archiveBaseForPlatformKey(e.platformKey) }))
+    .slice()
+    .sort((a, b) => a.targetTriple.localeCompare(b.targetTriple))
+);
+
+module.exports = {
+  PLATFORM_MATRIX,
+  PLATFORM_ENTRY_BY_KEY,
+  PUBLISHED_PLATFORM_KEYS,
+  PUBLISHED_TARGET_TRIPLES,
+  PUBLISHED_RELEASE_TARGETS,
+  archiveBaseForPlatformKey,
+  assetNameForPlatformKey
+};