@modootoday/envs 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,418 @@
+import { U as Unlock, D as DekWrap } from './config-DKLCgBZX.js';
+export { a as ConfigOptions, C as ConfigResult, b as ConflictError, c as CreateKeyringOptions, d as DEK_BYTES, E as Encoding, K as KekMissingError, e as Keyring, f as KeyringLockedError, L as Layer, O as OnConflict, P as Provenance, R as RecoveryCodeError, W as WrapMethod, g as addWrap, h as config, i as createKeyring, j as formatRecoveryCode, k as generateRecoveryCode, n as normaliseRecoveryCode, s as sameKey, u as unlockDek } from './config-DKLCgBZX.js';
+
+/**
+ * env format parser. An env document is a sequence of logical entries, each a
+ * comment, a blank line, or KEY=VALUE; a fourth kind means the file is not env
+ * format and none of it loads. Values never appear in findings.
+ */
+type EntryKind = "comment" | "blank" | "assignment";
+type Quote = '"' | "'" | "`";
+interface ParsedEntry {
+    readonly kind: EntryKind;
+    /** 1-based line where the entry starts. */
+    readonly line: number;
+    /** 1-based line where the entry ends; differs from line for multiline values. */
+    readonly endLine: number;
+    readonly key?: string;
+    readonly value?: string;
+    readonly quote?: Quote | null;
+    /** `export KEY=v` form. */
+    readonly exported?: boolean;
+}
+type FindingCode = "NOT_ENV_LINE" | "EMPTY_KEY" | "INVALID_KEY" | "UNTERMINATED_QUOTE" | "TRAILING_CONTENT";
+interface ParseFinding {
+    readonly code: FindingCode;
+    readonly line: number;
+}
+interface ParseResult {
+    readonly ok: boolean;
+    readonly entries: readonly ParsedEntry[];
+    readonly findings: readonly ParseFinding[];
+}
+declare function parseEnv(input: string): ParseResult;
+/**
+ * All-or-nothing: a file with any finding contributes no values at all, so a
+ * partially parseable file cannot lose entries silently.
+ */
+declare function toRecord(result: ParseResult): Record<string, string> | null;
+
+/**
+ * One provider per sqlite backend. Everything the backends disagree about lives
+ * here as data, so the open path stays the same for all three.
+ */
+type SqliteBackend = "bun" | "node" | "better-sqlite3";
+interface SqliteProvider {
+    readonly backend: SqliteBackend;
+    /** Held as a string: a literal specifier would make bundlers hard-fail. */
+    readonly specifier: string;
+    /** Export holding the constructor; "default" for the CJS module. */
+    readonly exportName: string;
+    /** Built into its runtime, so it costs a consumer nothing. */
+    readonly builtIn: boolean;
+    /**
+     * Whether this provider may even be attempted here. Not every bad import
+     * throws: loading better-sqlite3 under bun 1.3.14 panics the process with
+     * NAPI FATAL ERROR, which no try/catch can contain. Ineligible providers are
+     * skipped rather than tried.
+     */
+    eligible(): boolean;
+    /** Constructor options. No two backends spell these the same way. */
+    openOptions(readOnly: boolean): unknown;
+    /**
+     * Key form for a named parameter. Measured: bun needs the sigil token,
+     * better-sqlite3 needs the bare name, node takes either. Getting it wrong is
+     * not always an error — bun binds NULL and says nothing.
+     */
+    bindKey(bare: string, token: string): string;
+}
+declare const PROVIDERS: readonly SqliteProvider[];
+
+/**
+ * One sqlite surface over three providers. Each built-in resolves only in its
+ * own runtime, so an import failure is the ordinary path, and better-sqlite3 is
+ * the fallback for runtimes that have neither.
+ */
+
+type SqliteValue = null | number | bigint | string | Uint8Array;
+type BindValue = SqliteValue | boolean;
+type BindParams = readonly BindValue[] | Readonly<Record<string, BindValue>>;
+interface RunResult {
+    readonly changes: number | bigint;
+    readonly lastInsertRowid: number | bigint;
+}
+interface Statement<Row = Record<string, SqliteValue>> {
+    get(params?: BindParams): Row | undefined;
+    all(params?: BindParams): Row[];
+    run(params?: BindParams): RunResult;
+}
+interface Database {
+    readonly backend: SqliteBackend;
+    exec(sql: string): void;
+    prepare<Row = Record<string, SqliteValue>>(sql: string): Statement<Row>;
+    /** BEGIN/COMMIT around fn, ROLLBACK if it throws. Not nestable. */
+    transaction<T>(fn: () => T): T;
+    close(): void;
+}
+interface OpenOptions {
+    /** WAL unless the database is in memory, where it is not available. */
+    readonly journalMode?: "WAL" | "DELETE" | "MEMORY";
+    readonly readOnly?: boolean;
+    /** Pin a backend instead of taking the first that loads. */
+    readonly backend?: SqliteBackend;
+}
+declare class SqliteUnavailableError extends Error {
+    readonly attempts: ReadonlyArray<readonly [string, string]>;
+    constructor(attempts: ReadonlyArray<readonly [string, string]>);
+}
+declare class SqliteBindError extends Error {
+    constructor(message: string);
+}
+/**
+ * Named placeholders in a statement, bare name to the exact token. bun binds
+ * NULL without complaint when a key's sigil does not match its placeholder, so
+ * keys are matched against the SQL rather than trusted or stripped.
+ */
+declare function scanPlaceholders(sql: string): ReadonlyMap<string, string>;
+declare function openDatabase(path: string, options?: OpenOptions): Promise<Database>;
+declare function openDatabaseSync(path: string, options?: OpenOptions): Database;
+/** Which backends load here. Empty when none do. */
+declare function availableBackends(): Promise<readonly SqliteBackend[]>;
+/** Test seam: forget loaded constructors so resolution can run again. */
+declare function resetBindingCache(): void;
+
+/** Algorithm agility. One value today; without the field there is no second. */
+declare const FORMAT_AES_256_GCM = 1;
+declare class EnvelopeFormatError extends Error {
+    constructor(message: string);
+}
+declare class EnvelopeAuthError extends Error {
+    constructor(message: string);
+}
+interface EnvelopeHeader {
+    readonly format: number;
+    readonly kekVersion: number;
+    readonly iv: Uint8Array;
+}
+/**
+ * Context is what the blob is bound to — the row it belongs to, or the freshness
+ * of the catalog it was derived from. Moving an authentic blob elsewhere then
+ * fails to decrypt instead of resurrecting a value.
+ */
+interface SealInput {
+    readonly kek: Uint8Array;
+    readonly kekVersion: number;
+    readonly plaintext: Uint8Array;
+    readonly context: Uint8Array;
+    /** Injectable for tests; production leaves it to the runtime CSPRNG. */
+    readonly iv?: Uint8Array;
+}
+declare function seal(input: SealInput): Uint8Array;
+interface OpenInput {
+    readonly kek: Uint8Array;
+    readonly blob: Uint8Array;
+    readonly context: Uint8Array;
+}
+declare function open(input: OpenInput): Uint8Array;
+/** Read the header without the key, so a reader can tell which KEK is needed. */
+declare function readHeader(blob: Uint8Array): EnvelopeHeader;
+/**
+ * Key names are stored as deterministic HMACs, so opening the database without
+ * the key shows neither values nor which keys exist. Derived under its own
+ * label rather than using the KEK directly for a second algorithm.
+ */
+declare function hashKeyName(kek: Uint8Array, name: string): Uint8Array;
+
+/**
+ * Catalog schema and its version gate. Statements are literals; nothing a
+ * caller supplies reaches statement text.
+ */
+
+declare const SCHEMA_VERSION = 4;
+interface Migration {
+    readonly version: number;
+    readonly statements: readonly string[];
+}
+declare const MIGRATIONS: readonly Migration[];
+declare class CatalogVersionError extends Error {
+    readonly found: number;
+    readonly supported: number;
+    constructor(found: number, supported: number, message: string);
+}
+interface CatalogMeta {
+    readonly version: number;
+    readonly catalogId: string;
+    readonly createdAt: string;
+}
+declare function readMeta(db: Database): CatalogMeta | undefined;
+interface CreateOptions {
+    readonly catalogId?: string;
+    readonly now?: () => string;
+}
+/** Build an empty catalog at the current version. */
+declare function createSchema(db: Database, options?: CreateOptions): CatalogMeta;
+/**
+ * A catalog newer than this build is refused rather than read: reading it with
+ * an older understanding is how a value comes back wrong. An older one is
+ * reported, never migrated as a side effect of being opened -- one run of a
+ * floating CLI must not upgrade a catalog another project has pinned.
+ */
+declare function checkVersion(meta: CatalogMeta): void;
+interface OpenCatalogOptions extends OpenOptions {
+    /** Create the schema when the file holds none. Off for read paths. */
+    readonly create?: boolean;
+    readonly catalogId?: string;
+    readonly now?: () => string;
+}
+interface OpenedCatalog {
+    readonly db: Database;
+    readonly meta: CatalogMeta;
+}
+declare function openCatalog(path: string, options?: OpenCatalogOptions): Promise<OpenedCatalog>;
+/** Bring an older catalog up to this build's version, on purpose. */
+declare function migrate(db: Database): CatalogMeta;
+
+declare function findProjectRoot(from: string): string | undefined;
+declare function globalDir(home?: string): string;
+interface LocateOptions {
+    readonly cwd?: string;
+    readonly home?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+interface Located {
+    /** The catalog this project reads and writes. Always present. */
+    readonly project: string;
+    /**
+     * The machine-wide layer, when a project catalog is distinct from it. Absent
+     * when there is no project root, because then the home catalog is the project
+     * one and there is no second layer.
+     */
+    readonly global?: string;
+    readonly projectRoot?: string;
+    readonly source: "explicit" | "project" | "global";
+}
+/**
+ * ENVS_CATALOG_PATH names one catalog and suppresses the layering: a caller
+ * that says exactly which file to read should not silently get a second.
+ */
+declare function locateCatalogs(options?: LocateOptions): Located;
+/**
+ * The cache follows the binary rather than the catalog: node_modules when
+ * installed, the home directory under npx or a global install. It is derived,
+ * so the two never disagree in a way that matters.
+ */
+declare function cacheDir(options?: LocateOptions): string;
+
+/**
+ * export — the one command that prints values. Everything else in this package
+ * reports keys and provenance and never a value, so this path is explicit,
+ * asks for the secret rather than taking it from argv, and says what it did.
+ */
+
+type ExportFormat = "csv" | "env" | "json" | "shell";
+interface ExportOptions extends LocateOptions {
+    readonly unlock: Unlock;
+    readonly format?: ExportFormat;
+    readonly aliases?: readonly string[];
+    readonly revisionId?: string;
+    /** Include the machine-wide layer. Off by default: export one store at a time. */
+    readonly includeGlobal?: boolean;
+}
+interface ExportResult {
+    readonly text: string;
+    readonly count: number;
+    /** Keys whose value a spreadsheet would evaluate rather than display. */
+    readonly formulaKeys: readonly string[];
+    readonly catalogs: readonly string[];
+}
+/** RFC 4180. Every field is quoted: env values carry commas and newlines. */
+declare function csvField(value: string): string;
+declare function exportValues(options: ExportOptions): ExportResult;
+
+/**
+ * Reading values out of a catalog. Every item is sealed under the DEK and bound
+ * to its row, and the key name travels inside the envelope rather than beside
+ * it, so a database opened without the key shows neither.
+ */
+
+interface CatalogEntry {
+    readonly key: string;
+    readonly value: string;
+    readonly sourceId: string;
+    readonly alias: string;
+    readonly path: string;
+}
+declare class NoReleaseError extends Error {
+    constructor(message: string);
+}
+/** Binds an item to its row, so a blob cannot be moved between them. */
+declare function itemContext(sourceId: string, keyHash: Uint8Array, revisionId: string): Uint8Array;
+declare function readWraps(db: Database): DekWrap[];
+declare function currentRevision(db: Database): string | undefined;
+interface ReadOptions {
+    readonly unlock: Unlock;
+    /** Read a specific release instead of whatever the pointer names. */
+    readonly revisionId?: string;
+    /** Restrict to these source aliases, in this order. */
+    readonly aliases?: readonly string[];
+}
+/**
+ * Entries for one release, in source order. Order is what the caller uses to
+ * decide a winner, so it is preserved rather than collapsed here: which file
+ * declared a key is the question this store exists to answer.
+ */
+declare function readEntries(db: Database, options: ReadOptions): readonly CatalogEntry[];
+
+/**
+ * Terminal output in the shape prompts uses — a symbol, a colour, aligned
+ * secondary text — written here rather than depended on, because this package
+ * ships with no runtime dependencies.
+ */
+interface Stream {
+    write(text: string): unknown;
+    isTTY?: boolean;
+}
+interface UiOptions {
+    readonly stdout?: Stream;
+    readonly stderr?: Stream;
+    /** Force colour on or off. Otherwise a TTY and NO_COLOR decide. */
+    readonly color?: boolean;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+declare const CODES: {
+    readonly reset: `${string}[0m`;
+    readonly bold: `${string}[1m`;
+    readonly dim: `${string}[2m`;
+    readonly red: `${string}[31m`;
+    readonly green: `${string}[32m`;
+    readonly yellow: `${string}[33m`;
+    readonly cyan: `${string}[36m`;
+};
+type Colour = keyof typeof CODES;
+/**
+ * Symbols are ASCII on purpose. The colour carries the state, and a glyph that
+ * a terminal renders as a box carries nothing.
+ */
+declare const SYMBOL: {
+    readonly success: "+";
+    readonly error: "x";
+    readonly warn: "!";
+    readonly info: "-";
+    readonly prompt: ">";
+};
+type Kind = keyof typeof SYMBOL;
+declare class Ui {
+    private readonly out;
+    private readonly err;
+    readonly colour: boolean;
+    constructor(options?: UiOptions);
+    paint(text: string, ...colours: readonly Colour[]): string;
+    /** Data goes to stdout so it can be piped; everything else to stderr. */
+    data(text: string): void;
+    line(text?: string): void;
+    message(kind: Kind, text: string, detail?: string): void;
+    success(text: string, detail?: string): void;
+    error(text: string, detail?: string): void;
+    warn(text: string, detail?: string): void;
+    info(text: string, detail?: string): void;
+    /** Two aligned columns, as a help screen or a summary. */
+    table(rows: ReadonlyArray<readonly [string, string]>, indent?: string): void;
+    heading(text: string): void;
+}
+
+/**
+ * A command is a value: its name, what it takes, and what it does. Help is
+ * generated from that rather than written twice, so a flag cannot exist in one
+ * and not the other.
+ */
+
+interface OptionSpec {
+    readonly name: string;
+    readonly describe: string;
+    /** A flag with no value. */
+    readonly boolean?: boolean;
+    /** May appear more than once; the parsed value is always an array. */
+    readonly repeat?: boolean;
+    readonly placeholder?: string;
+}
+interface ParsedArgs {
+    readonly positional: readonly string[];
+    readonly options: ReadonlyMap<string, readonly string[]>;
+    readonly flags: ReadonlySet<string>;
+}
+interface CommandContext {
+    readonly ui: Ui;
+    readonly args: ParsedArgs;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly cwd: string;
+}
+/** Help headings, in the order someone meets them. */
+declare const GROUPS: readonly ["start here", "values", "check", "history", "backup", "hosted account", "publish"];
+type Group = (typeof GROUPS)[number];
+interface Command {
+    readonly name: string;
+    readonly describe: string;
+    readonly usage: string;
+    /** Which help heading it sits under. Absent means the trailing one. */
+    readonly group?: Group;
+    readonly options?: readonly OptionSpec[];
+    /**
+     * Exit code. 0 success, 1 the work failed, 2 the invocation was wrong.
+     * May be async: a destination can be a network. config() stays synchronous,
+     * which is a rule about the loader rather than about commands.
+     */
+    run(context: CommandContext): number | Promise<number>;
+}
+
+declare const COMMANDS: readonly Command[];
+/** Named so an unknown verb can say "designed, not built" rather than "unknown". */
+/** Empty: every verb the design named is built. */
+declare const PLANNED: readonly string[];
+interface DispatchOptions {
+    readonly ui?: Ui;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly cwd?: string;
+}
+declare function dispatch(argv: readonly string[], options?: DispatchOptions): number | Promise<number>;
+
+export { type BindParams, type BindValue, COMMANDS, type CatalogEntry, type CatalogMeta, CatalogVersionError, type Database, DekWrap, type DispatchOptions, type EntryKind, EnvelopeAuthError, EnvelopeFormatError, type EnvelopeHeader, type ExportFormat, type ExportOptions, type ExportResult, FORMAT_AES_256_GCM, type FindingCode, type LocateOptions, type Located, MIGRATIONS, type Migration, NoReleaseError, type OpenCatalogOptions, type OpenInput, type OpenOptions, type OpenedCatalog, PLANNED, PROVIDERS, type ParseFinding, type ParseResult, type ParsedEntry, type Quote, type ReadOptions, type RunResult, SCHEMA_VERSION, type SealInput, type SqliteBackend, SqliteBindError, type SqliteProvider, SqliteUnavailableError, type SqliteValue, type Statement, type Stream, Ui, type UiOptions, Unlock, availableBackends, cacheDir, checkVersion, createSchema, csvField, currentRevision, dispatch, exportValues, findProjectRoot, globalDir, hashKeyName, itemContext, locateCatalogs, migrate, openCatalog, openDatabase, openDatabaseSync, open as openEnvelope, parseEnv, readEntries, readHeader, readMeta, readWraps, resetBindingCache, scanPlaceholders, seal, toRecord };

package/dist/index.js

@@ -0,0 +1,112 @@
+import {
+  COMMANDS,
+  PLANNED,
+  Ui,
+  csvField,
+  dispatch,
+  exportValues
+} from "./chunk-47XO3SDE.js";
+import {
+  CatalogVersionError,
+  ConflictError,
+  DEK_BYTES,
+  EnvelopeAuthError,
+  EnvelopeFormatError,
+  FORMAT_AES_256_GCM,
+  KekMissingError,
+  KeyringLockedError,
+  MIGRATIONS,
+  NoReleaseError,
+  PROVIDERS,
+  RecoveryCodeError,
+  SCHEMA_VERSION,
+  SqliteBindError,
+  SqliteUnavailableError,
+  addWrap,
+  availableBackends,
+  cacheDir,
+  checkVersion,
+  config,
+  createKeyring,
+  createSchema,
+  currentRevision,
+  findProjectRoot,
+  formatRecoveryCode,
+  generateRecoveryCode,
+  globalDir,
+  hashKeyName,
+  itemContext,
+  locateCatalogs,
+  migrate,
+  normaliseRecoveryCode,
+  open,
+  openCatalog,
+  openDatabase,
+  openDatabaseSync,
+  parseEnv,
+  readEntries,
+  readHeader,
+  readMeta,
+  readWraps,
+  resetBindingCache,
+  sameKey,
+  scanPlaceholders,
+  seal,
+  toRecord,
+  unlockDek
+} from "./chunk-STHFIZRP.js";
+export {
+  COMMANDS,
+  CatalogVersionError,
+  ConflictError,
+  DEK_BYTES,
+  EnvelopeAuthError,
+  EnvelopeFormatError,
+  FORMAT_AES_256_GCM,
+  KekMissingError,
+  KeyringLockedError,
+  MIGRATIONS,
+  NoReleaseError,
+  PLANNED,
+  PROVIDERS,
+  RecoveryCodeError,
+  SCHEMA_VERSION,
+  SqliteBindError,
+  SqliteUnavailableError,
+  Ui,
+  addWrap,
+  availableBackends,
+  cacheDir,
+  checkVersion,
+  config,
+  createKeyring,
+  createSchema,
+  csvField,
+  currentRevision,
+  dispatch,
+  exportValues,
+  findProjectRoot,
+  formatRecoveryCode,
+  generateRecoveryCode,
+  globalDir,
+  hashKeyName,
+  itemContext,
+  locateCatalogs,
+  migrate,
+  normaliseRecoveryCode,
+  openCatalog,
+  openDatabase,
+  openDatabaseSync,
+  open as openEnvelope,
+  parseEnv,
+  readEntries,
+  readHeader,
+  readMeta,
+  readWraps,
+  resetBindingCache,
+  sameKey,
+  scanPlaceholders,
+  seal,
+  toRecord,
+  unlockDek
+};

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@modootoday/envs",
+  "version": "0.1.0",
+  "license": "Elastic-2.0",
+  "author": "modootoday",
+  "description": "Environment values in an encrypted catalog rather than scattered files — provenance, releases, rollback and a strict .env format gate. dotenv-compatible surface.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "require": "./dist/config.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/.tsbuildinfo",
+    "!dist/cli.cjs",
+    "!dist/cli.d.cts",
+    "README.md",
+    ".agent/skills",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "site:build": "node scripts/build-registry-pages.mjs",
+    "site:deployed": "node scripts/check-deployed.mjs",
+    "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile ./dist/.tsbuildinfo",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepack": "npm run build && npm run typecheck && npm test"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "better-sqlite3": "^13.0.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "better-sqlite3": ">=9"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.3.0"
+  },
+  "bin": {
+    "envs": "dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "homepage": "https://envs.build",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modootoday/envs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/modootoday/envs/issues"
+  },
+  "keywords": [
+    "dotenv",
+    "env",
+    ".env",
+    "environment",
+    "variables",
+    "config",
+    "settings",
+    "env vars",
+    "environment variables",
+    "secrets",
+    "secret-management",
+    "encryption",
+    "encrypted",
+    "credentials",
+    "key-rotation",
+    "recovery-codes",
+    "rollback",
+    "cli"
+  ]
+}