@poe-platform/safe-bash 0.1.527 → 0.1.529

package/dist/safe-bash/core.browser.js

@@ -37498,12 +37498,23 @@ function literalIndex(source2, offset, budget = new ParseBudget()) {
   return { decimal: decimal4 };
 }
 function numericIndex(index) {
+  if (index.source !== void 0) {
+    try {
+      return numericIndex(literalIndex(index.source, 0));
+    } catch {
+      return void 0;
+    }
+  }
   if (index.decimal.length > 10 || index.decimal.length === 10 && index.decimal > "2147483647") return void 0;
   return Number(index.decimal);
 }
-function arraySelector(source2, offset, budget = new ParseBudget()) {
+function stringIndex(source2, budget, word) {
+  budget.admit(2);
+  return { decimal: source2, source: source2, ...word ? { word } : {} };
+}
+function arraySelector(source2, offset, budget = new ParseBudget(), word) {
   budget.admit();
-  return source2 === "@" || source2 === "*" ? { kind: "members", separator: source2 } : { kind: "element", index: literalIndex(source2, offset, budget) };
+  return source2 === "@" || source2 === "*" ? { kind: "members", separator: source2 } : { kind: "element", index: word ? stringIndex(source2, budget, word) : literalIndex(source2, offset, budget) };
 }
 function setArraySelector(part, selector) {
   selectors.set(part, selector);
@@ -37543,21 +37554,22 @@ function removePrefix(word, length, budget) {
   if (length !== 0) throw new ShellSyntaxError("Invalid indexed-array assignment", word.offset);
   return { offset: word.offset, parts };
 }
-function elementAssignment(word, budget = new ParseBudget()) {
+function elementAssignment(word, budget = new ParseBudget(), parseWord, subscriptEnd) {
   const source2 = word.spelling;
   const first = word.parts[0];
   if (source2 === void 0 || first?.kind !== "text" || first.quoted) return void 0;
   const name2 = /^([a-zA-Z_][a-zA-Z_0-9]*)\[/u.exec(source2)?.[1];
   if (!name2) return void 0;
-  const end = source2.indexOf("]", name2.length + 1);
+  const end = subscriptEnd ? subscriptEnd(source2, name2.length + 1) : source2.indexOf("]", name2.length + 1);
   if (end < 0 || !/^(?:\+?=)/u.test(source2.slice(end + 1))) {
     if (source2.includes("=")) throw new ShellSyntaxError("Invalid indexed-array assignment", word.offset);
     return void 0;
   }
   budget.admit();
-  const index = literalIndex(source2.slice(name2.length + 1, end), word.offset + name2.length + 1, budget);
+  const keySource = source2.slice(name2.length + 1, end);
+  const index = parseWord ? stringIndex(keySource, budget, parseWord(keySource)) : literalIndex(keySource, word.offset + name2.length + 1, budget);
   const append = source2[end + 1] === "+";
-  const value2 = removePrefix(word, name2.length + index.decimal.length + (append ? 4 : 3), budget);
+  const value2 = parseWord ? parseWord(source2.slice(end + (append ? 3 : 2))) : removePrefix(word, name2.length + index.decimal.length + (append ? 4 : 3), budget);
   return { kind: "element", name: name2, index, append, value: value2 };
 }
 function compoundHead(word, budget = new ParseBudget()) {
@@ -38316,7 +38328,7 @@ shell: command substitution: line ${line}: \`${sourceLine}'
       if (!name2) this.error("Unsupported parameter expansion");
       this.position += name2.length;
       let prefixNames;
-      if (listing) {
+      if (listing && this.source[this.position] !== "[") {
         const separator = this.source[this.position];
         if (!/^[a-zA-Z_][a-zA-Z_0-9]*$/u.test(name2) || separator !== "*" && separator !== "@" || this.source[this.position + 1] !== "}") this.error("Unsupported indirect parameter expansion");
         prefixNames = separator;
@@ -38326,12 +38338,14 @@ shell: command substitution: line ${line}: \`${sourceLine}'
       if (this.source[this.position] === "[") {
         if (!/^[a-zA-Z_][a-zA-Z_0-9]*$/u.test(name2)) this.error("Unsupported indexed-array parameter");
         const start = ++this.position;
-        const end = this.source.indexOf("]", start);
-        if (end < 0) this.error("Unterminated indexed-array subscript");
-        selector = arraySelector(this.source.slice(start, end), start, this.budget);
+        const keyWord = this.word("]");
+        const end = this.position;
+        if (this.source[end] !== "]") this.error("Unterminated indexed-array subscript");
+        selector = arraySelector(this.source.slice(start, end), start, this.budget, keyWord);
         this.position = end + 1;
         if (this.source[this.position] !== "}" && this.source[this.position] !== "@") this.error("Unsupported indexed-array operator");
       }
+      if (listing && selector?.kind === "element") this.error("Unsupported indirect parameter expansion");
       let transform2;
       if (this.source[this.position] === "@") {
         const operation2 = this.source[this.position + 1];
@@ -38382,6 +38396,7 @@ shell: command substitution: line ${line}: \`${sourceLine}'
       } else {
         this.position++;
         const part = { kind: "variable", name: name2, quoted: quoted2, line, ...prefixNames ? { prefixNames } : {}, ...transform2 ? { transform: transform2 } : {}, ...length ? { length } : {}, ...operator ? { operator, alternate } : {}, ...replacement ? { replacement } : {}, ...substring ? { substring } : {} };
+        if (listing && selector) part.keys = true;
         if (selector) setArraySelector(part, selector);
         parts.push(part);
       }
@@ -38756,7 +38771,12 @@ var Parser4 = class {
             word = { offset: word.offset, parts: word.parts, spelling: this.lexer.source.slice(word.offset, end) };
             setArrayAssignment(word, { kind: "compound", ...head, entries: entries2 });
           } else {
-            const assignment = words.every((previous) => getArrayAssignment(previous) || scalarAssignmentName(previous)) ? elementAssignment(word, this.budget) : void 0;
+            const assignment = words.every((previous) => getArrayAssignment(previous) || scalarAssignmentName(previous)) ? elementAssignment(word, this.budget, (source2) => parseArraySubscript(source2, this.budget, this.lexer.byteLocale, this.lexer.depth), (source2, start) => {
+              const lexer = new Lexer2(this.budget, source2, this.lexer.depth, [], 0, this.lexer.byteLocale);
+              lexer.position = start;
+              lexer.word("]");
+              return lexer.source[lexer.position] === "]" ? lexer.position : -1;
+            }) : void 0;
             if (assignment) setArrayAssignment(word, assignment);
           }
           words.push(word);
@@ -38798,6 +38818,10 @@ function parseShell(source2, depth = 0, options3 = {}) {
   budget.admit();
   return { ...script, ...warnings.length ? { warnings } : {} };
 }
+function parseArraySubscript(source2, budget, byteLocale2 = false, depth = 0) {
+  const lexer = new Lexer2(budget, source2, depth, [], 0, byteLocale2);
+  return lexer.word("\0");
+}
 function parseBraceWord(source2, opaque, budget) {
   budget.admit(source2.length + 1);
   const lexer = new Lexer2(budget, source2, 0);
@@ -40879,14 +40903,16 @@ var controlNames = /* @__PURE__ */ new Set([
   "LC_CTYPE"
 ]);
 var OwnedText = class {
-  constructor(value2, bytes3, admission) {
+  constructor(value2, bytes3, admission, rawValue) {
     this.value = value2;
     this.bytes = bytes3;
     this.admission = admission;
+    this.rawValue = rawValue;
   }
   value;
   bytes;
   admission;
+  rawValue;
   references = 1;
   retain() {
     if (this.references === Number.MAX_SAFE_INTEGER) throw new ArrayFailure("reference capacity is not representable");
@@ -40912,27 +40938,110 @@ async function textToken(owner, value2, signal) {
   const admission = owner.reserve({ payload: bytes3, metadata: 32, work: 4 });
   return new OwnedText(value2, bytes3, admission);
 }
+async function valueToken(owner, value2, signal) {
+  if (typeof value2 === "string") return textToken(owner, value2, signal);
+  const bytes3 = shellValueByteLength(value2);
+  const temporary = owner.reserve({ payload: bytes3 * 3, metadata: 64, work: 4 });
+  try {
+    const input3 = shellValueBytes(value2);
+    const decoder2 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    let text3 = "";
+    for (let offset = 0; offset < bytes3; offset += 1024) {
+      const end = Math.min(bytes3, offset + 1024);
+      owner.reserve({ work: end - offset }).release();
+      await owner.ledger.checkpoint(signal, end - offset);
+      if (text3 !== void 0) try {
+        text3 += decoder2.decode(input3.subarray(offset, end), { stream: end < bytes3 });
+      } catch (error) {
+        if (!(error instanceof TypeError) || "code" in error && error.code !== "ERR_ENCODING_INVALID_ENCODED_DATA") throw error;
+        text3 = void 0;
+      }
+    }
+    if (text3 !== void 0) return await textToken(owner, text3, signal);
+    const admission = owner.reserve({ payload: bytes3 * 4, metadata: 128, work: 4 });
+    try {
+      const raw = shellValueFromBytes(input3);
+      return new OwnedText(shellValueText(raw), bytes3, admission, raw);
+    } catch (error) {
+      admission.release();
+      throw error;
+    }
+  } finally {
+    temporary.release();
+  }
+}
 var IndexedBinding = class _IndexedBinding {
-  constructor(owner) {
+  constructor(owner, associative = false) {
     this.owner = owner;
+    this.associative = associative;
   }
   owner;
+  associative;
   values = /* @__PURE__ */ new Map();
+  keys = /* @__PURE__ */ new Map();
+  keyByIndex = /* @__PURE__ */ new Map();
   maximum = -1;
   generation = 0;
   version = 0;
   references = 1;
   assigned = false;
-  static create(parent) {
+  static create(parent, associative = false) {
     const owner = ArrayOwner.create(parent.ledger, parent);
     try {
       owner.reserve({ wrappers: 1, metadata: 128, work: 7 });
-      return new _IndexedBinding(owner);
+      return new _IndexedBinding(owner, associative);
     } catch (error) {
       void owner.close();
       throw error;
     }
   }
+  async keyIdentity(value2, owner, signal) {
+    const length = shellValueByteLength(value2);
+    if (!length) throw new ArrayFailure("bad array subscript");
+    const admission = owner.reserve({ payload: length * 5, metadata: 64 + length * 16, work: length + 2 });
+    try {
+      const bytes3 = shellValueBytes(value2);
+      const parts = [];
+      for (const byte of bytes3) {
+        parts.push(byte.toString(16).padStart(2, "0"));
+        await owner.ledger.checkpoint(signal);
+      }
+      return parts.join("");
+    } finally {
+      admission.release();
+    }
+  }
+  async keyIndex(value2, owner, signal, create = false) {
+    const identity2 = await this.keyIdentity(value2, owner, signal);
+    const existing2 = this.keys.get(identity2);
+    if (existing2 || !create) return existing2?.index;
+    const index = this.maximum + 1;
+    const admission = this.owner.reserve({ metadata: 128 + identity2.length * 2, work: 8 });
+    let text3;
+    try {
+      text3 = await valueToken(this.owner, value2, signal);
+    } catch (error) {
+      admission.release();
+      throw error;
+    }
+    const entry = { index, text: text3, admission };
+    admission.cleanup = () => {
+      if (this.keys.get(identity2) === entry) {
+        this.keys.delete(identity2);
+        this.keyByIndex.delete(index);
+      }
+      text3.release();
+    };
+    this.keys.set(identity2, entry);
+    this.keyByIndex.set(index, identity2);
+    this.maximum = index;
+    return index;
+  }
+  remove(index) {
+    this.values.get(index)?.slot.release();
+    const identity2 = this.keyByIndex.get(index);
+    if (identity2 !== void 0) this.keys.get(identity2)?.admission.release();
+  }
   get(index) {
     return this.values.get(index)?.text.value;
   }
@@ -40959,13 +41068,30 @@ var IndexedBinding = class _IndexedBinding {
     previous?.slot.release();
   }
   async copy(signal) {
-    const copy2 = _IndexedBinding.create(this.owner.parent);
+    const copy2 = _IndexedBinding.create(this.owner.parent, this.associative);
     copy2.assigned = this.assigned;
     this.retain();
     try {
+      for (const [identity2, entry] of this.keys) {
+        const admission = copy2.owner.reserve({ metadata: 128 + identity2.length * 2, work: identity2.length + 8 });
+        copy2.owner.parent.adopt(entry.text.admission);
+        const text3 = entry.text.retain();
+        const cloned = { index: entry.index, text: text3, admission };
+        admission.cleanup = () => {
+          if (copy2.keys.get(identity2) === cloned) {
+            copy2.keys.delete(identity2);
+            copy2.keyByIndex.delete(entry.index);
+          }
+          text3.release();
+        };
+        copy2.keys.set(identity2, cloned);
+        copy2.keyByIndex.set(entry.index, identity2);
+        await copy2.owner.ledger.checkpoint(signal, identity2.length + 8);
+      }
       for (const [index, element] of this.values) {
         copy2.owner.reserve({ work: 2 }).release();
         const slot = copy2.owner.reserve({ slots: 1, metadata: 32, work: 5 });
+        copy2.owner.parent.adopt(element.text.admission);
         const text3 = element.text.retain();
         const cloned = { text: text3, slot };
         slot.cleanup = () => {
@@ -41148,6 +41274,116 @@ var BindingStore = class _BindingStore {
   }
 };
 
+// packages/safe-bash/src/shell/mapfile.ts
+init_platform();
+var MapfileUsageError = class extends Error {
+  constructor(message3, status2) {
+    super(message3);
+    this.status = status2;
+  }
+  status;
+};
+async function mapfileOptions(context2, work, allocation) {
+  const options3 = { name: "MAPFILE", strip: false, delimiter: 10, count: 0, skip: 0, origin: 0, preserve: false, callback: void 0, quantum: 5e3 };
+  const args = getCommandArguments(context2);
+  let cursor = 0;
+  const numeric4 = async (text3, maximum) => {
+    let value2 = 0;
+    let index = 0;
+    const whitespace2 = (code) => code === 32 || code >= 9 && code <= 13;
+    while (index < text3.length && whitespace2(text3.charCodeAt(index))) {
+      const pending = stringCheckpoint(work);
+      if (pending) await pending;
+      index++;
+    }
+    const negative = text3[index] === "-";
+    if (negative || text3[index] === "+") index++;
+    let digits = 0;
+    for (; index < text3.length; index++) {
+      const pending = stringCheckpoint(work);
+      if (pending) await pending;
+      const digit3 = text3.charCodeAt(index) - 48;
+      if (digit3 < 0 || digit3 > 9) break;
+      if (value2 > Math.floor((maximum - digit3) / 10)) throw new MapfileUsageError(`${text3}: invalid number`, 1);
+      value2 = value2 * 10 + digit3;
+      digits++;
+    }
+    for (; index < text3.length; index++) {
+      const pending = stringCheckpoint(work);
+      if (pending) await pending;
+      if (!whitespace2(text3.charCodeAt(index))) throw new MapfileUsageError(`${text3}: invalid number`, 1);
+    }
+    if (!digits || negative && value2 !== 0) throw new MapfileUsageError(`${text3}: invalid number`, 1);
+    return value2;
+  };
+  while (cursor < context2.args.length) {
+    const option = context2.args[cursor];
+    if (option === "--") {
+      cursor++;
+      break;
+    }
+    if (!option.startsWith("-") || option === "-") break;
+    cursor++;
+    for (let index = 1; index < option.length; index++) {
+      const pending = stringCheckpoint(work);
+      if (pending) await pending;
+      const flag = option[index];
+      if (flag === "t") {
+        options3.strip = true;
+        continue;
+      }
+      if (!"dnsOCc".includes(flag)) throw new MapfileUsageError(`-${flag}: invalid option`, 2);
+      const attached = index + 1 < option.length;
+      const operandIndex = attached ? cursor - 1 : cursor++;
+      const operand = attached ? option.slice(index + 1) : context2.args[operandIndex];
+      if (operand === void 0) throw new MapfileUsageError(`-${flag}: option requires an argument`, 2);
+      if (flag === "d") {
+        const bytes3 = shellValueBytes(args.values[operandIndex], allocation);
+        options3.delimiter = bytes3[attached ? index + 1 : 0] ?? 0;
+      } else if (flag === "C") options3.callback = operand;
+      else {
+        const value2 = await numeric4(operand, flag === "O" ? 2147483647 : Number.MAX_SAFE_INTEGER);
+        if (flag === "c") {
+          if (!value2) throw new MapfileUsageError("0: invalid callback quantum", 1);
+          options3.quantum = value2;
+        } else if (flag === "n") options3.count = value2;
+        else if (flag === "s") options3.skip = value2;
+        else {
+          options3.origin = value2;
+          options3.preserve = true;
+        }
+      }
+      break;
+    }
+  }
+  options3.name = context2.args[cursor] ?? "MAPFILE";
+  if (!/^[a-zA-Z_][a-zA-Z_0-9]*$/u.test(options3.name)) throw new MapfileUsageError(`${options3.name}: invalid identifier`, 1);
+  return options3;
+}
+async function collectMapfile(options3, input3, hooks) {
+  let skipped = 0;
+  let written = 0;
+  while (!options3.count || written < options3.count) {
+    hooks.loop();
+    const allocation = hooks.allocation();
+    try {
+      const record4 = await input3.mapfileRecord(options3.delimiter, options3.strip, allocation);
+      if (!record4.present) break;
+      if (skipped < options3.skip) {
+        skipped++;
+        continue;
+      }
+      const index = options3.origin + written;
+      if (index > 2147483647) throw new MapfileUsageError("array index exceeds 2147483647", 1);
+      if (options3.callback !== void 0 && (written + 1) % options3.quantum === 0) await hooks.callback(options3.callback, index, record4.value);
+      await hooks.write(index, record4.value);
+      written++;
+    } finally {
+      allocation.close();
+    }
+  }
+}
+
 // packages/safe-bash/src/shell/arrays/state.ts
 init_platform();
 var sessions = /* @__PURE__ */ new WeakMap();
@@ -41909,6 +42145,9 @@ var shellBuiltinNames = /* @__PURE__ */ new Set([
   "local",
   "unset",
   "read",
+  "declare",
+  "mapfile",
+  "readarray",
   "exit",
   "return",
   "break",
@@ -42907,6 +43146,7 @@ var InvocationCancellationOwner = class {
     this.#failures.push(...result2.failures);
   }
 };
+var mapfileCallbackStates = /* @__PURE__ */ new WeakSet();
 var Runtime = class _Runtime {
   constructor(fs, commands, middleware, budget, signal = budget.signal, fileWrites = /* @__PURE__ */ new Map(), outputFiles = /* @__PURE__ */ new Map(), commandSignal = signal, cancellation, cancellationState, cancellationOwner, cancellationDepth, cancellationMaxDepth, outcomeFrame = void 0, inputProfile = fs) {
     this.fs = fs;
@@ -43247,7 +43487,7 @@ var Runtime = class _Runtime {
   }
   variable(state, name2) {
     const binding = arrayStore(state)?.get(name2);
-    return binding ? binding.get(0) : state.variables[name2];
+    return binding ? binding.get(binding.associative ? binding.keys.get("30")?.index ?? -1 : 0) : state.variables[name2];
   }
   requireParameter(value2, name2, state, io, line) {
     if (state.nounset && value2 === void 0) throw new NounsetFailure(`${name2}: unbound variable`, io.diagnosticLine ?? line);
@@ -43257,7 +43497,7 @@ var Runtime = class _Runtime {
       this.writeVariable(state, name2, value2, origin);
       return;
     }
-    await this.arrayZero(state, name2, async () => shellValueText(value2));
+    await this.arrayZero(state, name2, async () => value2);
   }
   async prepareVariable(state, name2, saved, scalarLegacy = false) {
     const store = requireArrays(state);
@@ -43383,7 +43623,7 @@ var Runtime = class _Runtime {
           if (key !== index && key > maximum) maximum = key;
           await operation2.ledger.checkpoint(this.signal, 2);
         }
-        if (typeof index === "number") staged.values.get(index)?.slot.release();
+        if (typeof index === "number") staged.remove(index);
         staged.maximum = maximum;
       }
       this.signal.throwIfAborted();
@@ -43414,6 +43654,7 @@ var Runtime = class _Runtime {
     const store = requireArrays(state);
     const operation2 = ArrayOwner.create(store.owner.ledger, store.owner);
     const holding = store.owner.hold();
+    const valueAllocation = this.budget.values.scope();
     let staged;
     try {
       const watch = await store.watch(name2, operation2, this.signal);
@@ -43430,10 +43671,12 @@ var Runtime = class _Runtime {
       const current = store.get(name2);
       if (!current) throw new ArrayFailure("stale binding");
       staged = await current.copy(this.signal);
-      const value2 = append ? await this.arrayJoin(operation2, [current.get(0) ?? "", expanded], "") : expanded;
-      const token = await textToken(staged.owner, value2, this.signal);
+      const index = staged.associative ? await staged.keyIndex("0", operation2, this.signal, true) : 0;
+      const previous = current.values.get(index)?.text.rawValue ?? current.get(index) ?? "";
+      const value2 = !append ? expanded : typeof previous === "string" && typeof expanded === "string" ? await this.arrayJoin(operation2, [previous, expanded], "") : concatShellValues([previous, expanded], valueAllocation);
+      const token = await valueToken(staged.owner, value2, this.signal);
       try {
-        staged.insert(0, token);
+        staged.insert(index, token);
       } catch (error) {
         token.release();
         throw error;
@@ -43459,6 +43702,7 @@ var Runtime = class _Runtime {
         await staged?.release();
         await operation2.close();
       } finally {
+        valueAllocation.close();
         holding.release();
       }
     }
@@ -43477,10 +43721,33 @@ var Runtime = class _Runtime {
     await owner.ledger.checkpoint(this.signal);
     return result2;
   }
+  async arrayIndex(binding, index, state, io, owner, create = false) {
+    if (!binding?.associative) {
+      const selected = index.source === void 0 ? index : literalIndex(index.source, 0, this.budget.parsing);
+      const number5 = numericIndex(selected);
+      if (number5 === void 0) throw new ArrayFailure("index outside 0..2147483647");
+      return number5;
+    }
+    const word = index.word ?? parseArraySubscript(index.source ?? index.decimal, this.budget.parsing, byteLocale(state.variables), state.depth);
+    const fields3 = await this.valueWord(word, state, io, false);
+    const value2 = fields3.length === 1 ? fields3[0] : concatShellValues(fields3, io[valueScope]);
+    if (shellValueByteLength(value2) === 0) {
+      await this.diagnostic(io, "associative array: bad array subscript");
+      if (create) throw completedExit(1);
+      return void 0;
+    }
+    return binding.keyIndex(value2, owner, this.signal, create);
+  }
   async arrayAssignment(assignment, state, io) {
     const name2 = assignment.name;
     this.signal.throwIfAborted();
-    if (state.readonlyVariables?.has(name2)) throw new ArrayFailure("readonly binding");
+    if (state.readonlyVariables?.has(name2)) {
+      if (arrayStore(state)?.get(name2)?.associative) {
+        await this.diagnostic(io, `${name2}: readonly variable`);
+        throw completedExit(1);
+      }
+      throw new ArrayFailure("readonly binding");
+    }
     if (controlNames.has(name2)) throw new ArrayFailure("control binding cannot be indexed");
     if (state.exported.has(name2)) throw new ArrayFailure("exported binding cannot be indexed");
     const store = requireArrays(state);
@@ -43490,11 +43757,12 @@ var Runtime = class _Runtime {
     try {
       const watch = await store.watch(name2, operation2, this.signal);
       const current = store.get(name2);
+      if (current?.associative && assignment.kind === "compound" && assignment.entries.length) throw new ArrayFailure("nonempty associative compound assignment is unsupported");
       const initialMaximum = current?.maximum ?? (state.variables[name2] === void 0 ? -1 : 0);
       let planned = assignment.append && assignment.kind === "compound" ? initialMaximum + 1 : 0;
       if (assignment.kind === "element") {
         operation2.reserve({ work: assignment.index.decimal.length + 1 }).release();
-        if (numericIndex(assignment.index) === void 0) throw new ArrayFailure("index outside 0..2147483647");
+        if (!current?.associative && numericIndex(literalIndex(assignment.index.source ?? assignment.index.decimal, 0, this.budget.parsing)) === void 0) throw new ArrayFailure("index outside 0..2147483647");
       } else for (const entry of assignment.entries) {
         operation2.reserve({ work: entry.value.parts.length + (entry.index?.decimal.length ?? 0) + 2 }).release();
         if (entry.index) {
@@ -43520,9 +43788,9 @@ var Runtime = class _Runtime {
       const tickets = operation2.reserve({ generation: true, version: true, epoch: true, work: 8 });
       const prepared = await store.prepareName(name2, operation2, this.signal);
       const preserve = assignment.kind === "element" || assignment.append;
-      staged = preserve && current ? await current.copy(this.signal) : IndexedBinding.create(store.owner);
+      staged = preserve && current ? await current.copy(this.signal) : IndexedBinding.create(store.owner, current?.associative);
       if (preserve && !current && state.variables[name2] !== void 0) {
-        const token = await textToken(staged.owner, state.variables[name2], this.signal);
+        const token = await valueToken(staged.owner, stateMonitor(state)?.values.get(name2, state.variables[name2]) ?? state.variables[name2], this.signal);
         try {
           staged.insert(0, token);
         } catch (error) {
@@ -43534,7 +43802,7 @@ var Runtime = class _Runtime {
       let cursor = assignment.append && assignment.kind === "compound" ? initialMaximum + 1 : 0;
       const insert = async (index, value2) => {
         if (index > 2147483647) throw new ArrayFailure("index outside 0..2147483647");
-        const token = await textToken(staged.owner, value2, this.signal);
+        const token = await valueToken(staged.owner, value2, this.signal);
         try {
           staged.insert(index, token);
         } catch (error) {
@@ -43543,11 +43811,12 @@ var Runtime = class _Runtime {
         }
         writes++;
       };
+      const join = async (values) => values.every((value2) => typeof value2 === "string") ? this.arrayJoin(operation2, values, "") : concatShellValues(values, io[valueScope]);
       if (assignment.kind === "element") {
-        const index = numericIndex(assignment.index);
-        const fields3 = await this.word(assignment.value, state, io, false);
-        let value2 = await this.arrayJoin(operation2, fields3, "");
-        if (assignment.append) value2 = await this.arrayJoin(operation2, [staged.get(index) ?? "", value2], "");
+        const index = await this.arrayIndex(staged, assignment.index, state, io, operation2, true);
+        const fields3 = await this.valueWord(assignment.value, state, io, false);
+        let value2 = await join(fields3);
+        if (assignment.append) value2 = await join([staged.values.get(index)?.text.rawValue ?? staged.get(index) ?? "", value2]);
         await insert(index, value2);
       } else for (const entry of assignment.entries) {
         const original = compoundEntryWords.get(entry);
@@ -43558,16 +43827,16 @@ var Runtime = class _Runtime {
             expandedEntry = true;
             const values = await this.valueWord(expanded, state, io, true, false, false, false, void 0, false);
             for (const value2 of values) {
-              await insert(cursor, shellValueText(value2));
+              await insert(cursor, value2);
               cursor++;
             }
           }
           if (expandedEntry) continue;
         }
-        const fields3 = await this.word(entry.value, state, io, entry.index === void 0);
+        const fields3 = await this.valueWord(entry.value, state, io, entry.index === void 0);
         if (entry.index) {
           const index = numericIndex(entry.index);
-          await insert(index, await this.arrayJoin(operation2, fields3, ""));
+          await insert(index, await join(fields3));
           cursor = index + 1;
         } else for (const value2 of fields3) {
           await insert(cursor, value2);
@@ -44458,8 +44727,8 @@ var Runtime = class _Runtime {
             throw new ArrayFailure("indexed binding cannot be a command prefix");
           }
           await this.arrayZero(state, assignment.name, async () => {
-            const fields3 = await this.word(assignment.value, state, io, false);
-            return this.arrayJoin(requireArrays(state).owner, fields3, "");
+            const fields3 = await this.valueWord(assignment.value, state, io, false);
+            return fields3.every((value3) => typeof value3 === "string") ? this.arrayJoin(requireArrays(state).owner, fields3, "") : concatShellValues(fields3, io[valueScope]);
           }, assignment.append);
           continue;
         }
@@ -44778,6 +45047,8 @@ var Runtime = class _Runtime {
             functionRestoration?.close();
             throw error;
           }
+          const callerLoopDepth = state.loopDepth;
+          if (mapfileCallbackStates.has(state)) state.loopDepth = 0;
           try {
             return { exitCode: await this.command(body, state, { ...io, ...context3, scriptName: body.sourceName ?? io.scriptName ?? "shell" }) };
           } catch (error) {
@@ -44791,6 +45062,7 @@ var Runtime = class _Runtime {
               savedPositionals.close();
               state.positionalSetVersion = positionalSetVersion;
               state.functionDepth--;
+              state.loopDepth = callerLoopDepth;
               state.depth--;
               state.locals.pop();
             };
@@ -46262,12 +46534,120 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
       allocation.close();
     }
   }
+  async mapfileBuiltin(context2, state) {
+    const allocation = this.budget.values.scope();
+    const work = { remaining: this.budget.limits.maxExpansionBytes * 8, signal: this.signal, exhausted: () => this.budget.fail("maxExpansionBytes") };
+    let pinned;
+    let releaseHolding;
+    try {
+      const options3 = await mapfileOptions(context2, work, allocation);
+      if (arrayStore(state)?.get(options3.name)?.associative) throw new MapfileUsageError(`${options3.name}: not an indexed array`, 1);
+      if (state.readonlyVariables?.has(options3.name)) throw new MapfileUsageError(`${options3.name}: readonly variable`, 1);
+      if (controlNames.has(options3.name) || state.exported.has(options3.name)) throw new ArrayFailure("control or exported binding cannot be indexed");
+      const store = requireArrays(state);
+      const holding = store.owner.hold();
+      releaseHolding = () => holding.release();
+      if (!options3.preserve || !store.get(options3.name)) await this.arrayAssignment({ kind: "compound", name: options3.name, append: options3.preserve, entries: [] }, state, context2);
+      const entry = store.bindings.get(options3.name);
+      allocation.reserve(128 + import_buffer.Buffer.byteLength(options3.name) * 2, 0);
+      pinned = entry.binding.retain();
+      const input3 = context2.stdin instanceof ShellInput ? context2.stdin : new ShellInput(context2.stdin, this.budget, this.signal);
+      let pendingFlow;
+      await collectMapfile(options3, input3, {
+        allocation: () => this.budget.values.scope(),
+        loop: () => this.budget.loop(),
+        write: async (index, value2) => {
+          if (pinned !== entry.binding) {
+            const previous = pinned;
+            pinned = entry.binding.retain();
+            await previous.release();
+          }
+          const operation2 = ArrayOwner.create(store.owner.ledger, store.owner);
+          let staged;
+          try {
+            const current = pinned;
+            const attached = store.bindings.get(options3.name) === entry;
+            const watch = attached ? await store.watch(options3.name, operation2, this.signal) : void 0;
+            const supersede = attached ? await stateMonitor(state).prepareTypedPublication(options3.name, operation2, this.signal) : void 0;
+            if (attached) await this.prepareArrayObservers(state, operation2);
+            const tickets = operation2.reserve({ generation: true, version: true, epoch: true, work: 8 });
+            staged = current.references > (attached ? 2 : 1) ? await current.copy(this.signal) : current.retain();
+            const token = await valueToken(staged.owner, value2, this.signal);
+            try {
+              this.signal.throwIfAborted();
+              if (watch && !watch.valid()) throw new ArrayFailure("stale binding");
+              staged.insert(index, token);
+            } catch (error) {
+              token.release();
+              throw error;
+            }
+            if (attached) {
+              let released;
+              stateMonitor(state).publish(tickets, options3.name, () => {
+                supersede();
+                released = store.publish(options3.name, staged, tickets);
+              });
+              staged = void 0;
+              await released;
+            } else {
+              const previous = pinned;
+              pinned = staged;
+              entry.binding = staged;
+              staged = void 0;
+              await previous.release();
+            }
+          } finally {
+            try {
+              await staged?.release();
+            } finally {
+              await operation2.close();
+            }
+          }
+        },
+        callback: async (source2, index, value2) => {
+          if (pendingFlow) return;
+          const callbackAllocation = this.budget.values.scope();
+          const nested = mapfileCallbackStates.has(state);
+          try {
+            const quoted2 = shellValueText(await transformParameter(value2, "Q", { maximumBytes: this.budget.limits.maxExpansionBytes, byteLocale: byteLocale(state.variables), work, allocation: callbackAllocation }));
+            if (import_buffer.Buffer.byteLength(source2) + import_buffer.Buffer.byteLength(quoted2) + String(index).length + 2 > this.budget.limits.maxExpansionBytes) this.budget.fail("maxExpansionBytes");
+            mapfileCallbackStates.add(state);
+            await this.evalBuiltin({ ...context2, args: [source2, String(index), quoted2] }, state, context2, false);
+          } catch (error) {
+            if (error instanceof Flow2 && (error.kind === "break" || error.kind === "continue")) pendingFlow = error;
+            else throw error;
+          } finally {
+            if (!nested) mapfileCallbackStates.delete(state);
+            callbackAllocation.close();
+          }
+        }
+      });
+      if (pendingFlow) throw pendingFlow;
+      return 0;
+    } catch (error) {
+      this.signal.throwIfAborted();
+      if (!(error instanceof MapfileUsageError)) throw error;
+      await this.diagnostic(context2, `${context2.command}: ${error.message}`);
+      return error.status;
+    } finally {
+      try {
+        await pinned?.release();
+      } finally {
+        try {
+          releaseHolding?.();
+        } finally {
+          allocation.close();
+        }
+      }
+    }
+  }
   async builtin(context2, state, assignments2, diagnose, suppressSpecial = false) {
     const { command: command7, args, stdout, stderr } = context2;
     if (command7 === ":" || command7 === "true") return 0;
     if (command7 === "false") return 1;
     if (command7 === "shopt") return this.shoptBuiltin(context2, state);
     if (command7 === "let") return this.letBuiltin(context2, state);
+    if (command7 === "mapfile" || command7 === "readarray") return this.mapfileBuiltin(context2, state);
     if (command7 === "getopts") return this.getoptsBuiltin(context2, state);
     if (command7 === "pushd" || command7 === "dirs" || command7 === "popd") return this.directoryStackBuiltin(context2, state, diagnose);
     if (command7 === "pwd") {
@@ -46332,9 +46712,16 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
       this.replacePositionals(state, this.positionalValues(state).slice(count2));
       return 0;
     }
-    if (command7 === "export" || command7 === "local" || command7 === "readonly") {
+    if (command7 === "export" || command7 === "local" || command7 === "readonly" || command7 === "declare") {
+      const associativeDeclaration = command7 === "declare";
       const declarationArgs = [...args];
-      let indexedLocal = false;
+      let indexedLocal = associativeDeclaration;
+      if (associativeDeclaration) {
+        if (declarationArgs.shift() !== "-A" || !declarationArgs.length) {
+          await this.diagnostic(context2, "declare: only -A NAME is supported");
+          return 2;
+        }
+      }
       if (command7 === "local") {
         const options3 = localDeclarationOptions(declarationArgs, this.signal);
         if (options3.error !== void 0) {
@@ -46397,11 +46784,11 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
           status2 = 1;
           continue;
         }
-        if (command7 === "local" && indexedLocal) {
+        if ((command7 === "local" || associativeDeclaration) && indexedLocal) {
           if (controlNames.has(name2)) throw new ArrayFailure("control binding cannot be indexed");
           if (state.exported.has(name2)) throw new ArrayFailure("exported binding cannot be indexed");
-          const existingLocal = locals.get(name2);
-          const saved = existingLocal ? void 0 : assignments2.get(name2) ?? saveVariable(state, name2);
+          const existingLocal = locals?.get(name2);
+          const saved = !locals || existingLocal ? void 0 : assignments2.get(name2) ?? saveVariable(state, name2);
           let operation2;
           let holding;
           let shadow;
@@ -46426,12 +46813,14 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
             const tickets = operation2.reserve({ generation: true, version: true, epoch: true, work: 8 });
             const prepared = await store.prepareName(name2, operation2, this.signal);
             const current = store.get(name2);
-            shadow = !saved && current ? await current.copy(this.signal) : IndexedBinding.create(store.owner);
+            if (!saved && current && current.associative !== associativeDeclaration) throw new ArrayFailure("cannot convert array kind");
+            shadow = !saved && current ? await current.copy(this.signal) : IndexedBinding.create(store.owner, associativeDeclaration);
             const value2 = match[2] ?? (!saved && !current && Object.hasOwn(state.variables, name2) ? state.variables[name2] : void 0);
             if (value2 !== void 0) {
-              const token = await textToken(shadow.owner, value2, this.signal);
+              const retained = associativeDeclaration && match[2] === void 0 ? stateMonitor(state).values.get(name2, value2) : value2;
+              const token = await valueToken(shadow.owner, retained, this.signal);
               try {
-                shadow.insert(0, token);
+                shadow.insert(associativeDeclaration ? await shadow.keyIndex("0", operation2, this.signal, true) : 0, token);
               } catch (error) {
                 token.release();
                 throw error;
@@ -46579,7 +46968,8 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
     }
     if (command7 === "unset") {
       let status2 = 0;
-      for (const name2 of args) {
+      for (let argument2 = 0; argument2 < args.length; argument2++) {
+        const name2 = args[argument2];
         const selected = /^([a-zA-Z_][a-zA-Z_0-9]*)\[(.*)\]$/su.exec(name2);
         if (selected) {
           const base = selected[1];
@@ -46589,7 +46979,12 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
             status2 = 1;
             continue;
           }
-          if (selector === "@" || selector === "*") await this.unsetIndexed(state, base, "members");
+          const binding = arrayStore(state)?.get(base);
+          if (binding?.associative) {
+            const original = getCommandArguments(context2).values[argument2];
+            const index = typeof original === "string" ? await this.arrayIndex(binding, { decimal: selector, source: selector }, state, context2, binding.owner) : await binding.keyIndex(shellValueFromBytes(shellValueBytes(original, context2[valueScope]).subarray(base.length + 1, shellValueByteLength(original) - 1), context2[valueScope]), binding.owner, this.signal);
+            if (index !== void 0) await this.unsetIndexed(state, base, index);
+          } else if (selector === "@" || selector === "*") await this.unsetIndexed(state, base, "members");
           else {
             let index;
             try {
@@ -46823,7 +47218,7 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
     if (part.kind === "variable" && part.transform) {
       const selector2 = getArraySelector(part);
       if (selector2?.kind === "members" || part.name === "@" || part.name === "*") {
-        const members = selector2 ? await this.arrayMembers(part.name, state) : this.positionalValues(state);
+        const members = selector2 ? await this.arrayMembers(part.name, state, io, part.keys) : this.positionalValues(state);
         const ifs = state.variables.IFS ?? " ";
         const separator = ifs.length ? String.fromCodePoint(ifs.codePointAt(0)) : "";
         const fragments = [];
@@ -46863,10 +47258,22 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
     const binding = part.kind === "variable" ? arrayStore(state)?.get(part.name) : void 0;
     const holding = binding ? requireArrays(state).owner.hold() : void 0;
     const selector = getArraySelector(part);
-    const index = selector?.kind === "element" ? numericIndex(selector.index) : 0;
+    if (selector?.kind === "element" && binding?.associative) {
+      try {
+        const index2 = await this.arrayIndex(binding, selector.index, state, io, binding.owner);
+        const token2 = index2 === void 0 ? void 0 : binding.values.get(index2)?.text;
+        this.requireParameter(token2?.value, part.kind === "variable" ? part.name : "", state, io);
+        if (part.kind === "variable" && part.length) return this.parameterLength(token2?.value ?? "");
+        return token2?.rawValue ? shellValueFromBytes(shellValueBytes(token2.rawValue, io[valueScope]), io[valueScope]) : token2?.value ?? "";
+      } finally {
+        holding?.release();
+      }
+    }
+    const index = selector?.kind === "element" ? numericIndex(selector.index) : binding?.associative ? binding.keys.get("30")?.index : 0;
     const token = index === void 0 || selector?.kind === "members" ? void 0 : binding?.values.get(index)?.text;
     token?.retain();
     try {
+      if (token?.rawValue && part.kind === "variable" && !part.length && !part.operator && !part.substring) return shellValueFromBytes(shellValueBytes(token.rawValue, io[valueScope]), io[valueScope]);
       const value2 = await this.partValue(part, state, io, hereString);
       if (binding) await textToken(requireArrays(state).owner, shellValueText(value2), this.signal);
       return value2;
@@ -46984,8 +47391,11 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
         return part.length ? this.parameterLength(value3 ?? "") : value3 ?? "";
       }
       if (part.length) return String(binding?.values.size ?? (state.variables[part.name] === void 0 ? 0 : 1));
-      const values = await this.arrayMembers(part.name, state);
-      return this.arrayJoin(store.owner, values, Array.from(state.variables.IFS ?? " ")[0] ?? "");
+      const values = await this.arrayMembers(part.name, state, io, part.keys);
+      const separator = Array.from(state.variables.IFS ?? " ")[0] ?? "";
+      if (values.every((value3) => typeof value3 === "string")) return this.arrayJoin(store.owner, values, separator);
+      io[valueScope]?.reserve(values.length * 32 + 64, 0);
+      return concatShellValues(values.flatMap((value3, index) => index ? [separator, value3] : [value3]), io[valueScope]);
     }
     let value2 = part.name === "?" ? String(state.status) : part.name === "-" ? `${state.errexit ? "e" : ""}${state.nounset ? "u" : ""}${state.braceexpand !== false ? "B" : ""}` : part.name === "#" ? String(state.positional.length) : part.name === "@" || part.name === "*" ? state.positional.join(hereString && (part.name === "@" || !part.quoted) ? " " : Array.from(state.variables.IFS ?? " ")[0] ?? "") : /^0+$/u.test(part.name) ? state.arg0 ?? "virtual-bash" : /^\d+$/u.test(part.name) ? state.positional[Number(part.name) - 1] : this.variable(state, part.name);
     let retained = value2;
@@ -47394,7 +47804,7 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
             emptyNameGroups.add(quoteGroup);
           }
         } else if (part.kind === "variable" && split4 && (selector?.kind === "members" && !part.length && (!part.quoted || selector.separator === "@") || part.transform && part.name === "@")) {
-          const members = selector?.kind === "members" ? await this.arrayMembers(part.name, state) : this.positionalValues(state);
+          const members = selector?.kind === "members" ? await this.arrayMembers(part.name, state, io, part.keys) : this.positionalValues(state);
           for (let position = 0; position < members.length; position++) {
             if (position > 0) addField();
             const original = members[position];
@@ -47536,7 +47946,7 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
     for (const value2 of values) if (typeof value2 !== "string") allocation.hold(value2);
     return createCommandArguments(values, allocation);
   }
-  async arrayMembers(name2, state) {
+  async arrayMembers(name2, state, io, keys = false) {
     const store = requireArrays(state);
     const holding = store.owner.hold();
     try {
@@ -47547,7 +47957,7 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
         if (value2 === void 0) return [];
         store.owner.reserve({ metadata: 32, allocatedSlots: 1, work: 3 });
         await textToken(store.owner, value2, this.signal);
-        return [value2];
+        return [keys ? "0" : value2];
       }
       binding.retain();
       try {
@@ -47555,8 +47965,9 @@ ${prefix3} line ${offset + line}: \`${source2.split("\n")[line - 1] ?? ""}'
         const values = [];
         for (const index of indices) {
           store.owner.reserve({ metadata: 32, allocatedSlots: 1, work: 4 });
-          const value2 = binding.get(index);
-          await textToken(store.owner, value2, this.signal);
+          const token = keys ? binding.associative ? binding.keys.get(binding.keyByIndex.get(index)).text : await textToken(store.owner, String(index), this.signal) : binding.values.get(index).text;
+          const value2 = token.rawValue === void 0 ? token.value : shellValueFromBytes(shellValueBytes(token.rawValue, io[valueScope]), io[valueScope]);
+          if (typeof value2 === "string") await textToken(store.owner, value2, this.signal);
           values.push(value2);
           await store.owner.ledger.checkpoint(this.signal);
         }
@@ -48231,6 +48642,51 @@ var ShellInput = class _ShellInput {
       }
     });
   }
+  mapfileRecord(delimiter, strip, allocation) {
+    return this.#cursor.consume(this.signal, async () => {
+      this.#cursor.admitBoundedRead();
+      allocation.reserve(64, 0);
+      const parts = [];
+      let length = 0;
+      let truncated = false;
+      let pulls = 0;
+      while (true) {
+        if (++pulls % 128 === 0) await yieldTurn(this.signal);
+        const result2 = await this.#cursor.take(this.signal);
+        if (result2.done) return { value: concatShellValues(parts, allocation), present: length > 0 };
+        const chunk = result2.value;
+        for (let offset = 0; offset < chunk.length; ) {
+          await yieldTurn(this.signal);
+          if (length >= this.budget.limits.maxOutputBytes) this.budget.fail("maxOutputBytes");
+          const end = Math.min(offset + 1024, chunk.length, offset + this.budget.limits.maxOutputBytes - length);
+          allocation.reserve(end - offset + 64, 0);
+          const output2 = new Uint8Array(end - offset);
+          let used = 0;
+          let terminated = false;
+          while (offset < end) {
+            const byte = chunk[offset++];
+            this.#cursor.position++;
+            if (++length > this.budget.limits.maxOutputBytes) this.budget.fail("maxOutputBytes");
+            if (byte === delimiter) {
+              if (!strip && byte !== 0 && !truncated) output2[used++] = byte;
+              terminated = true;
+              break;
+            }
+            if (byte === 0) truncated = true;
+            if (!truncated) output2[used++] = byte;
+          }
+          if (used) {
+            allocation.reserve(32, 0);
+            parts.push(shellValueFromBytes(output2.subarray(0, used), allocation));
+          }
+          if (terminated) {
+            if (offset < chunk.length) this.#cursor.remainder = chunk.subarray(offset);
+            return { value: concatShellValues(parts, allocation), present: true };
+          }
+        }
+      }
+    });
+  }
   async readBounded(raw, options3) {
     const text3 = new ReadText();
     let characters = 0;