@namzu/cli 12.1.0 → 13.0.0

package/dist/config/load.d.ts

@@ -1,21 +1,25 @@
 /**
- * Config cascade for @namzu/cli (M0 scaffolding).
+ * Config cascade and runtime admission for @namzu/cli.
  *
  * Resolution order (highest priority first):
- *   1. CLI flags (handled by Commander, merged in `bin.ts`)
+ *   1. CLI flags (handled by Commander, merged in `cli.ts`)
  *   2. Environment variables prefixed `NAMZU_`
  *   3. Project config: `./namzu.config.json` (TS variant added in a later
  *      milestone when a build step is justified)
  *   4. User config: `~/.namzu/config.yaml`
  *   5. Built-in defaults from `schema.ts`
  *
- * In M0 we wire steps 2, 3, 4, 5. CLI-flag merging happens in `bin.ts`
- * where Commander knows what was explicitly set vs defaulted.
+ * This module owns steps 2–5. CLI-flag merging happens in `cli.ts`, where
+ * Commander knows what was explicitly set rather than merely defaulted.
  *
  * A file that is not there contributes nothing, and that is a default. A file
  * that IS there and cannot be read throws {@link ConfigLoadError} — this loader
  * has no way to say "some of your settings", and will not pretend the ones it
  * failed to read were never written.
+ *
+ * A source Namzu can parse but whose known key carries an invalid value throws
+ * {@link ConfigValueError}. Absence, syntax failure, and semantic rejection are
+ * three different states and none is represented by another.
  */
 import { type NamzuCliConfig } from './schema.js';
 export interface LoadConfigOptions {
@@ -25,7 +29,37 @@ export interface LoadConfigOptions {
     readonly cwd?: string;
     /** Replacement env source (testing). */
     readonly env?: NodeJS.ProcessEnv;
+    /**
+     * Which profile to apply, if any.
+     *
+     * A name that no file declares is an ERROR rather than a no-op. Someone
+     * who typed `--profile revew` is running under settings they did not
+     * choose, and every reading of the run after that is wrong; the cost of
+     * refusing is one retyped word.
+     */
+    readonly profile?: string;
+    /** Overridable for tests; defaults to {@link MANAGED_CONFIG_PATH}. */
+    readonly managedPath?: string;
 }
+/**
+ * A machine-wide config that wins the cascade.
+ *
+ * It exists for the case where the person running namzu is not the person
+ * deciding what it may do — a shared build machine, a managed workstation.
+ * Applied LAST, so it beats the project file and the environment both, which
+ * is the only ordering that makes it worth having.
+ *
+ * **Its guarantee is the file system's and nothing more.** namzu does not
+ * verify a signature, does not check an owner, and cannot tell an
+ * administrator's file from one the user wrote there. What stops a user
+ * editing it is that the path needs privileges they do not have, on a machine
+ * somebody configured that way. That is a real control and a narrow one, and
+ * stating it precisely is the difference between a security boundary and the
+ * appearance of one.
+ *
+ * Absent on almost every machine, which is the expected case and not an error.
+ */
+export declare const MANAGED_CONFIG_PATH: string;
 /**
  * A config value's source, one variant per cascade layer.
  *
@@ -44,9 +78,26 @@ export type ConfigSource = {
 } | {
     readonly kind: 'project-file';
     readonly path: string;
+}
+/**
+ * A selected profile, and the file it was declared in.
+ *
+ * Both are named because neither alone answers the question an operator
+ * asks here. "profile" does not say which file to open, and the path does
+ * not say which of that file's profiles is in force.
+ */
+ | {
+    readonly kind: 'profile';
+    readonly name: string;
+    readonly path: string;
 } | {
     readonly kind: 'env';
     readonly variable: string;
+}
+/** A machine-wide file that wins the cascade; see `MANAGED_CONFIG_PATH`. */
+ | {
+    readonly kind: 'managed';
+    readonly path: string;
 };
 /**
  * Which `ConfigSource` won each key of the resolved config.
@@ -74,6 +125,17 @@ export declare function loadConfigWithProvenance(opts?: LoadConfigOptions): {
     config: NamzuCliConfig;
     provenance: ConfigProvenance;
 };
+/**
+ * Resolve only process/user/managed authority before a project is trusted.
+ *
+ * Internal CLI seam: deliberately not re-exported from the package root. A
+ * selected profile may be declared by the project layer, so an otherwise
+ * unknown profile is deferred until the trusted, full resolution pass.
+ */
+export declare function loadBootstrapConfigWithProvenance(opts?: LoadConfigOptions): {
+    config: NamzuCliConfig;
+    provenance: ConfigProvenance;
+};
 export declare function loadConfig(opts?: LoadConfigOptions): NamzuCliConfig;
 /**
  * A config file namzu could not read.
@@ -89,6 +151,28 @@ export declare class ConfigLoadError extends Error {
         cause?: unknown;
     });
 }
+/** The explicit source that supplied a semantically invalid config value. */
+export type ConfigValueSource = {
+    readonly kind: 'file';
+    readonly path: string;
+} | {
+    readonly kind: 'environment';
+    readonly variable: string;
+};
+/**
+ * A known config key whose explicit value does not satisfy its public type.
+ *
+ * Kept distinct from {@link ConfigLoadError}: that class means a file could
+ * not be read or parsed at all, while this one means the source was readable
+ * and named a setting Namzu cannot honour. Public loaders throw both; the
+ * standalone binary maps both to `EX_CONFIG`.
+ */
+export declare class ConfigValueError extends Error {
+    readonly source: ConfigValueSource;
+    /** Dot/bracket path to the invalid known setting, without its source. */
+    readonly settingPath: string;
+    constructor(source: ConfigValueSource, settingPath: string, message: string);
+}
 /**
  * Which `NAMZU_*` variable a field reads from, or `undefined` when env does
  * not set it at all.

package/dist/config/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjE,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,gEAAgE;IAChE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,wCAAwC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAChC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,CAAC,IAAI,MAAM,cAAc,CAAC,CAAC,EAAE,YAAY;CACnD,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,GAAE,iBAAsB,GAAG;IACvE,MAAM,EAAE,cAAc,CAAA;IACtB,UAAU,EAAE,gBAAgB,CAAA;CAC5B,CAgCA;AAED,wBAAgB,UAAU,CAAC,IAAI,GAAE,iBAAsB,GAAG,cAAc,CAEvE;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACzC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKxE;AA8LD;;;;;;;;;;GAUG;AACH,KAAK,gBAAgB,GAAG;IACvB,QAAQ,EAAE,CAAC,IAAI,MAAM,QAAQ,CAAC,cAAc,CAAC,GAAG,MAAM,GAAG,SAAS;CAClE,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,gBAWhC,CAAA"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"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"}