claudeup 4.17.0 → 4.18.0

package/src/services/alias-shell-writer.js

@@ -0,0 +1,764 @@
+/**
+ * Render the managed `claude` alias and splice it into shell rc files.
+ *
+ * Two layers:
+ *   - Pure render functions (POSIX vs fish) that take a config and emit text.
+ *   - I/O helpers that detect installed shells and replace the managed block
+ *     idempotently using sentinel comment markers.
+ */
+import { readFile, writeFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { ALIAS_FLAGS, getFlagById, } from "../data/alias-flags.js";
+const BLOCK_BEGIN = "# >>> claudeup managed alias >>>";
+const BLOCK_END = "# <<< claudeup managed alias <<<";
+/**
+ * Probe the user's home dir for the three supported shell rc files.
+ *
+ * Path discovery is intentionally simple: we don't follow `$ZDOTDIR` or
+ * fish's `$XDG_CONFIG_HOME` overrides yet. If users hit those, we expose
+ * a path override later — for now the conventional locations cover the
+ * default install on macOS / Linux.
+ */
+export async function detectShells(home = homedir(), shellEnv = process.env.SHELL ?? "") {
+    const candidates = [
+        { kind: "zsh", path: join(home, ".zshrc") },
+        { kind: "bash", path: join(home, ".bashrc") },
+        { kind: "fish", path: join(home, ".config", "fish", "config.fish") },
+    ];
+    const defaultKind = inferDefaultShell(shellEnv);
+    const results = [];
+    for (const c of candidates) {
+        let exists = existsSync(c.path);
+        if (exists) {
+            // existsSync can lie on broken symlinks — check stat too
+            try {
+                await stat(c.path);
+            }
+            catch {
+                exists = false;
+            }
+        }
+        results.push({
+            kind: c.kind,
+            path: c.path,
+            exists,
+            isDefault: c.kind === defaultKind,
+        });
+    }
+    return results;
+}
+function inferDefaultShell(shellEnv) {
+    if (shellEnv.endsWith("/zsh"))
+        return "zsh";
+    if (shellEnv.endsWith("/bash"))
+        return "bash";
+    if (shellEnv.endsWith("/fish"))
+        return "fish";
+    return null;
+}
+/**
+ * Build the alias body as a list of segments. Pure function.
+ *
+ * Validation:
+ *  - `xorGroup` collisions are resolved by emitting only the first enabled
+ *    flag in the group. The UI is responsible for warning the user; the
+ *    renderer never silently keeps both.
+ *  - `requires` is enforced: a flag whose dependency is disabled is dropped.
+ */
+export function renderArgs(config) {
+    const out = [];
+    const seenXor = new Set();
+    for (const flag of ALIAS_FLAGS) {
+        if (flag.requires) {
+            const dep = config.flags[flag.requires];
+            if (!isFlagEnabled(dep))
+                continue;
+        }
+        if (flag.xorGroup) {
+            if (seenXor.has(flag.xorGroup))
+                continue;
+        }
+        const value = config.flags[flag.id];
+        if (!value)
+            continue;
+        const rendered = renderFlag(flag, value);
+        if (rendered.length === 0)
+            continue;
+        out.push(...rendered);
+        if (flag.xorGroup)
+            seenXor.add(flag.xorGroup);
+    }
+    return out;
+}
+/**
+ * Convenience: render each segment to its literal-token approximation.
+ * Composite segments are stringified by joining their literal parts with
+ * `<sub>` placeholders for raw parts. Used by tests and validation summaries
+ * where the actual shell substitution doesn't matter.
+ */
+export function renderArgsAsTokens(config) {
+    return renderArgs(config).map((seg) => {
+        if (seg.kind === "literal")
+            return seg.text;
+        return seg.parts
+            .map((p) => (p.kind === "literal" ? p.text : `<${p.posix}>`))
+            .join("");
+    });
+}
+function isFlagEnabled(value) {
+    if (!value)
+        return false;
+    switch (value.kind) {
+        case "boolean":
+            return value.enabled;
+        case "tri-state":
+            return value.state !== "unset";
+        case "select":
+        case "text":
+        case "optional-text":
+        case "text-list":
+        case "multi-with-custom":
+            return value.enabled;
+    }
+}
+function lit(text) {
+    return { kind: "literal", text };
+}
+/**
+ * Wrap a templated value as a composite segment if it contains any tokens,
+ * otherwise return it as a plain literal.
+ */
+function templatedSegment(value) {
+    const parts = expandTemplateValue(value);
+    if (parts.length === 1 && parts[0].kind === "literal") {
+        return { kind: "literal", text: parts[0].text };
+    }
+    return { kind: "composite", parts };
+}
+function renderFlag(flag, value) {
+    switch (value.kind) {
+        case "boolean":
+            return value.enabled ? [lit(flag.flag)] : [];
+        case "tri-state":
+            if (value.state === "on")
+                return [lit(flag.flag)];
+            if (value.state === "off" && flag.triStateOff)
+                return [lit(flag.triStateOff)];
+            return [];
+        case "select":
+            if (!value.enabled)
+                return [];
+            // Empty value means "bare flag, default variant" (e.g. `--tmux` alone).
+            return value.value === ""
+                ? [lit(flag.flag)]
+                : [lit(flag.flag), lit(value.value)];
+        case "text":
+            if (!value.enabled || !value.value)
+                return [];
+            return [
+                lit(flag.flag),
+                flag.templated ? templatedSegment(value.value) : lit(value.value),
+            ];
+        case "optional-text":
+            if (!value.enabled)
+                return [];
+            if (!value.value)
+                return [lit(flag.flag)];
+            return [
+                lit(flag.flag),
+                flag.templated ? templatedSegment(value.value) : lit(value.value),
+            ];
+        case "text-list": {
+            if (!value.enabled || value.values.length === 0)
+                return [];
+            const out = [];
+            for (const v of value.values) {
+                if (!v)
+                    continue;
+                out.push(lit(flag.flag), flag.templated ? templatedSegment(v) : lit(v));
+            }
+            return out;
+        }
+        case "multi-with-custom": {
+            if (!value.enabled)
+                return [];
+            const tokens = dedupe([...value.picked, ...value.custom]).filter((t) => t.length > 0);
+            if (tokens.length === 0)
+                return [lit(flag.flag)];
+            return [lit(flag.flag), lit(tokens.join(","))];
+        }
+    }
+}
+/**
+ * Per-token shell-substitution code. POSIX and fish forms diverge slightly:
+ *
+ * - POSIX: classic `$(cmd)` with double quotes around `$PWD` so paths with
+ *   spaces survive word-splitting in `basename`. The double quotes are
+ *   tolerable inside the outer-double-quoted segment because we're already
+ *   committed to a "embedded substitution" layer.
+ * - fish: `(cmd)` and fish handles variable expansion without the
+ *   word-splitting concern, so `$PWD` doesn't need inner quoting.
+ *
+ * Note for POSIX: when this segment is emitted as `'"$(basename "$PWD")"'`,
+ * the shell sees `"$(basename "$PWD")"` — outer `"…"` enclosing an inner
+ * `"$PWD"`. POSIX (and bash/zsh) handle nested double quotes inside command
+ * substitution correctly: the inner `"$PWD"` is parsed within the `$(...)`
+ * subshell scope, not the outer shell's scope.
+ */
+const TOKEN_TO_SUB = {
+    "{folder}": {
+        posix: '$(basename "$PWD")',
+        fish: "(basename $PWD)",
+    },
+    "{day}": { posix: "$(date +%d)", fish: "(date +%d)" },
+    "{month}": { posix: "$(date +%m)", fish: "(date +%m)" },
+    "{year}": { posix: "$(date +%Y)", fish: "(date +%Y)" },
+};
+const TEMPLATE_RE = /\{(folder|day|month|year)\}/g;
+/**
+ * Split a templated value into alternating literal and raw parts.
+ * Empty literal pieces are dropped. If the value contains no tokens, returns
+ * a single literal part covering the full string.
+ */
+export function expandTemplateValue(value) {
+    const out = [];
+    let last = 0;
+    for (const match of value.matchAll(TEMPLATE_RE)) {
+        const start = match.index;
+        if (start > last) {
+            out.push({ kind: "literal", text: value.slice(last, start) });
+        }
+        const sub = TOKEN_TO_SUB[match[0]];
+        if (sub) {
+            out.push({ kind: "raw", posix: sub.posix, fish: sub.fish });
+        }
+        last = start + match[0].length;
+    }
+    if (last < value.length) {
+        out.push({ kind: "literal", text: value.slice(last) });
+    }
+    if (out.length === 0) {
+        out.push({ kind: "literal", text: value });
+    }
+    return out;
+}
+function dedupe(arr) {
+    return Array.from(new Set(arr));
+}
+/**
+ * Fish quoting. Fish single quotes are simpler — only `\` and `'` need escapes.
+ */
+function quoteFish(s) {
+    return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+export function renderAlias(config, shell) {
+    const args = renderArgs(config);
+    const name = config.aliasName;
+    if (shell === "fish") {
+        return { shell, block: renderFishBlock(name, args) };
+    }
+    return { shell, block: renderPosixBlock(name, args) };
+}
+function renderPosixBlock(name, segments) {
+    // The alias body lives inside outer single quotes:
+    //   alias <name>='claude … '
+    // Each segment becomes one shell-arg inside that body. Composite segments
+    // (templated values) interleave literal text with double-quoted shell
+    // substitutions via close-outer + double-quote + reopen-outer.
+    const body = segments.length === 0
+        ? ""
+        : " " + segments.map(renderPosixSegment).join(" ");
+    const line = `alias ${name}='claude${body}'`;
+    return `${BLOCK_BEGIN}\n${line}\n${BLOCK_END}\n`;
+}
+function renderPosixSegment(seg) {
+    if (seg.kind === "literal")
+        return quoteInsidePosixAlias(seg.text);
+    return seg.parts
+        .map((p) => p.kind === "literal"
+        ? quoteInsidePosixAlias(p.text)
+        : embedPosixSubstitution(p.posix))
+        .join("");
+}
+/**
+ * Embed shell substitution code inside the outer single-quoted alias body
+ * so it fires when the alias is expanded, not when the alias is defined.
+ *
+ * The outer alias body is `'…'`. To inject `$(cmd)` and have it evaluate at
+ * expansion time, we close the outer `'`, switch to double quotes (which
+ * interpolate), emit the substitution, close the double quotes, reopen the
+ * outer `'`. Net source text: `'"$(cmd)"'`.
+ *
+ * Any inner double quotes in the substitution code (e.g. `"$PWD"` for
+ * spaces-in-paths protection) survive because POSIX command substitution
+ * has its own quoting context inside `$(...)`.
+ */
+function embedPosixSubstitution(posixCode) {
+    return `'"${posixCode}"'`;
+}
+const POSIX_BARE = /^[A-Za-z0-9_\-=,:.\/!@%+]+$/;
+function quoteInsidePosixAlias(token) {
+    if (POSIX_BARE.test(token))
+        return token;
+    // No internal single quotes guaranteed by upstream validation.
+    return `'\\''${token}'\\''`;
+}
+/**
+ * Tokens with embedded single quotes can't be cleanly nested inside an outer
+ * single-quoted alias body without compounding escape layers that make the
+ * file unreadable. The UI surfaces this as an error before write.
+ *
+ * Composite segments are not checked here — their literal parts are checked
+ * via the same recursion. A `'` in a templated value's literal portion would
+ * still be unrenderable, so we walk the parts.
+ */
+export function findUnquotableTokens(segments) {
+    const out = [];
+    for (const seg of segments) {
+        if (seg.kind === "literal") {
+            if (seg.text.includes("'"))
+                out.push(seg.text);
+            continue;
+        }
+        for (const p of seg.parts) {
+            if (p.kind === "literal" && p.text.includes("'"))
+                out.push(p.text);
+        }
+    }
+    return out;
+}
+function renderFishBlock(name, segments) {
+    // Fish: `alias <name> 'claude --foo bar'` — outer single quotes, no `=`.
+    const body = segments.length === 0
+        ? ""
+        : " " + segments.map(renderFishSegment).join(" ");
+    const line = `alias ${name} 'claude${body}'`;
+    return `${BLOCK_BEGIN}\n${line}\n${BLOCK_END}\n`;
+}
+function renderFishSegment(seg) {
+    if (seg.kind === "literal")
+        return quoteFish(seg.text);
+    return seg.parts
+        .map((p) => p.kind === "literal"
+        ? quoteFish(p.text)
+        : embedFishSubstitution(p.fish))
+        .join("");
+}
+/**
+ * Fish substitution embedding mirrors POSIX. Outer `'…'` is fish's literal
+ * single-quote (no interpolation), so close-and-double-quote-reopen is the
+ * same dance: `'"(cmd)"'` becomes literal-' + `(cmd)` evaluated at expansion
+ * time + literal-'.
+ */
+function embedFishSubstitution(fishCode) {
+    return `'"${fishCode}"'`;
+}
+// ─── Splicing ─────────────────────────────────────────────────────────────
+/**
+ * Replace the existing managed block in `existing` with `block`, or append
+ * `block` to the end if no block is present. Pure function — no I/O.
+ */
+export function spliceManagedBlock(existing, block) {
+    const beginIdx = existing.indexOf(BLOCK_BEGIN);
+    if (beginIdx === -1) {
+        if (existing.length === 0)
+            return block;
+        const sep = existing.endsWith("\n") ? "" : "\n";
+        return existing + sep + "\n" + block;
+    }
+    const endIdx = existing.indexOf(BLOCK_END, beginIdx);
+    if (endIdx === -1) {
+        // Malformed block — replace from BEGIN to EOF to be safe.
+        return existing.slice(0, beginIdx) + block;
+    }
+    // Consume the trailing newline of the END marker if present.
+    let cutEnd = endIdx + BLOCK_END.length;
+    if (existing[cutEnd] === "\n")
+        cutEnd += 1;
+    return existing.slice(0, beginIdx) + block + existing.slice(cutEnd);
+}
+export async function writeAliasToShell(config, target) {
+    const args = renderArgs(config);
+    const unquotable = findUnquotableTokens(args);
+    if (unquotable.length > 0) {
+        throw new Error(`Cannot render alias: ${unquotable.length} value${unquotable.length === 1 ? "" : "s"} contain a single quote, which can't be embedded in a shell alias. Edit the offending value(s) and try again: ${unquotable
+            .map((t) => JSON.stringify(t))
+            .join(", ")}`);
+    }
+    const rendered = renderAlias(config, target.kind);
+    const existing = target.exists ? await readFile(target.path, "utf8") : "";
+    const next = spliceManagedBlock(existing, rendered.block);
+    await writeFile(target.path, next, "utf8");
+    return {
+        shell: target.kind,
+        path: target.path,
+        action: target.exists ? "updated" : "created",
+    };
+}
+/**
+ * Summarize which flags are in conflict given the current config.
+ * The UI uses this to grey out / annotate rows. The renderer enforces the
+ * same rules independently — this helper is purely for display.
+ */
+export function validateConfig(config) {
+    const issues = [];
+    // xor groups
+    const groups = new Map();
+    for (const flag of ALIAS_FLAGS) {
+        if (!flag.xorGroup)
+            continue;
+        if (!isFlagEnabled(config.flags[flag.id]))
+            continue;
+        const list = groups.get(flag.xorGroup) ?? [];
+        list.push(flag.id);
+        groups.set(flag.xorGroup, list);
+    }
+    for (const [group, ids] of groups) {
+        if (ids.length > 1) {
+            const winner = ids[0];
+            const losers = ids.slice(1);
+            for (const loser of losers) {
+                issues.push({
+                    flagId: loser,
+                    reason: `Mutually exclusive with --${winner}; will be dropped on write.`,
+                });
+            }
+        }
+    }
+    // requires
+    for (const flag of ALIAS_FLAGS) {
+        if (!flag.requires)
+            continue;
+        if (!isFlagEnabled(config.flags[flag.id]))
+            continue;
+        if (!isFlagEnabled(config.flags[flag.requires])) {
+            const dep = getFlagById(flag.requires);
+            issues.push({
+                flagId: flag.id,
+                reason: `Requires ${dep.flag}; will be dropped on write.`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Find the managed block in shell rc text, parse the alias line, and return
+ * the alias name plus the argv tokens after `claude`.
+ *
+ * Returns `null` when no managed block exists, the block is malformed, or
+ * the alias line can't be parsed. Callers treat null as "no managed alias
+ * on disk — start from defaults".
+ */
+export function parseManagedBlock(rcText) {
+    const beginIdx = rcText.indexOf(BLOCK_BEGIN);
+    if (beginIdx === -1)
+        return null;
+    const endIdx = rcText.indexOf(BLOCK_END, beginIdx);
+    if (endIdx === -1)
+        return null;
+    // Lines inside the block, sans markers.
+    const inner = rcText.slice(beginIdx + BLOCK_BEGIN.length, endIdx);
+    // Find the `alias <name>=...` line (skip blank lines, comments, the markers).
+    const aliasLine = inner
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => /^alias\s+[A-Za-z_][A-Za-z0-9_-]*\s*=/.test(l));
+    if (!aliasLine)
+        return null;
+    return parseAliasLine(aliasLine);
+}
+const ALIAS_LINE_RE = /^alias\s+([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*'(.*)'\s*$/;
+/**
+ * Parse a single `alias <name>='<body>'` line. Body is the raw text inside
+ * the outer single quotes; the tokenizer below undoes the writer's escape
+ * scheme.
+ */
+export function parseAliasLine(line) {
+    const match = ALIAS_LINE_RE.exec(line);
+    if (!match)
+        return null;
+    const [, aliasName, body] = match;
+    // First token is the command itself (claude). Drop it; we only want argv.
+    const tokens = tokenizePosixAliasBody(body);
+    if (tokens.length === 0 || tokens[0] !== "claude")
+        return null;
+    return { aliasName, args: tokens.slice(1) };
+}
+/**
+ * Tokenize the body of a POSIX alias inside the outer single quotes.
+ *
+ * Our writer emits three shapes inside the outer `'…'`:
+ *   1. Bare tokens (matching POSIX_BARE) — emitted as-is.
+ *   2. Quoted literals: `'\''text without single quotes'\''` — these survive
+ *      the outer single quotes by closing them, emitting a literal `'`,
+ *      single-quoting the inner content, then a literal `'`, and reopening.
+ *   3. Substitution embeds: `'"$(cmd)"'` — close outer ', open ", embed,
+ *      close ", reopen outer '. Result is one shell arg with the
+ *      substitution that fires on alias expansion.
+ *
+ * Reading the body left-to-right, we expect to see:
+ *   - bare chars (collect into the current token's value)
+ *   - whitespace (delimits tokens)
+ *   - `'\''<text>'\''` (collect inner text verbatim into the current token)
+ *   - `'"<sub>"'` (record as a raw substitution and unparse it back into
+ *     the closest matching template token via `unparseSubstitution`)
+ *
+ * Tokens emitted as `composite` segments (template values) re-tokenize into
+ * a single shell arg whose pieces are interleaved literal+raw. We rebuild
+ * those as `{token}` strings to match what the UI stores.
+ */
+export function tokenizePosixAliasBody(body) {
+    const tokens = [];
+    let current = "";
+    let inToken = false;
+    let i = 0;
+    const len = body.length;
+    const flush = () => {
+        if (inToken) {
+            tokens.push(current);
+            current = "";
+            inToken = false;
+        }
+    };
+    while (i < len) {
+        const ch = body[i];
+        if (ch === " " || ch === "\t") {
+            flush();
+            i += 1;
+            continue;
+        }
+        // Quoted literal: '\''…'\''
+        if (body.startsWith(`'\\''`, i)) {
+            // Skip the opening sequence.
+            i += 4;
+            const end = body.indexOf(`'\\''`, i);
+            if (end === -1)
+                return tokens; // malformed — bail, return what we have
+            current += body.slice(i, end);
+            inToken = true;
+            i = end + 4;
+            continue;
+        }
+        // Substitution embed: '"<sub>"'
+        if (body.startsWith(`'"`, i)) {
+            const inner = i + 2;
+            const close = body.indexOf(`"'`, inner);
+            if (close === -1)
+                return tokens;
+            const subCode = body.slice(inner, close);
+            const token = unparseSubstitution(subCode);
+            current += token;
+            inToken = true;
+            i = close + 2;
+            continue;
+        }
+        // Bare character.
+        current += ch;
+        inToken = true;
+        i += 1;
+    }
+    flush();
+    return tokens;
+}
+/**
+ * Map a POSIX substitution code back to its template token, if one matches.
+ * Falls through to a `$(...)` literal when no token matches — that way we
+ * preserve hand-edited substitutions as opaque values rather than dropping
+ * them.
+ *
+ * Mirror of TOKEN_TO_SUB in the writer.
+ */
+function unparseSubstitution(posixCode) {
+    switch (posixCode) {
+        case '$(basename "$PWD")':
+            return "{folder}";
+        case "$(date +%d)":
+            return "{day}";
+        case "$(date +%m)":
+            return "{month}";
+        case "$(date +%Y)":
+            return "{year}";
+        default:
+            // Unknown substitution: pass through the raw code so the user can see
+            // it in the UI and decide whether to keep it. The writer can't faithfully
+            // round-trip it, but at least we don't silently drop it.
+            return posixCode;
+    }
+}
+/**
+ * Apply parsed argv tokens to a FlagValue map. Walks the catalog in order,
+ * consuming tokens that match each flag's pattern. Tokens that don't match
+ * any flag are dropped silently (e.g. the user hand-added a flag we don't
+ * know about). Returns a fresh `Record<flagId, FlagValue>` suitable for
+ * splicing into an AliasConfig.
+ *
+ * Ordering: the writer emits flags in catalog order, so a left-to-right
+ * scan is sufficient. We pre-index by flag string for `--foo` lookups.
+ */
+export function argsToFlagValues(args) {
+    // Index every flag by its primary `flag` string AND its triStateOff variant.
+    const byFlag = new Map();
+    for (const flag of ALIAS_FLAGS) {
+        byFlag.set(flag.flag, { flag, off: false });
+        if (flag.triStateOff) {
+            byFlag.set(flag.triStateOff, { flag, off: true });
+        }
+    }
+    const out = {};
+    let i = 0;
+    while (i < args.length) {
+        const tok = args[i];
+        const entry = byFlag.get(tok);
+        if (!entry) {
+            // Unknown flag — skip this token AND its likely value, if next looks
+            // like a value (doesn't start with --). This is a best-effort skip
+            // so unknown flag pairs don't cascade-corrupt the rest of the parse.
+            i += 1;
+            if (i < args.length && !args[i].startsWith("-"))
+                i += 1;
+            continue;
+        }
+        const { flag, off } = entry;
+        const peek = () => args[i + 1];
+        const takeValue = () => {
+            const v = args[i + 1];
+            i += 2;
+            return v;
+        };
+        switch (flag.kind) {
+            case "boolean":
+                out[flag.id] = { kind: "boolean", enabled: true };
+                i += 1;
+                break;
+            case "tri-state":
+                out[flag.id] = { kind: "tri-state", state: off ? "off" : "on" };
+                i += 1;
+                break;
+            case "select": {
+                // The writer emits `--flag` alone for "bare" empty value, or
+                // `--flag <value>` for a selection. We can't tell without peeking
+                // at whether the next token is a known value.
+                const opts = flag.options ?? [];
+                const next = peek();
+                const valid = next !== undefined && opts.some((o) => o.value === next);
+                if (valid) {
+                    out[flag.id] = { kind: "select", enabled: true, value: takeValue() };
+                }
+                else {
+                    out[flag.id] = { kind: "select", enabled: true, value: "" };
+                    i += 1;
+                }
+                break;
+            }
+            case "text":
+                // `text` always emits a value; if there's no next token we treat as
+                // disabled (defensive).
+                if (peek() !== undefined) {
+                    out[flag.id] = { kind: "text", enabled: true, value: takeValue() };
+                }
+                else {
+                    out[flag.id] = { kind: "text", enabled: false, value: "" };
+                    i += 1;
+                }
+                break;
+            case "optional-text": {
+                // Optional-text: next token is the value if it doesn't look like a
+                // flag. We can't perfectly distinguish a deliberately-bare emission
+                // from one followed by an unrelated flag, but the writer's emission
+                // of bare is `flag.flag` alone with the next token being another
+                // catalog flag — so checking the lookup tells us.
+                const next = peek();
+                if (next === undefined || byFlag.has(next)) {
+                    out[flag.id] = { kind: "optional-text", enabled: true, value: "" };
+                    i += 1;
+                }
+                else {
+                    out[flag.id] = {
+                        kind: "optional-text",
+                        enabled: true,
+                        value: takeValue(),
+                    };
+                }
+                break;
+            }
+            case "text-list": {
+                // Each instance of the flag emits one value. Collect repeats.
+                const values = [];
+                // Consume the first pair.
+                if (peek() !== undefined)
+                    values.push(takeValue());
+                else
+                    i += 1;
+                // Consume additional pairs of the same flag.
+                while (i < args.length && args[i] === flag.flag) {
+                    if (i + 1 < args.length) {
+                        values.push(args[i + 1]);
+                        i += 2;
+                    }
+                    else {
+                        i += 1;
+                        break;
+                    }
+                }
+                out[flag.id] = {
+                    kind: "text-list",
+                    enabled: true,
+                    values,
+                };
+                break;
+            }
+            case "multi-with-custom": {
+                // Either bare `--debug` (no filter) or `--debug a,b,c`.
+                const next = peek();
+                if (next === undefined || byFlag.has(next)) {
+                    out[flag.id] = {
+                        kind: "multi-with-custom",
+                        enabled: true,
+                        picked: [],
+                        custom: [],
+                    };
+                    i += 1;
+                }
+                else {
+                    const tokens = takeValue()
+                        .split(",")
+                        .map((s) => s.trim())
+                        .filter((s) => s.length > 0);
+                    const picklist = new Set(flag.picklist ?? []);
+                    const picked = [];
+                    const custom = [];
+                    for (const t of tokens) {
+                        if (picklist.has(t))
+                            picked.push(t);
+                        else
+                            custom.push(t);
+                    }
+                    out[flag.id] = {
+                        kind: "multi-with-custom",
+                        enabled: true,
+                        picked,
+                        custom,
+                    };
+                }
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * High-level entry point: read shell rc text, parse the managed block, and
+ * return a populated flag map plus the parsed alias name. Returns null when
+ * there's no managed block to parse from.
+ */
+export function parseAliasFromRc(rcText) {
+    const parsed = parseManagedBlock(rcText);
+    if (!parsed || !parsed.aliasName)
+        return null;
+    return {
+        aliasName: parsed.aliasName,
+        flags: argsToFlagValues(parsed.args),
+    };
+}