@cleocode/lafs 2026.3.74 → 2026.4.3

package/dist/src/fieldExtraction.js

@@ -1,19 +1,55 @@
-import { LAFSFlagError } from "./flagSemantics.js";
-import { isMVILevel } from "./types.js";
+/**
+ * Field extraction resolution for LAFS envelopes.
+ *
+ * Implements section 9.2 of the LAFS spec: `--field` extracts a single value
+ * as plain text (no envelope), `--fields` filters the JSON envelope to a subset,
+ * and `--mvi` controls envelope verbosity.
+ *
+ * @remarks
+ * This module provides both resolution (flag parsing) and runtime extraction/filtering
+ * functions. The resolution layer is consumed by the unified resolver in `flagResolver.ts`.
+ *
+ * @since 1.5.0
+ */
+import { LAFSFlagError } from './flagSemantics.js';
+import { isMVILevel } from './types.js';
+/**
+ * Resolve field extraction flags into a validated configuration.
+ *
+ * @param input - The field extraction flag inputs
+ * @returns The resolved extraction configuration with mvi level and source
+ *
+ * @remarks
+ * Parses and validates the `--field`, `--fields`, and `--mvi` flags. Throws
+ * `E_FIELD_CONFLICT` if both `--field` and `--fields` are provided. The `'custom'`
+ * MVI level is server-set per section 9.1 and is rejected as a client-requested value;
+ * invalid or absent `--mvi` falls back to `'minimal'`.
+ *
+ * @example
+ * ```ts
+ * const resolution = resolveFieldExtraction({ fieldsFlag: 'id,title' });
+ * // => { fields: ['id', 'title'], mvi: 'minimal', mviSource: 'default', expectsCustomMvi: true }
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When both `fieldFlag` and `fieldsFlag` are set.
+ */
 export function resolveFieldExtraction(input) {
     if (input.fieldFlag && input.fieldsFlag) {
-        throw new LAFSFlagError('E_FIELD_CONFLICT', 'Cannot combine --field and --fields: --field extracts a single value '
-            + 'as plain text (no envelope); --fields filters the JSON envelope. '
-            + 'Use one or the other.', { conflictingModes: ['single-field-extraction', 'multi-field-filter'] });
+        throw new LAFSFlagError('E_FIELD_CONFLICT', 'Cannot combine --field and --fields: --field extracts a single value ' +
+            'as plain text (no envelope); --fields filters the JSON envelope. ' +
+            'Use one or the other.', { conflictingModes: ['single-field-extraction', 'multi-field-filter'] });
     }
     const fields = typeof input.fieldsFlag === 'string'
-        ? input.fieldsFlag.split(',').map(f => f.trim()).filter(Boolean)
+        ? input.fieldsFlag
+            .split(',')
+            .map((f) => f.trim())
+            .filter(Boolean)
         : Array.isArray(input.fieldsFlag)
-            ? input.fieldsFlag.map(f => f.trim()).filter(Boolean)
+            ? input.fieldsFlag.map((f) => f.trim()).filter(Boolean)
             : undefined;
     // 'custom' is server-set (§9.1) — not a client-requestable level
     const validMvi = isMVILevel(input.mviFlag) && input.mviFlag !== 'custom';
-    const mvi = validMvi ? input.mviFlag : 'standard';
+    const mvi = validMvi ? input.mviFlag : 'minimal';
     const mviSource = validMvi ? 'flag' : 'default';
     const hasFields = (fields?.length ?? 0) > 0;
     return {
@@ -27,20 +63,29 @@ export function resolveFieldExtraction(input) {
 /**
  * Extract a named field from a LAFS result object.
  *
+ * @param result - The envelope result value (object, array, or null)
+ * @param field - The field name to extract
+ * @returns The extracted value, or `undefined` if not found at any level
+ *
+ * @remarks
  * Handles four result shapes:
- *   1. Direct array: result[0][field]       (list operations where result IS an array)
- *   2. Direct:       result[field]          (flat result object)
- *   3. Nested:       result.<key>[field]    (wrapper-entity, e.g. result.task.title)
- *   4. Array value:  result.<key>[0][field] (wrapper-array, e.g. result.items[0].title)
+ *   1. Direct array: `result[0][field]` (list operations where result IS an array)
+ *   2. Direct: `result[field]` (flat result object)
+ *   3. Nested: `result.<key>[field]` (wrapper-entity, e.g. `result.task.title`)
+ *   4. Array value: `result.<key>[0][field]` (wrapper-array, e.g. `result.items[0].title`)
  *
  * Returns the value from the first match only. For array results (shapes 1
  * and 4), returns the first element's field value only. To extract from all
- * elements, iterate the array or use applyFieldFilter().
+ * elements, iterate the array or use {@link applyFieldFilter}.
  *
  * When multiple wrapper keys contain the requested field (shapes 3 and 4),
  * the first key in property insertion order wins.
  *
- * Returns undefined if not found at any level.
+ * @example
+ * ```ts
+ * const result = { task: { id: 'T1', title: 'Fix bug' } };
+ * extractFieldFromResult(result, 'title'); // => 'Fix bug'
+ * ```
  */
 export function extractFieldFromResult(result, field) {
     if (result === null || typeof result !== 'object')
@@ -73,33 +118,60 @@ export function extractFieldFromResult(result, field) {
     }
     return undefined;
 }
-/** Convenience wrapper — extracts a field from an envelope's result. */
+/**
+ * Extract a named field from an envelope's result.
+ *
+ * @param envelope - The LAFS envelope to extract from
+ * @param field - The field name to extract
+ * @returns The extracted value, or `undefined` if not found
+ *
+ * @remarks
+ * Convenience wrapper around {@link extractFieldFromResult} that accepts
+ * the full envelope and delegates to the result extraction logic.
+ *
+ * @example
+ * ```ts
+ * const value = extractFieldFromEnvelope(envelope, 'title');
+ * ```
+ */
 export function extractFieldFromEnvelope(envelope, field) {
     return extractFieldFromResult(envelope.result, field);
 }
 /**
  * Filter result fields in a LAFS envelope to the requested subset.
  *
- * Handles the same four result shapes as extractFieldFromResult:
- *   1. Direct array:    project each element
- *   2. Flat result:     project top-level keys
- *   3. Wrapper-entity:  project nested entity's keys, preserve wrapper
- *   4. Wrapper-array:   project each element's keys, preserve wrapper
+ * @param envelope - The LAFS envelope whose result will be filtered
+ * @param fields - Array of field names to retain in the result
+ * @returns A new envelope with the filtered result and `_meta.mvi` set to `'custom'`
  *
- * Sets _meta.mvi = 'custom' per §9.1.
- * Returns a new envelope with a new _meta object. Result values are not
+ * @remarks
+ * Handles the same four result shapes as {@link extractFieldFromResult}:
+ *   1. Direct array: project each element
+ *   2. Flat result: project top-level keys
+ *   3. Wrapper-entity: project nested entity's keys, preserve wrapper
+ *   4. Wrapper-array: project each element's keys, preserve wrapper
+ *
+ * Sets `_meta.mvi = 'custom'` per section 9.1.
+ * Returns a new envelope with a new `_meta` object. Result values are not
  * deep-cloned; nested object references are shared with the original.
- * Unknown field names are silently omitted per §9.2.
+ * Unknown field names are silently omitted per section 9.2.
  *
  * When result is a wrapper (shapes 3/4) with multiple keys, each key is
  * projected independently. Primitive values at the wrapper level (numbers,
- * strings, booleans) are preserved as-is — _fields is applied to nested
+ * strings, booleans) are preserved as-is; field filtering is applied to nested
  * entity or array keys only, not to the wrapper's own primitive keys.
+ *
+ * @example
+ * ```ts
+ * const filtered = applyFieldFilter(envelope, ['id', 'title']);
+ * // filtered.result contains only 'id' and 'title' fields
+ * // filtered._meta.mvi === 'custom'
+ * ```
  */
 export function applyFieldFilter(envelope, fields) {
     if (fields.length === 0 || envelope.result === null)
         return envelope;
-    const pick = (obj) => Object.fromEntries(fields.filter(f => f in obj).map(f => [f, obj[f]]));
+    const pick = (obj) => Object.fromEntries(fields.filter((f) => f in obj).map((f) => [f, obj[f]]));
     let filtered;
     if (Array.isArray(envelope.result)) {
         // Shape 1: direct array
@@ -107,7 +179,7 @@ export function applyFieldFilter(envelope, fields) {
     }
     else {
         const record = envelope.result;
-        const topLevelMatch = fields.some(f => f in record);
+        const topLevelMatch = fields.some((f) => f in record);
         if (topLevelMatch) {
             // Shape 2: flat result
             filtered = pick(record);
@@ -116,7 +188,7 @@ export function applyFieldFilter(envelope, fields) {
             // Shapes 3 & 4: wrapper — apply pick one level down, preserve wrapper keys
             filtered = Object.fromEntries(Object.entries(record).map(([k, v]) => {
                 if (Array.isArray(v)) {
-                    return [k, v.map(item => pick(item))];
+                    return [k, v.map((item) => pick(item))];
                 }
                 if (v && typeof v === 'object') {
                     return [k, pick(v)];
@@ -131,3 +203,4 @@ export function applyFieldFilter(envelope, fields) {
         result: filtered,
     };
 }
+//# sourceMappingURL=fieldExtraction.js.map

package/dist/src/fieldExtraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldExtraction.js","sourceRoot":"","sources":["../../src/fieldExtraction.ts"],"names":[],"mappings":"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"}

package/dist/src/flagResolver.d.ts

@@ -6,41 +6,108 @@
  *
  * @since 1.6.0
  */
-import { type FlagResolution } from './flagSemantics.js';
 import { type FieldExtractionResolution } from './fieldExtraction.js';
-/** Combined input for both format and field extraction layers. */
+import { type FlagResolution } from './flagSemantics.js';
+/**
+ * Combined input for both format and field extraction layers.
+ *
+ * @remarks
+ * Merges the format-layer flags (sections 5.1-5.3) with the field extraction
+ * flags (section 9.2) into a single input object for {@link resolveFlags}.
+ */
 export interface UnifiedFlagInput {
+    /**
+     * Request human-readable output (`--human` flag).
+     * @defaultValue undefined
+     */
     human?: boolean;
+    /**
+     * Request JSON output (`--json` flag).
+     * @defaultValue undefined
+     */
     json?: boolean;
+    /**
+     * Suppress non-essential output for scripting (`--quiet` flag).
+     * @defaultValue undefined
+     */
     quiet?: boolean;
+    /**
+     * Explicit format override, taking highest precedence in the format layer.
+     * @defaultValue undefined
+     */
     requestedFormat?: 'json' | 'human';
+    /**
+     * Project-level default format from configuration.
+     * @defaultValue undefined
+     */
     projectDefault?: 'json' | 'human';
+    /**
+     * User-level default format from configuration.
+     * @defaultValue undefined
+     */
     userDefault?: 'json' | 'human';
     /**
      * TTY detection hint. When true, defaults to human format if no
      * explicit format flag or project/user default is set.
      * CLI tools should pass `process.stdout.isTTY ?? false`.
+     * @defaultValue undefined
      */
     tty?: boolean;
+    /**
+     * Extract a single field as plain text, discarding the envelope (`--field` flag).
+     * @defaultValue undefined
+     */
     field?: string;
+    /**
+     * Filter result to these fields while preserving the envelope (`--fields` flag).
+     * Accepts a comma-separated string or an array of field names.
+     * @defaultValue undefined
+     */
     fields?: string | string[];
+    /**
+     * Requested MVI verbosity level (`--mvi` flag).
+     * @defaultValue undefined
+     */
     mvi?: string;
 }
-/** Combined resolution result with cross-layer warnings. */
+/**
+ * Combined resolution result with cross-layer warnings.
+ *
+ * @remarks
+ * Contains the independently resolved format and field extraction layers plus
+ * any cross-layer interaction warnings produced during validation (section 5.4).
+ */
 export interface UnifiedFlagResolution {
-    /** Resolved format layer. */
+    /** Resolved format layer from the format precedence chain. */
     format: FlagResolution;
-    /** Resolved field extraction layer. */
+    /** Resolved field extraction layer from field/fields/mvi flags. */
     fields: FieldExtractionResolution;
-    /** Warnings for cross-layer interactions (non-fatal). */
+    /** Warnings for cross-layer interactions (non-fatal, informational only). */
     warnings: string[];
 }
 /**
  * Resolve all flags across both layers and validate cross-layer semantics.
  *
- * Per §5.4, cross-layer combinations are valid but MAY produce warnings.
- * Format-layer conflicts (E_FORMAT_CONFLICT) and field-layer conflicts
- * (E_FIELD_CONFLICT) still throw as before — they are delegated to the
- * existing single-layer resolvers.
+ * @param input - Combined format and field extraction flags
+ * @returns The unified resolution containing format, fields, and any cross-layer warnings
+ *
+ * @remarks
+ * Delegates to {@link resolveOutputFormat} for the format layer and
+ * {@link resolveFieldExtraction} for the field extraction layer, then performs
+ * cross-layer validation per section 5.4. Cross-layer combinations are valid but
+ * MAY produce informational warnings. Format-layer conflicts (`E_FORMAT_CONFLICT`)
+ * and field-layer conflicts (`E_FIELD_CONFLICT`) still throw as before; they are
+ * delegated to the existing single-layer resolvers.
+ *
+ * @example
+ * ```ts
+ * const result = resolveFlags({ human: true, field: 'title' });
+ * // result.format => { format: 'human', source: 'flag', quiet: false }
+ * // result.fields => { field: 'title', mvi: 'minimal', ... }
+ * // result.warnings => ['Cross-layer: --human + --field "title". ...']
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When format or field layer flags conflict.
  */
 export declare function resolveFlags(input: UnifiedFlagInput): UnifiedFlagResolution;
+//# sourceMappingURL=flagResolver.d.ts.map

package/dist/src/flagResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flagResolver.d.ts","sourceRoot":"","sources":["../../src/flagResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,yBAAyB,EAA0B,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAE,KAAK,cAAc,EAAuB,MAAM,oBAAoB,CAAC;AAG9E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,MAAM,EAAE,cAAc,CAAC;IACvB,mEAAmE;IACnE,MAAM,EAAE,yBAAyB,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,qBAAqB,CAqC3E"}

package/dist/src/flagResolver.js

@@ -6,15 +6,31 @@
  *
  * @since 1.6.0
  */
-import { resolveOutputFormat } from './flagSemantics.js';
 import { resolveFieldExtraction } from './fieldExtraction.js';
+import { resolveOutputFormat } from './flagSemantics.js';
 /**
  * Resolve all flags across both layers and validate cross-layer semantics.
  *
- * Per §5.4, cross-layer combinations are valid but MAY produce warnings.
- * Format-layer conflicts (E_FORMAT_CONFLICT) and field-layer conflicts
- * (E_FIELD_CONFLICT) still throw as before — they are delegated to the
- * existing single-layer resolvers.
+ * @param input - Combined format and field extraction flags
+ * @returns The unified resolution containing format, fields, and any cross-layer warnings
+ *
+ * @remarks
+ * Delegates to {@link resolveOutputFormat} for the format layer and
+ * {@link resolveFieldExtraction} for the field extraction layer, then performs
+ * cross-layer validation per section 5.4. Cross-layer combinations are valid but
+ * MAY produce informational warnings. Format-layer conflicts (`E_FORMAT_CONFLICT`)
+ * and field-layer conflicts (`E_FIELD_CONFLICT`) still throw as before; they are
+ * delegated to the existing single-layer resolvers.
+ *
+ * @example
+ * ```ts
+ * const result = resolveFlags({ human: true, field: 'title' });
+ * // result.format => { format: 'human', source: 'flag', quiet: false }
+ * // result.fields => { field: 'title', mvi: 'minimal', ... }
+ * // result.warnings => ['Cross-layer: --human + --field "title". ...']
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When format or field layer flags conflict.
  */
 export function resolveFlags(input) {
     const formatInput = {
@@ -45,3 +61,4 @@ export function resolveFlags(input) {
     }
     return { format, fields, warnings };
 }
+//# sourceMappingURL=flagResolver.js.map

package/dist/src/flagResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flagResolver.js","sourceRoot":"","sources":["../../src/flagResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAkC,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9F,OAAO,EAAuB,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAkF9E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAuB;IAClD,MAAM,WAAW,GAAc;QAC7B,SAAS,EAAE,KAAK,CAAC,KAAK;QACtB,QAAQ,EAAE,KAAK,CAAC,IAAI;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,GAAG,EAAE,KAAK,CAAC,GAAG;KACf,CAAC;IACF,MAAM,MAAM,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAEhD,MAAM,UAAU,GAAyB;QACvC,SAAS,EAAE,KAAK,CAAC,KAAK;QACtB,UAAU,EAAE,KAAK,CAAC,MAAM;QACxB,OAAO,EAAE,KAAK,CAAC,GAAG;KACnB,CAAC;IACF,MAAM,MAAM,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAElD,gCAAgC;IAChC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CACX,mCAAmC,MAAM,CAAC,KAAK,KAAK;YAClD,gEAAgE,CACnE,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3E,QAAQ,CAAC,IAAI,CACX,oCAAoC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAC/D,+DAA+D,CAClE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC"}

package/dist/src/flagSemantics.d.ts

@@ -1,16 +1,92 @@
-import type { FlagInput, LAFSError, LAFSErrorCategory } from "./types.js";
+/**
+ * Flag semantics for LAFS output format resolution.
+ *
+ * Implements the precedence chain defined in LAFS spec sections 5.1-5.3:
+ * explicit flag > project config > user config > TTY detection > default (json).
+ *
+ * @remarks
+ * This module is the single-layer resolver for format flags. For cross-layer
+ * resolution that also includes field extraction, use {@link resolveFlags} from
+ * `flagResolver.ts`.
+ *
+ * @since 1.0.0
+ */
+import type { FlagInput, LAFSError, LAFSErrorCategory } from './types.js';
+/**
+ * Result of resolving output format flags.
+ *
+ * @remarks
+ * Captures both the resolved format and which configuration layer determined it,
+ * enabling diagnostics and cross-layer validation in the unified resolver.
+ */
 export interface FlagResolution {
-    format: "json" | "human";
-    source: "flag" | "project" | "user" | "default";
-    /** When true, suppress non-essential output for scripting */
+    /** The resolved output format: `'json'` for machine-readable or `'human'` for human-readable. */
+    format: 'json' | 'human';
+    /** Which configuration layer determined the format value. */
+    source: 'flag' | 'project' | 'user' | 'default';
+    /** When true, suppress non-essential output for scripting. */
     quiet: boolean;
 }
+/**
+ * Error thrown when LAFS flag validation fails.
+ *
+ * @remarks
+ * Wraps a registered LAFS error code with category and retryability information
+ * looked up from the error registry. The most common error is `E_FORMAT_CONFLICT`
+ * when `--human` and `--json` are used together.
+ */
 export declare class LAFSFlagError extends Error implements LAFSError {
+    /** The LAFS error code (e.g. `'E_FORMAT_CONFLICT'`). */
     code: string;
+    /** The error category resolved from the error registry. */
     category: LAFSErrorCategory;
+    /** Whether the operation that produced this error can be retried. */
     retryable: boolean;
+    /** Milliseconds to wait before retrying, or `null` if not applicable. */
     retryAfterMs: number | null;
+    /** Additional structured details about the error. */
     details: Record<string, unknown>;
+    /**
+     * Create a new LAFSFlagError.
+     *
+     * @param code - A registered LAFS error code (e.g. `'E_FORMAT_CONFLICT'`)
+     * @param message - Human-readable description of the error
+     * @param details - Optional structured details to attach to the error
+     *
+     * @remarks
+     * Looks up the error code in the LAFS error registry to populate
+     * `category` and `retryable`. Falls back to `'CONTRACT'` category
+     * and non-retryable if the code is not found.
+     *
+     * @example
+     * ```ts
+     * throw new LAFSFlagError(
+     *   'E_FORMAT_CONFLICT',
+     *   'Cannot combine --human and --json.',
+     * );
+     * ```
+     */
     constructor(code: string, message: string, details?: Record<string, unknown>);
 }
+/**
+ * Resolve the output format from flag inputs using the LAFS precedence chain.
+ *
+ * @param input - The flag inputs including explicit flags, project/user defaults, and TTY state
+ * @returns The resolved format, its source layer, and quiet mode status
+ *
+ * @remarks
+ * Precedence (highest to lowest): explicit `requestedFormat` > `--human`/`--json` flag >
+ * project default > user default > TTY detection > protocol default (`'json'`).
+ * Throws `LAFSFlagError` with code `E_FORMAT_CONFLICT` if both `--human` and `--json`
+ * are set simultaneously.
+ *
+ * @example
+ * ```ts
+ * const resolution = resolveOutputFormat({ humanFlag: true });
+ * // => { format: 'human', source: 'flag', quiet: false }
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When `humanFlag` and `jsonFlag` are both truthy.
+ */
 export declare function resolveOutputFormat(input: FlagInput): FlagResolution;
+//# sourceMappingURL=flagSemantics.d.ts.map

package/dist/src/flagSemantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flagSemantics.d.ts","sourceRoot":"","sources":["../../src/flagSemantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,iGAAiG;IACjG,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAChD,8DAA8D;IAC9D,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,KAAM,YAAW,SAAS;IAC3D,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;;;;;;;;;;;;;;;;;;OAmBG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAUjF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,CA+BpE"}

package/dist/src/flagSemantics.js

@@ -1,45 +1,112 @@
-import { getRegistryCode } from "./errorRegistry.js";
+/**
+ * Flag semantics for LAFS output format resolution.
+ *
+ * Implements the precedence chain defined in LAFS spec sections 5.1-5.3:
+ * explicit flag > project config > user config > TTY detection > default (json).
+ *
+ * @remarks
+ * This module is the single-layer resolver for format flags. For cross-layer
+ * resolution that also includes field extraction, use {@link resolveFlags} from
+ * `flagResolver.ts`.
+ *
+ * @since 1.0.0
+ */
+import { getRegistryCode } from './errorRegistry.js';
+/**
+ * Error thrown when LAFS flag validation fails.
+ *
+ * @remarks
+ * Wraps a registered LAFS error code with category and retryability information
+ * looked up from the error registry. The most common error is `E_FORMAT_CONFLICT`
+ * when `--human` and `--json` are used together.
+ */
 export class LAFSFlagError extends Error {
+    /** The LAFS error code (e.g. `'E_FORMAT_CONFLICT'`). */
     code;
+    /** The error category resolved from the error registry. */
     category;
+    /** Whether the operation that produced this error can be retried. */
     retryable;
+    /** Milliseconds to wait before retrying, or `null` if not applicable. */
     retryAfterMs;
+    /** Additional structured details about the error. */
     details;
+    /**
+     * Create a new LAFSFlagError.
+     *
+     * @param code - A registered LAFS error code (e.g. `'E_FORMAT_CONFLICT'`)
+     * @param message - Human-readable description of the error
+     * @param details - Optional structured details to attach to the error
+     *
+     * @remarks
+     * Looks up the error code in the LAFS error registry to populate
+     * `category` and `retryable`. Falls back to `'CONTRACT'` category
+     * and non-retryable if the code is not found.
+     *
+     * @example
+     * ```ts
+     * throw new LAFSFlagError(
+     *   'E_FORMAT_CONFLICT',
+     *   'Cannot combine --human and --json.',
+     * );
+     * ```
+     */
     constructor(code, message, details = {}) {
         super(message);
-        this.name = "LAFSFlagError";
+        this.name = 'LAFSFlagError';
         this.code = code;
         const entry = getRegistryCode(code);
-        this.category = (entry?.category ?? "CONTRACT");
+        this.category = (entry?.category ?? 'CONTRACT');
         this.retryable = entry?.retryable ?? false;
         this.retryAfterMs = null;
         this.details = details;
     }
 }
+/**
+ * Resolve the output format from flag inputs using the LAFS precedence chain.
+ *
+ * @param input - The flag inputs including explicit flags, project/user defaults, and TTY state
+ * @returns The resolved format, its source layer, and quiet mode status
+ *
+ * @remarks
+ * Precedence (highest to lowest): explicit `requestedFormat` > `--human`/`--json` flag >
+ * project default > user default > TTY detection > protocol default (`'json'`).
+ * Throws `LAFSFlagError` with code `E_FORMAT_CONFLICT` if both `--human` and `--json`
+ * are set simultaneously.
+ *
+ * @example
+ * ```ts
+ * const resolution = resolveOutputFormat({ humanFlag: true });
+ * // => { format: 'human', source: 'flag', quiet: false }
+ * ```
+ *
+ * @throws {@link LAFSFlagError} When `humanFlag` and `jsonFlag` are both truthy.
+ */
 export function resolveOutputFormat(input) {
     if (input.humanFlag && input.jsonFlag) {
-        throw new LAFSFlagError("E_FORMAT_CONFLICT", "Cannot combine --human and --json in the same invocation.");
+        throw new LAFSFlagError('E_FORMAT_CONFLICT', 'Cannot combine --human and --json in the same invocation.');
     }
     const quiet = input.quiet ?? false;
     if (input.requestedFormat) {
-        return { format: input.requestedFormat, source: "flag", quiet };
+        return { format: input.requestedFormat, source: 'flag', quiet };
     }
     if (input.humanFlag) {
-        return { format: "human", source: "flag", quiet };
+        return { format: 'human', source: 'flag', quiet };
     }
     if (input.jsonFlag) {
-        return { format: "json", source: "flag", quiet };
+        return { format: 'json', source: 'flag', quiet };
     }
     if (input.projectDefault) {
-        return { format: input.projectDefault, source: "project", quiet };
+        return { format: input.projectDefault, source: 'project', quiet };
     }
     if (input.userDefault) {
-        return { format: input.userDefault, source: "user", quiet };
+        return { format: input.userDefault, source: 'user', quiet };
     }
     // TTY terminals default to human-readable output for usability.
     // Non-TTY (piped, CI, agents) defaults to JSON per LAFS protocol.
     if (input.tty) {
-        return { format: "human", source: "default", quiet };
+        return { format: 'human', source: 'default', quiet };
     }
-    return { format: "json", source: "default", quiet };
+    return { format: 'json', source: 'default', quiet };
 }
+//# sourceMappingURL=flagSemantics.js.map

package/dist/src/flagSemantics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flagSemantics.js","sourceRoot":"","sources":["../../src/flagSemantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAmBrD;;;;;;;GAOG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,wDAAwD;IACxD,IAAI,CAAS;IACb,2DAA2D;IAC3D,QAAQ,CAAoB;IAC5B,qEAAqE;IACrE,SAAS,CAAU;IACnB,yEAAyE;IACzE,YAAY,CAAgB;IAC5B,qDAAqD;IACrD,OAAO,CAA0B;IAEjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,IAAY,EAAE,OAAe,EAAE,UAAmC,EAAE;QAC9E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,EAAE,QAAQ,IAAI,UAAU,CAAsB,CAAC;QACrE,IAAI,CAAC,SAAS,GAAG,KAAK,EAAE,SAAS,IAAI,KAAK,CAAC;QAC3C,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACtC,MAAM,IAAI,aAAa,CACrB,mBAAmB,EACnB,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC;IAEnC,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAClE,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACnD,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QACzB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IACD,gEAAgE;IAChE,kEAAkE;IAClE,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACtD,CAAC"}