bulgur 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# bulgur
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ultra-simple secrets manager CLI. This npm package is a thin, self-contained
+distribution of the `bulgur` binary — no postinstall downloads, no network
+access required. The correct binary for your platform is bundled inside the
+package and launched by a small Node shim.
+
+## Add it to a project
+
+```sh
+npx bulgur init
+```
+
+`init` links the directory to a bulgur project (writes `bulgur.json`), adds
+`bulgur` as a devDependency and wraps your `dev` script:
+
+```json
+"scripts": { "dev": "bulgur run -- next dev" }
+```
+
+Commit `bulgur.json` and `package.json`. From then on a teammate only runs:
+
+```sh
+git clone … && cd app
+pnpm install
+pnpm dev        # asks for their bulgur email/username + password once, then starts with secrets
+```
+
+No `.env` files to pass around. In CI, set `BULGUR_TOKEN`, or
+`BULGUR_SKIP=1` to run a wrapped script without secrets.
+
+## Install globally
+
+```sh
+npm install -g bulgur
+```
+
+## Usage
+
+```sh
+bulgur login              # email/username + password, or --token blg_...
+bulgur init
+bulgur run -- <command>   # inject secrets into one command
+bulgur pull               # write a .env
+bulgur push
+```
+
+## Supported platforms
+
+- macOS (Intel `x64`, Apple Silicon `arm64`)
+- Linux (`x64`, `arm64`)
+
+Windows is not supported yet.
+
+## How it works
+
+`bin/bulgur.js` selects `binaries/<platform>-<arch>/bulgur` based on
+`process.platform` + `process.arch`, spawns it with inherited stdio, and
+forwards the exit code and signals. Binaries are stamped into the package at
+publish time from the goreleaser build.
+
+## Runtime SDK
+
+This package also exports a tiny, dependency-free runtime SDK for loading
+secrets into `process.env` at process startup — no CLI binary involved:
+
+```js
+const { load } = require("bulgur");
+// or: import { load } from "bulgur";
+
+await load(); // reads BULGUR_DSN, assigns onto process.env
+```
+
+Set `BULGUR_DSN` to a **runtime-scoped** token DSN:
+`bulgur://TOKEN@HOST/ORG/PROJECT/ENV`. See the repo root `README.md`
+("Runtime (deploy platforms)") for platform examples. `load()` accepts
+`{ dsn, override, optional }` — see `index.d.ts` for details.

package/bin/bulgur.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+"use strict";
+
+// Thin launcher: pick the bundled bulgur binary that matches the host
+// platform/arch and exec it, forwarding stdio, the exit code, and signals.
+// The binaries are fat-bundled into this package at pack time (see the repo
+// Makefile `npm-pack` target), so there is NO network/postinstall step —
+// this works even while the GitHub repo is private.
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// Node reports arch as x64/arm64; we bundle binaries under matching dir names.
+const platform = process.platform; // 'darwin' | 'linux'
+const arch = process.arch; // 'x64' | 'arm64'
+
+const supported = new Set([
+  "darwin-x64",
+  "darwin-arm64",
+  "linux-x64",
+  "linux-arm64",
+]);
+
+const key = `${platform}-${arch}`;
+if (!supported.has(key)) {
+  console.error(
+    `bulgur: unsupported platform/arch "${key}". ` +
+      `Supported: ${[...supported].join(", ")}.`
+  );
+  process.exit(1);
+}
+
+const binPath = path.join(__dirname, "..", "binaries", key, "bulgur");
+if (!fs.existsSync(binPath)) {
+  console.error(
+    `bulgur: bundled binary not found at ${binPath}. ` +
+      `This package may have been built without the ${key} binary.`
+  );
+  process.exit(1);
+}
+
+// spawnSync with stdio: inherit forwards stdin/stdout/stderr transparently and
+// relays terminating signals to the child on POSIX, so the run command's signal
+// handling keeps working.
+const result = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  console.error(`bulgur: failed to launch binary: ${result.error.message}`);
+  process.exit(1);
+}
+
+if (result.signal) {
+  // Re-raise the signal so the parent shell sees the correct termination cause.
+  process.kill(process.pid, result.signal);
+  return;
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/index.d.ts

@@ -0,0 +1,75 @@
+// Type definitions for the `bulgur` runtime SDK.
+// Hand-written; no build step. Kept in sync with index.js by hand.
+
+export interface LoadOptions {
+  /**
+   * The DSN to load, of the form `bulgur://TOKEN@HOST/ORG/PROJECT/ENV`.
+   * Defaults to `process.env.BULGUR_DSN`.
+   */
+  dsn?: string;
+
+  /**
+   * When true, values fetched from bulgur overwrite any existing
+   * `process.env` entry with the same name.
+   *
+   * Default: false — existing `process.env` values win, and the fetched
+   * value is skipped (not counted in the returned `loaded` count).
+   */
+  override?: boolean;
+
+  /**
+   * When true:
+   *   - a missing/empty DSN resolves `{ loaded: 0 }` instead of throwing.
+   *   - a network failure or non-2xx HTTP response resolves `{ loaded: 0 }`
+   *     instead of throwing.
+   * A DSN that IS present but malformed (bad scheme, missing token, wrong
+   * number of path segments, etc.) always throws regardless of this option
+   * — a configuration typo should be loud.
+   *
+   * Default: false — all of the above throw.
+   */
+  optional?: boolean;
+}
+
+export interface LoadResult {
+  /**
+   * The number of secrets actually written to `process.env`. Secrets that
+   * were fetched but skipped because an existing `process.env` value won
+   * (see `override`) are NOT counted.
+   */
+  loaded: number;
+}
+
+export interface ParsedDsn {
+  /** The bearer token (userinfo component of the DSN). */
+  token: string;
+  /** Lowercased `host[:port]`. */
+  host: string;
+  /** Org slug (first path segment). */
+  org: string;
+  /** Project slug (second path segment). */
+  project: string;
+  /** Environment slug (third path segment). */
+  env: string;
+  /**
+   * The resolved API base URL, e.g. `https://api.bulgur.dev` or
+   * `http://localhost:5432`. `http` is used only for `localhost` /
+   * `127.0.0.1` hosts; every other host uses `https`.
+   */
+  baseUrl: string;
+}
+
+/**
+ * Load secret values for the environment identified by `options.dsn` (or
+ * `process.env.BULGUR_DSN`) and assign them onto `process.env`.
+ *
+ * This is a one-shot call: after it resolves, this module has no further
+ * runtime effect and holds no open connections.
+ */
+export function load(options?: LoadOptions): Promise<LoadResult>;
+
+/**
+ * Parse and validate a `bulgur://TOKEN@HOST/ORG/PROJECT/ENV` DSN without
+ * making a network call. Thrown error messages never include the token.
+ */
+export function parseDsn(dsn: string): ParsedDsn;

package/index.js

@@ -0,0 +1,191 @@
+"use strict";
+
+// bulgur runtime SDK — Node >= 18 (relies on global fetch, no deps).
+//
+// Reads a `bulgur://TOKEN@HOST/ORG/PROJECT/ENV` DSN, fetches the merged
+// secret values for that org/project/environment from the bulgur API, and
+// assigns them onto process.env. This module has zero runtime dependencies
+// and is hand-written CJS (no bundler/build step) so it can ship inside the
+// npm fat-bundle package alongside the CLI binary wrapper.
+//
+// Error hygiene: no error thrown by this module ever includes the TOKEN.
+// Messages may include host/org/project/env and HTTP status for debugging.
+
+/**
+ * Parse a bulgur DSN of the form:
+ *   bulgur://TOKEN@HOST[:PORT]/ORG/PROJECT/ENV
+ *
+ * Parsed manually (not via WHATWG URL) because the URL parser does not
+ * lowercase the host for non-special schemes like "bulgur:", which would
+ * silently produce a different (case-sensitive) host than intended.
+ *
+ * @param {string} dsn
+ * @returns {{token: string, host: string, org: string, project: string, env: string, baseUrl: string}}
+ */
+function parseDsn(dsn) {
+  if (typeof dsn !== "string" || dsn.length === 0) {
+    throw new Error("bulgur: invalid DSN: expected a non-empty string");
+  }
+
+  const SCHEME_SEP = "://";
+  const schemeIdx = dsn.indexOf(SCHEME_SEP);
+  if (schemeIdx === -1) {
+    throw new Error(
+      'bulgur: invalid DSN: expected "bulgur://TOKEN@HOST/ORG/PROJECT/ENV"'
+    );
+  }
+
+  const scheme = dsn.slice(0, schemeIdx);
+  if (scheme !== "bulgur") {
+    throw new Error(
+      `bulgur: invalid DSN: scheme must be "bulgur", got "${scheme}"`
+    );
+  }
+
+  // rest = TOKEN@HOST[:PORT]/ORG/PROJECT/ENV[/]
+  const rest = dsn.slice(schemeIdx + SCHEME_SEP.length);
+
+  const atIdx = rest.indexOf("@");
+  if (atIdx === -1) {
+    throw new Error(
+      "bulgur: invalid DSN: missing token (expected TOKEN@HOST/...)"
+    );
+  }
+
+  const token = rest.slice(0, atIdx);
+  if (token.length === 0) {
+    throw new Error("bulgur: invalid DSN: token must not be empty");
+  }
+
+  const afterAt = rest.slice(atIdx + 1); // HOST[:PORT]/ORG/PROJECT/ENV[/]
+  const slashIdx = afterAt.indexOf("/");
+  if (slashIdx === -1) {
+    throw new Error(
+      "bulgur: invalid DSN: missing path (expected /ORG/PROJECT/ENV)"
+    );
+  }
+
+  const rawHost = afterAt.slice(0, slashIdx);
+  if (rawHost.length === 0) {
+    throw new Error("bulgur: invalid DSN: host must not be empty");
+  }
+
+  let pathPart = afterAt.slice(slashIdx + 1); // ORG/PROJECT/ENV possibly with a trailing slash
+  if (pathPart.endsWith("/")) {
+    pathPart = pathPart.slice(0, -1);
+  }
+
+  const segments = pathPart.length === 0 ? [] : pathPart.split("/");
+  if (segments.length !== 3 || segments.some((s) => s.length === 0)) {
+    throw new Error(
+      "bulgur: invalid DSN: path must have exactly 3 non-empty segments " +
+        `(/ORG/PROJECT/ENV), got ${segments.length} segment(s)`
+    );
+  }
+  const [org, project, envSlug] = segments;
+
+  // Split optional :PORT off the host, then lowercase (hosts are
+  // case-insensitive; the WHATWG URL parser does NOT do this for us on a
+  // non-special scheme like "bulgur:", so we do it ourselves).
+  let hostname = rawHost;
+  let port = "";
+  const colonIdx = rawHost.lastIndexOf(":");
+  if (colonIdx !== -1) {
+    hostname = rawHost.slice(0, colonIdx);
+    port = rawHost.slice(colonIdx + 1);
+    if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+      throw new Error("bulgur: invalid DSN: invalid port in host");
+    }
+  }
+  if (hostname.length === 0) {
+    throw new Error("bulgur: invalid DSN: host must not be empty");
+  }
+  hostname = hostname.toLowerCase();
+  const host = port ? `${hostname}:${port}` : hostname;
+
+  const isLocal = hostname === "localhost" || hostname === "127.0.0.1";
+  const scheme2 = isLocal ? "http" : "https";
+  const baseUrl = `${scheme2}://${host}`;
+
+  return { token, host, org, project, env: envSlug, baseUrl };
+}
+
+/**
+ * @param {{dsn?: string, override?: boolean, optional?: boolean}} [options]
+ * @returns {Promise<{loaded: number}>}
+ */
+async function load(options) {
+  const opts = options || {};
+  const dsn = opts.dsn !== undefined ? opts.dsn : process.env.BULGUR_DSN;
+  const override = opts.override === true;
+  const optional = opts.optional === true;
+
+  if (!dsn) {
+    if (optional) return { loaded: 0 };
+    throw new Error(
+      "bulgur: missing DSN (set BULGUR_DSN or pass { dsn } to load())"
+    );
+  }
+
+  // Malformed DSN is always loud, even with optional:true.
+  const parsed = parseDsn(dsn);
+  const { token, host, org, project, env, baseUrl } = parsed;
+
+  const url =
+    `${baseUrl}/v1/orgs/${encodeURIComponent(org)}` +
+    `/projects/${encodeURIComponent(project)}` +
+    `/environments/${encodeURIComponent(env)}/values`;
+
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+      },
+    });
+  } catch (err) {
+    if (optional) return { loaded: 0 };
+    throw new Error(
+      `bulgur: failed to reach ${host} (org=${org}, project=${project}, ` +
+        `env=${env}): ${err && err.message ? err.message : err}`
+    );
+  }
+
+  if (!res.ok) {
+    if (optional) return { loaded: 0 };
+    throw new Error(
+      `bulgur: request to ${host} failed with HTTP ${res.status} ` +
+        `(org=${org}, project=${project}, env=${env})`
+    );
+  }
+
+  let body;
+  try {
+    body = await res.json();
+  } catch (err) {
+    if (optional) return { loaded: 0 };
+    throw new Error(
+      `bulgur: failed to parse response from ${host} as JSON ` +
+        `(org=${org}, project=${project}, env=${env})`
+    );
+  }
+
+  const secrets = body && Array.isArray(body.secrets) ? body.secrets : [];
+  let loaded = 0;
+  for (const secret of secrets) {
+    if (!secret || typeof secret.name !== "string") continue;
+    const key = secret.name;
+    const hasExisting = Object.prototype.hasOwnProperty.call(
+      process.env,
+      key
+    );
+    if (hasExisting && !override) continue; // existing env vars win by default
+    process.env[key] = secret.value == null ? "" : String(secret.value);
+    loaded++;
+  }
+
+  return { loaded };
+}
+
+module.exports = { load, parseDsn };

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "bulgur",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Ultra-simple secrets manager CLI (bulgur), plus a runtime SDK: `import { load } from \"bulgur\"`",
+  "bin": {
+    "bulgur": "bin/bulgur.js"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "binaries/",
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "homepage": "https://bulgur.dev",
+  "license": "UNLICENSED",
+  "keywords": [
+    "bulgur",
+    "secrets",
+    "cli",
+    "env",
+    "dotenv",
+    "environment-variables",
+    "secrets-manager"
+  ]
+}