@neon/config 0.12.0 → 0.13.0

package/dist/paths.d.ts

@@ -0,0 +1,79 @@
+//#region src/paths.d.ts
+/**
+ * # `@neon/config/paths` — where the Neon CLIs keep their files on disk
+ *
+ * **Implementor-only, and deliberately impure.** This subpath reads environment variables
+ * and touches the filesystem, which the root `@neon/config` export must never do — the same
+ * split as `@neon/env` (pure) versus `@neon/env/runtime` (stateful). Import it from a CLI,
+ * never from a `neon.ts` policy. It imports nothing from the rest of the package, so pulling
+ * it in costs one module.
+ *
+ * It exists because three separate readers each grew their own answer to "where is the
+ * config directory", and all three disagreed: `packages/cli` honoured `XDG_CONFIG_HOME` but
+ * not `NEONCTL_CONFIG_DIR`, `packages/env` honoured the env var but not XDG, and
+ * `packages/init` hardcoded `~/.config/neonctl`. With `XDG_CONFIG_HOME` set, the CLI wrote
+ * credentials somewhere the other two never looked.
+ *
+ * ## The directory
+ *
+ * `neon` is the current name; `neonctl` is the legacy one, kept readable forever. Resolution,
+ * each entry winning over the next:
+ *
+ * 1. An explicit directory (a `--config-dir` flag) — **exact**, no legacy fallback.
+ * 2. `NEON_CONFIG_DIR` — exact.
+ * 3. `NEONCTL_CONFIG_DIR` (legacy name) — exact.
+ * 4. `$XDG_CONFIG_HOME/neon`, else `<home>/.config/neon`.
+ *
+ * An explicitly chosen directory is never paired with a fallback: `--config-dir /tmp/ci` that
+ * quietly read `~/.config/neonctl` would defeat the point of passing it.
+ *
+ * ## The files
+ *
+ * {@link resolveConfigFile} answers "which path should I use for this file", and it is the
+ * same answer for reading and writing:
+ *
+ * - Present in `neon/` → use it.
+ * - Present only in `neonctl/` → **use it there, in place.** An existing credentials file is
+ *   never copied or moved, so nothing is left behind to go stale and no other tool starts
+ *   reading an abandoned token.
+ * - Present in neither → the new location. New files only ever appear under `neon/`.
+ */
+/** Current directory name. New files are created here. */
+declare const CONFIG_DIR_NAME = "neon";
+/** Legacy directory name, read forever so existing installs keep working untouched. */
+declare const LEGACY_CONFIG_DIR_NAME = "neonctl";
+interface ConfigPathOptions {
+  /**
+   * An explicit directory, e.g. from a `--config-dir` flag. Used exactly as given: no
+   * environment variables are consulted and the legacy directory is never searched.
+   */
+  dir?: string;
+  /** Environment to read. Defaults to `process.env`. Injectable for tests. */
+  env?: NodeJS.ProcessEnv;
+}
+/** Where files are created. See the module docs for the precedence. */
+declare function configDir(options?: ConfigPathOptions): string;
+/**
+ * The legacy directory, or `undefined` when the location was chosen explicitly (in which
+ * case there is no legacy counterpart to fall back to).
+ */
+declare function legacyConfigDir(options?: ConfigPathOptions): string | undefined;
+interface ResolvedConfigFile {
+  /** The path to use, for both reading and writing. */
+  path: string;
+  /** The directory `path` lives in. */
+  dir: string;
+  /** True when the file was found in the legacy `neonctl` directory. */
+  isLegacy: boolean;
+  /** Whether the file exists at `path` right now. */
+  exists: boolean;
+}
+/**
+ * Resolve one file inside the config directory. Prefers the current location, falls back to
+ * an existing legacy file **in place**, and otherwise points at the current location so new
+ * files are created there.
+ */
+declare function resolveConfigFile(fileName: string, options?: ConfigPathOptions): ResolvedConfigFile;
+//#endregion
+export { CONFIG_DIR_NAME, ConfigPathOptions, LEGACY_CONFIG_DIR_NAME, ResolvedConfigFile, configDir, legacyConfigDir, resolveConfigFile };
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","names":[],"sources":["../src/paths.ts"],"mappings":";;AA4CA;AAGA;AAEA;AAWA;AAUA;AAOA;AAgBA;AAAiC;AAEvB;AACP;AAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cApDR,eAAA;;cAGA,sBAAA;UAEI,iBAAA;;;;;;;QAOV,MAAA,CAAO;;;iBAIE,SAAA,WAAmB;;;;;iBAUnB,eAAA,WACN;UAMO,kBAAA;;;;;;;;;;;;;;;iBAgBD,iBAAA,6BAEN,oBACP"}

package/dist/paths.js

@@ -0,0 +1,111 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+//#region src/paths.ts
+/**
+* # `@neon/config/paths` — where the Neon CLIs keep their files on disk
+*
+* **Implementor-only, and deliberately impure.** This subpath reads environment variables
+* and touches the filesystem, which the root `@neon/config` export must never do — the same
+* split as `@neon/env` (pure) versus `@neon/env/runtime` (stateful). Import it from a CLI,
+* never from a `neon.ts` policy. It imports nothing from the rest of the package, so pulling
+* it in costs one module.
+*
+* It exists because three separate readers each grew their own answer to "where is the
+* config directory", and all three disagreed: `packages/cli` honoured `XDG_CONFIG_HOME` but
+* not `NEONCTL_CONFIG_DIR`, `packages/env` honoured the env var but not XDG, and
+* `packages/init` hardcoded `~/.config/neonctl`. With `XDG_CONFIG_HOME` set, the CLI wrote
+* credentials somewhere the other two never looked.
+*
+* ## The directory
+*
+* `neon` is the current name; `neonctl` is the legacy one, kept readable forever. Resolution,
+* each entry winning over the next:
+*
+* 1. An explicit directory (a `--config-dir` flag) — **exact**, no legacy fallback.
+* 2. `NEON_CONFIG_DIR` — exact.
+* 3. `NEONCTL_CONFIG_DIR` (legacy name) — exact.
+* 4. `$XDG_CONFIG_HOME/neon`, else `<home>/.config/neon`.
+*
+* An explicitly chosen directory is never paired with a fallback: `--config-dir /tmp/ci` that
+* quietly read `~/.config/neonctl` would defeat the point of passing it.
+*
+* ## The files
+*
+* {@link resolveConfigFile} answers "which path should I use for this file", and it is the
+* same answer for reading and writing:
+*
+* - Present in `neon/` → use it.
+* - Present only in `neonctl/` → **use it there, in place.** An existing credentials file is
+*   never copied or moved, so nothing is left behind to go stale and no other tool starts
+*   reading an abandoned token.
+* - Present in neither → the new location. New files only ever appear under `neon/`.
+*/
+/** Current directory name. New files are created here. */
+const CONFIG_DIR_NAME = "neon";
+/** Legacy directory name, read forever so existing installs keep working untouched. */
+const LEGACY_CONFIG_DIR_NAME = "neonctl";
+/** Where files are created. See the module docs for the precedence. */
+function configDir(options = {}) {
+	const explicit = explicitDir(options);
+	if (explicit) return explicit;
+	return join(configHome(options.env ?? process.env), CONFIG_DIR_NAME);
+}
+/**
+* The legacy directory, or `undefined` when the location was chosen explicitly (in which
+* case there is no legacy counterpart to fall back to).
+*/
+function legacyConfigDir(options = {}) {
+	if (explicitDir(options)) return void 0;
+	return join(configHome(options.env ?? process.env), LEGACY_CONFIG_DIR_NAME);
+}
+/**
+* Resolve one file inside the config directory. Prefers the current location, falls back to
+* an existing legacy file **in place**, and otherwise points at the current location so new
+* files are created there.
+*/
+function resolveConfigFile(fileName, options = {}) {
+	const dir = configDir(options);
+	const current = resolve(dir, fileName);
+	if (existsSync(current)) return {
+		path: current,
+		dir,
+		isLegacy: false,
+		exists: true
+	};
+	const legacyDir = legacyConfigDir(options);
+	if (legacyDir) {
+		const legacy = resolve(legacyDir, fileName);
+		if (existsSync(legacy)) return {
+			path: legacy,
+			dir: legacyDir,
+			isLegacy: true,
+			exists: true
+		};
+	}
+	return {
+		path: current,
+		dir,
+		isLegacy: false,
+		exists: false
+	};
+}
+/** `$XDG_CONFIG_HOME`, else `<home>/.config`. Falls back to a relative `.config` with no home. */
+function configHome(env) {
+	const xdg = nonEmpty(env.XDG_CONFIG_HOME);
+	if (xdg) return xdg;
+	const home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);
+	return home ? join(home, ".config") : ".config";
+}
+function explicitDir(options) {
+	const env = options.env ?? process.env;
+	return nonEmpty(options.dir) ?? nonEmpty(env.NEON_CONFIG_DIR) ?? nonEmpty(env.NEONCTL_CONFIG_DIR);
+}
+function nonEmpty(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+//#endregion
+export { CONFIG_DIR_NAME, LEGACY_CONFIG_DIR_NAME, configDir, legacyConfigDir, resolveConfigFile };
+
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","names":[],"sources":["../src/paths.ts"],"sourcesContent":["/**\n * # `@neon/config/paths` — where the Neon CLIs keep their files on disk\n *\n * **Implementor-only, and deliberately impure.** This subpath reads environment variables\n * and touches the filesystem, which the root `@neon/config` export must never do — the same\n * split as `@neon/env` (pure) versus `@neon/env/runtime` (stateful). Import it from a CLI,\n * never from a `neon.ts` policy. It imports nothing from the rest of the package, so pulling\n * it in costs one module.\n *\n * It exists because three separate readers each grew their own answer to \"where is the\n * config directory\", and all three disagreed: `packages/cli` honoured `XDG_CONFIG_HOME` but\n * not `NEONCTL_CONFIG_DIR`, `packages/env` honoured the env var but not XDG, and\n * `packages/init` hardcoded `~/.config/neonctl`. With `XDG_CONFIG_HOME` set, the CLI wrote\n * credentials somewhere the other two never looked.\n *\n * ## The directory\n *\n * `neon` is the current name; `neonctl` is the legacy one, kept readable forever. Resolution,\n * each entry winning over the next:\n *\n * 1. An explicit directory (a `--config-dir` flag) — **exact**, no legacy fallback.\n * 2. `NEON_CONFIG_DIR` — exact.\n * 3. `NEONCTL_CONFIG_DIR` (legacy name) — exact.\n * 4. `$XDG_CONFIG_HOME/neon`, else `<home>/.config/neon`.\n *\n * An explicitly chosen directory is never paired with a fallback: `--config-dir /tmp/ci` that\n * quietly read `~/.config/neonctl` would defeat the point of passing it.\n *\n * ## The files\n *\n * {@link resolveConfigFile} answers \"which path should I use for this file\", and it is the\n * same answer for reading and writing:\n *\n * - Present in `neon/` → use it.\n * - Present only in `neonctl/` → **use it there, in place.** An existing credentials file is\n *   never copied or moved, so nothing is left behind to go stale and no other tool starts\n *   reading an abandoned token.\n * - Present in neither → the new location. New files only ever appear under `neon/`.\n */\n\nimport { existsSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\n\n/** Current directory name. New files are created here. */\nexport const CONFIG_DIR_NAME = \"neon\";\n\n/** Legacy directory name, read forever so existing installs keep working untouched. */\nexport const LEGACY_CONFIG_DIR_NAME = \"neonctl\";\n\nexport interface ConfigPathOptions {\n\t/**\n\t * An explicit directory, e.g. from a `--config-dir` flag. Used exactly as given: no\n\t * environment variables are consulted and the legacy directory is never searched.\n\t */\n\tdir?: string;\n\t/** Environment to read. Defaults to `process.env`. Injectable for tests. */\n\tenv?: NodeJS.ProcessEnv;\n}\n\n/** Where files are created. See the module docs for the precedence. */\nexport function configDir(options: ConfigPathOptions = {}): string {\n\tconst explicit = explicitDir(options);\n\tif (explicit) return explicit;\n\treturn join(configHome(options.env ?? process.env), CONFIG_DIR_NAME);\n}\n\n/**\n * The legacy directory, or `undefined` when the location was chosen explicitly (in which\n * case there is no legacy counterpart to fall back to).\n */\nexport function legacyConfigDir(\n\toptions: ConfigPathOptions = {},\n): string | undefined {\n\tif (explicitDir(options)) return undefined;\n\treturn join(configHome(options.env ?? process.env), LEGACY_CONFIG_DIR_NAME);\n}\n\nexport interface ResolvedConfigFile {\n\t/** The path to use, for both reading and writing. */\n\tpath: string;\n\t/** The directory `path` lives in. */\n\tdir: string;\n\t/** True when the file was found in the legacy `neonctl` directory. */\n\tisLegacy: boolean;\n\t/** Whether the file exists at `path` right now. */\n\texists: boolean;\n}\n\n/**\n * Resolve one file inside the config directory. Prefers the current location, falls back to\n * an existing legacy file **in place**, and otherwise points at the current location so new\n * files are created there.\n */\nexport function resolveConfigFile(\n\tfileName: string,\n\toptions: ConfigPathOptions = {},\n): ResolvedConfigFile {\n\tconst dir = configDir(options);\n\tconst current = resolve(dir, fileName);\n\tif (existsSync(current))\n\t\treturn { path: current, dir, isLegacy: false, exists: true };\n\n\tconst legacyDir = legacyConfigDir(options);\n\tif (legacyDir) {\n\t\tconst legacy = resolve(legacyDir, fileName);\n\t\tif (existsSync(legacy))\n\t\t\treturn {\n\t\t\t\tpath: legacy,\n\t\t\t\tdir: legacyDir,\n\t\t\t\tisLegacy: true,\n\t\t\t\texists: true,\n\t\t\t};\n\t}\n\n\treturn { path: current, dir, isLegacy: false, exists: false };\n}\n\n/** `$XDG_CONFIG_HOME`, else `<home>/.config`. Falls back to a relative `.config` with no home. */\nfunction configHome(env: NodeJS.ProcessEnv): string {\n\tconst xdg = nonEmpty(env.XDG_CONFIG_HOME);\n\tif (xdg) return xdg;\n\tconst home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);\n\treturn home ? join(home, \".config\") : \".config\";\n}\n\nfunction explicitDir(options: ConfigPathOptions): string | undefined {\n\tconst env = options.env ?? process.env;\n\treturn (\n\t\tnonEmpty(options.dir) ??\n\t\tnonEmpty(env.NEON_CONFIG_DIR) ??\n\t\tnonEmpty(env.NEONCTL_CONFIG_DIR)\n\t);\n}\n\nfunction nonEmpty(value: string | undefined): string | undefined {\n\tif (typeof value !== \"string\") return undefined;\n\tconst trimmed = value.trim();\n\treturn trimmed === \"\" ? undefined : trimmed;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,MAAa,kBAAkB;;AAG/B,MAAa,yBAAyB;;AAatC,SAAgB,UAAU,UAA6B,CAAC,GAAW;CAClE,MAAM,WAAW,YAAY,OAAO;CACpC,IAAI,UAAU,OAAO;CACrB,OAAO,KAAK,WAAW,QAAQ,OAAO,QAAQ,GAAG,GAAG,eAAe;AACpE;;;;;AAMA,SAAgB,gBACf,UAA6B,CAAC,GACT;CACrB,IAAI,YAAY,OAAO,GAAG,OAAO,KAAA;CACjC,OAAO,KAAK,WAAW,QAAQ,OAAO,QAAQ,GAAG,GAAG,sBAAsB;AAC3E;;;;;;AAkBA,SAAgB,kBACf,UACA,UAA6B,CAAC,GACT;CACrB,MAAM,MAAM,UAAU,OAAO;CAC7B,MAAM,UAAU,QAAQ,KAAK,QAAQ;CACrC,IAAI,WAAW,OAAO,GACrB,OAAO;EAAE,MAAM;EAAS;EAAK,UAAU;EAAO,QAAQ;CAAK;CAE5D,MAAM,YAAY,gBAAgB,OAAO;CACzC,IAAI,WAAW;EACd,MAAM,SAAS,QAAQ,WAAW,QAAQ;EAC1C,IAAI,WAAW,MAAM,GACpB,OAAO;GACN,MAAM;GACN,KAAK;GACL,UAAU;GACV,QAAQ;EACT;CACF;CAEA,OAAO;EAAE,MAAM;EAAS;EAAK,UAAU;EAAO,QAAQ;CAAM;AAC7D;;AAGA,SAAS,WAAW,KAAgC;CACnD,MAAM,MAAM,SAAS,IAAI,eAAe;CACxC,IAAI,KAAK,OAAO;CAChB,MAAM,OAAO,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,WAAW;CAC3D,OAAO,OAAO,KAAK,MAAM,SAAS,IAAI;AACvC;AAEA,SAAS,YAAY,SAAgD;CACpE,MAAM,MAAM,QAAQ,OAAO,QAAQ;CACnC,OACC,SAAS,QAAQ,GAAG,KACpB,SAAS,IAAI,eAAe,KAC5B,SAAS,IAAI,kBAAkB;AAEjC;AAEA,SAAS,SAAS,OAA+C;CAChE,IAAI,OAAO,UAAU,UAAU,OAAO,KAAA;CACtC,MAAM,UAAU,MAAM,KAAK;CAC3B,OAAO,YAAY,KAAK,KAAA,IAAY;AACrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neon/config",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Config-as-Code for Neon. Define a `neon.ts` policy and inspect/diff/deploy it against the Neon API as plain TypeScript functions.",
   "keywords": [
     "neon",
@@ -32,6 +32,11 @@
       "types": "./dist/v1.d.ts",
       "import": "./dist/v1.js",
       "default": "./dist/v1.js"
+    },
+    "./paths": {
+      "types": "./dist/paths.d.ts",
+      "import": "./dist/paths.js",
+      "default": "./dist/paths.js"
     }
   },
   "files": [