@crustjs/core 0.3.5 → 0.4.0

package/dist/{context-BPR700gY.d.ts → context-B1ck_WZ-.d.ts}

@@ -478,6 +478,10 @@ interface FlagSnapshot {
   readonly choices?: readonly string[];
   /** Declared default value; `URL` defaults are serialized to their `href` string. */
   readonly default?: unknown;
+  /** Declared environment binding; never contains the variable's value. */
+  readonly env?: Readonly<NonNullable<FlagDef["env"]>>;
+  /** Delimiter that splits string argv values of a repeatable flag into occurrences. */
+  readonly delimiter?: string;
 }
 /**
  * A readonly, serializable description of a command, exposed across public
@@ -1625,16 +1629,42 @@ interface FlagDefBase {
   /** Not supported with core value options — see {@link SchemaStringFlagDef} */
   schema?: never;
 }
-/** Base for single-value flags — `multiple` must be omitted */
-interface SingleFlagBase extends FlagDefBase {
+/** Environment fallback for terminal parsing; structured `run()` never reads it. */
+interface FlagEnvBinding {
+  /** Variable consulted only when argv omits the flag; help shows its name, never its value. */
+  name: string;
+  /** Split environment text into occurrences; independent of the argv delimiter, repeatable flags only. */
+  delimiter?: string;
+}
+/** Occurrence fields of a single-value flag — `multiple` and `delimiter` must be omitted. */
+interface SingleOccurrenceFields {
+  /** Environment fallback; argv wins over env, which wins over the default. */
+  env?: FlagEnvBinding & {
+    delimiter?: never;
+  };
   /** Must be omitted for single-value flags — set to `true` for multi-value */
   multiple?: never;
+  /** Only repeatable flags split values — see {@link RepeatableOccurrenceFields} */
+  delimiter?: never;
 }
-/** Base for multi-value flags — `multiple` is required as `true` */
-interface MultiFlagBase extends FlagDefBase {
+/** Occurrence fields of a repeatable flag — `multiple` is required as `true`. */
+interface RepeatableOccurrenceFields {
+  /** Environment fallback; text is one occurrence unless `env.delimiter` is set. */
+  env?: FlagEnvBinding;
   /** Collect repeated values into an array */
   multiple: true;
+  /**
+   * Split each string argv value into separate occurrences
+   * (`--tags a,b` with `","` is two occurrences). Empty segments are dropped.
+   * Boolean argv switches stay booleans. Environment text uses `env.delimiter`.
+   * Opt-in with no default; structured `run()` arrays are never split.
+   */
+  delimiter?: string;
 }
+/** Base for single-value flags — `multiple` must be omitted */
+interface SingleFlagBase extends FlagDefBase, SingleOccurrenceFields {}
+/** Base for multi-value flags — `multiple` is required as `true` */
+interface MultiFlagBase extends FlagDefBase, RepeatableOccurrenceFields {}
 type StringFlagFields<Default, ParseOutput> = {
   /** Default string value, or string array for a multi-value flag. */
   default?: Default;
@@ -1688,23 +1718,19 @@ interface SchemaFlagBase extends Omit<FlagDefBase, "schema" | "required"> {
  * `string[] | undefined` with `multiple: true`) and exclusively owns coercion,
  * defaults, requiredness, and validation. `type` declares token consumption only.
  */
-interface SchemaStringFlagDef extends SchemaFlagBase {
+type SchemaStringFlagDef = SchemaFlagBase & {
   type: "string";
-  /** When `true`, the schema receives `string[]` when present, or `undefined` when omitted. */
-  multiple?: true;
   noNegate?: never;
-}
+} & (SingleOccurrenceFields | RepeatableOccurrenceFields);
 /**
  * A schema-backed toggle flag (no value token). The schema receives the raw
  * `boolean | undefined` (or `boolean[] | undefined` with `multiple: true`).
  */
-interface SchemaBooleanFlagDef extends SchemaFlagBase {
+type SchemaBooleanFlagDef = SchemaFlagBase & {
   type: "boolean";
-  /** When `true`, the schema receives `boolean[]` when present, or `undefined` when omitted. */
-  multiple?: true;
   /** When `true`, reject `--no-{name}` (and negated aliases) at parse time and hide the generated help label */
   noNegate?: true;
-}
+} & (SingleOccurrenceFields | RepeatableOccurrenceFields);
 /**
  * Defines a single named flag for a CLI command.
  *

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as CrustErrorCode, A as SectionConsumer, At as MergeContext, B as ExtensionContext, C as InvocationOptions, Ct as ArgSnapshot, D as ParsedArgValue, Dt as LocalFlagNameBrand, E as ParseResult, Et as LocalFlagBrand, F as BuildReport, G as Finished, H as ExtensionFlagDef, I as DefineExtensionWith, J as NamedExtensionFlagDef, K as InferExtensionFlags, L as Extension, M as ValueType, Mt as defineExtensionId, N as BuildArtifacts, O as ParsedFlagValue, Ot as EmptyArgNameBrand, P as BuildFile, Q as CrustError, R as ExtensionBuildContext, S as InvocationIO, St as defineCommand, T as NamedFlagDef, Tt as FlagSnapshot, U as ExtensionHooks, V as ExtensionFactory, W as ExtensionSectionContribution, X as defineExtension, Y as RootMetaKey, Z as CommandNotFoundErrorDetails, _ as ExecuteOptions, _t as RootCommandMeta, a as ContextInstance, at as ValidationErrorDetails, b as InputArgs, bt as RunInputArguments, c as FactoryValueOf, ct as CommandDefinition, d as ArgDef, dt as CommandPath, et as CrustErrorDetails, f as ArgsDef, ft as CommandShape, gt as CrustCommandContext, h as CommandSectionInput, ht as Crust, i as ContextFactory, it as ParseErrorDetails, j as ValidatedInput, jt as ExtensionId, k as SectionAudience, kt as LocalValueBrand, l as contextSources, lt as CommandDefinitionBuilder, m as CommandSection, mt as CommandTree, n as ContextBag, nt as CrustErrorJson, o as ContextMap, ot as AnyCrust, p as CommandMeta, pt as CommandShapeAt, q as InvocationOutcome, r as ContextConfig, rt as DefinitionErrorDetails, s as ContextSetup, st as CommandConfig, t as AnyContextFactory, tt as CrustErrorDetailsMap, u as defineContext, ut as CommandHandle, v as FlagDef, vt as RunArguments, w as MergeFlags, wt as CommandSnapshot, x as InputFlags, xt as RunOutcome, y as FlagsDef, yt as RunInput, z as ExtensionConfig } from "./context-BPR700gY.js";
+import { $ as CrustErrorCode, A as SectionConsumer, At as MergeContext, B as ExtensionContext, C as InvocationOptions, Ct as ArgSnapshot, D as ParsedArgValue, Dt as LocalFlagNameBrand, E as ParseResult, Et as LocalFlagBrand, F as BuildReport, G as Finished, H as ExtensionFlagDef, I as DefineExtensionWith, J as NamedExtensionFlagDef, K as InferExtensionFlags, L as Extension, M as ValueType, Mt as defineExtensionId, N as BuildArtifacts, O as ParsedFlagValue, Ot as EmptyArgNameBrand, P as BuildFile, Q as CrustError, R as ExtensionBuildContext, S as InvocationIO, St as defineCommand, T as NamedFlagDef, Tt as FlagSnapshot, U as ExtensionHooks, V as ExtensionFactory, W as ExtensionSectionContribution, X as defineExtension, Y as RootMetaKey, Z as CommandNotFoundErrorDetails, _ as ExecuteOptions, _t as RootCommandMeta, a as ContextInstance, at as ValidationErrorDetails, b as InputArgs, bt as RunInputArguments, c as FactoryValueOf, ct as CommandDefinition, d as ArgDef, dt as CommandPath, et as CrustErrorDetails, f as ArgsDef, ft as CommandShape, gt as CrustCommandContext, h as CommandSectionInput, ht as Crust, i as ContextFactory, it as ParseErrorDetails, j as ValidatedInput, jt as ExtensionId, k as SectionAudience, kt as LocalValueBrand, l as contextSources, lt as CommandDefinitionBuilder, m as CommandSection, mt as CommandTree, n as ContextBag, nt as CrustErrorJson, o as ContextMap, ot as AnyCrust, p as CommandMeta, pt as CommandShapeAt, q as InvocationOutcome, r as ContextConfig, rt as DefinitionErrorDetails, s as ContextSetup, st as CommandConfig, t as AnyContextFactory, tt as CrustErrorDetailsMap, u as defineContext, ut as CommandHandle, v as FlagDef, vt as RunArguments, w as MergeFlags, wt as CommandSnapshot, x as InputFlags, xt as RunOutcome, y as FlagsDef, yt as RunInput, z as ExtensionConfig } from "./context-B1ck_WZ-.js";
 import { resolveArtifactDir } from "@crustjs/utils/artifacts";
 //#region src/api/flags.d.ts
 /** Distribute `Omit<_, "name">` over the {@link ArgDef} union. */
@@ -7,13 +7,13 @@ type OmitName<T> = T extends {
 } ? Omit<T, "name"> : never;
 /** A positional argument definition without its name — the `defineArg` input shape. */
 type UnnamedArgDef = OmitName<ArgDef>;
-type Frozen<T> = { readonly [K in keyof T]: K extends "aliases" | "choices" | (T extends {
+type Frozen<T> = { readonly [K in keyof T]: K extends "aliases" | "choices" | "env" | (T extends {
   multiple: true;
 } ? "default" : never) ? Readonly<T[K]> : T[K]; };
 type Named<N extends string, D> = D extends unknown ? Frozen<{
   name: N;
 } & D> : never;
-/** Define and own one flag locally; attachment checks destination collisions. */
+/** Define and own one flag locally, including its readonly env binding; attachment checks destination collisions. */
 export declare function defineFlag<const N extends string, const D extends FlagDef>(name: N & LocalFlagNameBrand<N>, def: D & LocalFlagBrand<{
   name: N;
 } & D>): Named<N, D>;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as CrustError, S as normalizeFlag, _ as contextSources, a as runInvocation, b as validateContextAvailability, d as cloneFlagRegistry, f as installExtensionContexts, g as defineExtension, h as registerFlag, i as resolveTypedPath, m as createCommandNode, n as executeInvocation, o as snapshotCommand, p as validateCommandSections, r as prepareInvocation, u as cloneCommandNode, v as defineContext, x as normalizeArg, y as definingOf } from "./invocation-BaWf5POY.js";
+import { C as CrustError, S as normalizeFlag, _ as contextSources, a as runInvocation, b as validateContextAvailability, d as cloneFlagRegistry, f as installExtensionContexts, g as defineExtension, h as registerFlag, i as resolveTypedPath, m as createCommandNode, n as executeInvocation, o as snapshotCommand, p as validateCommandSections, r as prepareInvocation, u as cloneCommandNode, v as defineContext, x as normalizeArg, y as definingOf } from "./invocation-ka-BNJKZ.js";
 import { resolveArtifactDir } from "@crustjs/utils/artifacts";
 //#region src/identity.ts
 /** Mint an Extension identity from any non-blank, trimmed string. */

package/dist/{invocation-BaWf5POY.js → invocation-ka-BNJKZ.js}

@@ -115,9 +115,16 @@ function ownDefinition(def) {
 		...def,
 		..."aliases" in def && def.aliases ? { aliases: Object.freeze([...def.aliases]) } : {},
 		...def.choices ? { choices: Object.freeze([...def.choices]) } : {},
+		..."env" in def && def.env ? { env: Object.freeze({
+			name: def.env.name,
+			delimiter: def.env.delimiter
+		}) } : {},
 		..."multiple" in def && def.multiple && Array.isArray(def.default) ? { default: Object.freeze([...def.default]) } : {}
 	});
 }
+function isEnvBinding(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && "name" in value && typeof value.name === "string" && (!("delimiter" in value) || value.delimiter === void 0 || typeof value.delimiter === "string");
+}
 function normalizeFlag(name, def) {
 	assertUsableSpelling(name, "canonical");
 	if (def.short !== void 0) assertUsableSpelling(def.short, "short");
@@ -129,6 +136,29 @@ function normalizeFlag(name, def) {
 		reason: "flag-collision"
 	});
 	if (def.short !== void 0 && def.short.length !== 1) throw new CrustError("DEFINITION", "Short flags must be one character");
+	if (def.env !== void 0 && !isEnvBinding(def.env)) throw new CrustError("DEFINITION", `Flag "${name}" env must be an object with a string name and optional string delimiter`, {
+		subject: "flag",
+		name,
+		reason: "invalid-env"
+	});
+	if (def.env?.name === "") throw new CrustError("DEFINITION", `Flag "${name}" env variable name must be non-empty`, {
+		subject: "flag",
+		name,
+		reason: "empty-env"
+	});
+	for (const [field, delimiter] of [["delimiter", def.delimiter], ["env.delimiter", def.env?.delimiter]]) {
+		if (delimiter === void 0) continue;
+		if (!def.multiple) throw new CrustError("DEFINITION", `Flag "${name}" ${field} requires multiple: true`, {
+			subject: "flag",
+			name,
+			reason: "delimiter-without-multiple"
+		});
+		if (delimiter === "") throw new CrustError("DEFINITION", `Flag "${name}" ${field} must be non-empty`, {
+			subject: "flag",
+			name,
+			reason: "empty-delimiter"
+		});
+	}
 	return ownDefinition(def);
 }
 function normalizeArg(def) {
@@ -814,6 +844,60 @@ function resolveAliases(tokens, spellings) {
 	}
 	return canonical;
 }
+/** Split repeatable occurrences on the declared delimiter, dropping empty segments. */
+function splitOccurrences(values, delimiter) {
+	if (delimiter === void 0) return [...values];
+	return values.flatMap((value) => value.split(delimiter)).filter((value) => value !== "");
+}
+/**
+* Convert an environment value into the shape argv tokens produce, so the
+* shared coercion path (`choices`, `parse`, type conversion, schemas) runs
+* identically. Booleans use the positional spelling rule (`true`/`1`);
+* a `noNegate` flag rejects a false value like it rejects `--no-<name>`.
+*/
+function envFlagValue(name, def, raw) {
+	const occurrences = def.multiple ? splitOccurrences([raw], def.env?.delimiter) : [raw];
+	if (def.multiple && occurrences.length === 0) return void 0;
+	if (def.type !== "boolean") return {
+		kind: "string",
+		value: def.multiple ? occurrences : raw
+	};
+	const values = occurrences.map(coerceBooleanString);
+	if ("noNegate" in def && def.noNegate && values.includes(false)) throw new CrustError("PARSE", `Flag "--${name}" does not support negation (from ${def.env?.name})`);
+	return {
+		kind: "boolean",
+		value: def.multiple ? values : values[0]
+	};
+}
+/**
+* Select each flag's source: argv > `env` > `default`.
+*
+* Source selection looks at explicit argv presence *before* delimiter
+* splitting, so `--tags ""` stays an argv value (zero occurrences, then
+* default/required rules) instead of letting a stale environment variable
+* override an explicit request. Environment lookup is argv-only; structured
+* `run()` input never reaches this function.
+*/
+function applyEnvAndDelimiter(flagsDef, argvValues, env) {
+	const values = {};
+	for (const [name, def] of Object.entries(flagsDef)) {
+		const argvValue = Object.hasOwn(argvValues, name) ? argvValues[name] : void 0;
+		if (argvValue !== void 0) {
+			if (def.delimiter !== void 0 && argvValue.kind === "string" && Array.isArray(argvValue.value)) {
+				const occurrences = splitOccurrences(argvValue.value, def.delimiter);
+				values[name] = occurrences.length === 0 ? void 0 : {
+					kind: "string",
+					value: occurrences
+				};
+			} else values[name] = argvValue;
+			continue;
+		}
+		if (def.env === void 0 || !Object.hasOwn(env, def.env.name)) continue;
+		const raw = env[def.env.name];
+		if (raw !== void 0) values[name] = envFlagValue(name, def, raw);
+	}
+	return values;
+}
 /**
 * Resolve all flag definitions against the canonical parsed values.
 * Handles coercion and default values.
@@ -990,12 +1074,13 @@ function bind(command, positionals, flagValues, coerceArg, coerceFlag) {
 *
 * @param command - The command whose arg/flag definitions drive the parsing
 * @param argv - The argv array to parse (typically `process.argv.slice(2)`)
+* @param env - Environment consulted for `FlagDef.env` fallbacks; pass `{}` to parse without one
 * @returns Parsed args, flags, excessArgs (positionals before `--` not consumed by a declared argument), and rawArgs (everything after `--`)
 * @throws {CrustError} On unknown flags or type coercion failure
 */
-function parseArgs$1(command, argv) {
+function parseArgs$1(command, argv, env = process.env) {
 	const { positionals, flagValues, rawArgs } = tokenizeArgv(command, argv);
-	const { args, flags, consumed } = bind(command, positionals, flagValues, coerceArgToken, coerceFlagValue);
+	const { args, flags, consumed } = bind(command, positionals, applyEnvAndDelimiter(command.effectiveFlags, flagValues, env), coerceArgToken, coerceFlagValue);
 	return {
 		args,
 		flags,
@@ -1178,7 +1263,12 @@ function snapshotFlag(def) {
 		negatable: isFlagNegatable(def),
 		noNegate: "noNegate" in def ? def.noNegate : void 0,
 		choices: def.choices ? Object.freeze([...def.choices]) : void 0,
-		default: serializableDefault(def.default)
+		default: serializableDefault(def.default),
+		env: def.env ? freezeCompact({
+			name: def.env.name,
+			delimiter: def.env.delimiter
+		}) : void 0,
+		delimiter: def.delimiter
 	});
 }
 /**

package/dist/tooling.d.ts

@@ -1,4 +1,4 @@
-import { Tt as FlagSnapshot, g as DeclaredDefault, jt as ExtensionId, m as CommandSection, wt as CommandSnapshot } from "./context-BPR700gY.js";
+import { Tt as FlagSnapshot, g as DeclaredDefault, jt as ExtensionId, m as CommandSection, wt as CommandSnapshot } from "./context-B1ck_WZ-.js";
 import { BUILD_OUT_DIR_ENV } from "@crustjs/utils/artifacts";
 //#region src/command/invocation.d.ts
 /**
@@ -17,8 +17,11 @@ export declare const SNAPSHOT_PATH_ENV = "CRUST_INTERNAL_SNAPSHOT_PATH";
 //#region src/command/documentation.d.ts
 /** Format a declared default value for command documentation. */
 export declare function formatDefault(value: DeclaredDefault): string;
-/** Format a definition's description and optional default/choice annotations. */
-export declare function formatDescription(description: string | undefined, defaultValue: DeclaredDefault, choices: readonly string[] | undefined, formatAnnotation?: (annotation: string) => string): string;
+/**
+ * Format a definition's description and optional env/default/choice annotations.
+ * `env` is the variable *name* only; renderers never see its value.
+ */
+export declare function formatDescription(description: string | undefined, defaultValue: DeclaredDefault, choices: readonly string[] | undefined, formatAnnotation?: (annotation: string) => string, env?: string): string;
 /**
  * Presentation-ready view of one positional argument.
  *
@@ -90,6 +93,10 @@ interface DocumentationFlag {
   readonly choices?: readonly string[];
   /** Default value used when the flag is omitted, e.g. `false`. */
   readonly default?: unknown;
+  /** Declared environment binding; never contains the variable's value. */
+  readonly env?: FlagSnapshot["env"];
+  /** Delimiter that splits string argv values of a repeatable flag into occurrences. */
+  readonly delimiter?: string;
 }
 /**
  * One renderer-colorable piece of a usage line. `custom` is the sole segment

package/dist/tooling.js

@@ -1,4 +1,4 @@
-import { c as sectionsFor, l as visibleSectionsFor, s as isListed, t as SNAPSHOT_PATH_ENV } from "./invocation-BaWf5POY.js";
+import { c as sectionsFor, l as visibleSectionsFor, s as isListed, t as SNAPSHOT_PATH_ENV } from "./invocation-ka-BNJKZ.js";
 import { BUILD_OUT_DIR_ENV } from "@crustjs/utils/artifacts";
 //#region src/command/documentation.ts
 function isNonFiniteNumber(value) {
@@ -10,9 +10,13 @@ function formatDefault(value) {
 	if (Array.isArray(value)) return value.map(String).join(", ");
 	return JSON.stringify(value) ?? String(value);
 }
-/** Format a definition's description and optional default/choice annotations. */
-function formatDescription(description, defaultValue, choices, formatAnnotation = (annotation) => annotation) {
+/**
+* Format a definition's description and optional env/default/choice annotations.
+* `env` is the variable *name* only; renderers never see its value.
+*/
+function formatDescription(description, defaultValue, choices, formatAnnotation = (annotation) => annotation, env) {
 	const parts = description ? [description] : [];
+	if (env !== void 0) parts.push(formatAnnotation(`[env: ${env}]`));
 	if (defaultValue !== void 0) parts.push(formatAnnotation(`[default: ${formatDefault(defaultValue)}]`));
 	if (choices?.length) parts.push(formatAnnotation(`[choices: ${choices.join(", ")}]`));
 	return parts.join(" ");
@@ -39,7 +43,9 @@ function documentationFlags(flags) {
 			required: def.required === true,
 			multiple: def.multiple === true,
 			choices: def.choices,
-			default: def.default
+			default: def.default,
+			env: def.env,
+			delimiter: def.delimiter
 		});
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/core",
-	"version": "0.3.5",
+	"version": "0.4.0",
 	"description": "Core library for the Crust CLI framework",
 	"type": "module",
 	"sideEffects": false,