claudeup 4.17.0 → 4.19.0

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

@@ -0,0 +1,1247 @@
+/**
+ * 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,
+  type AliasFlag,
+} from "../data/alias-flags.js";
+import {
+  CHANNELS_FLAG_ID,
+  defaultValueFor,
+  derivedChannelValues,
+  listValues,
+  type AliasConfig,
+  type FlagValue,
+} from "./alias-store.js";
+
+export type ShellKind = "zsh" | "bash" | "fish";
+
+export interface ShellTarget {
+  kind: ShellKind;
+  /** Absolute path to the rc file. */
+  path: string;
+  /** True if the file currently exists on disk. */
+  exists: boolean;
+  /** True if `$SHELL` points at this shell — the default write target. */
+  isDefault: boolean;
+}
+
+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: string = homedir(),
+  shellEnv: string = process.env.SHELL ?? "",
+): Promise<ShellTarget[]> {
+  const candidates: Array<{ kind: ShellKind; path: string }> = [
+    { 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: ShellTarget[] = [];
+  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: string): ShellKind | null {
+  if (shellEnv.endsWith("/zsh")) return "zsh";
+  if (shellEnv.endsWith("/bash")) return "bash";
+  if (shellEnv.endsWith("/fish")) return "fish";
+  return null;
+}
+
+// ─── Rendering ────────────────────────────────────────────────────────────
+
+/**
+ * One emitted argv token in the alias body. A token can be:
+ *
+ *  - A plain `literal` token like `--ide` or `low` (gets single-quoted in
+ *    the outer alias body).
+ *  - A `composite` token, where the actual argv value is the concatenation
+ *    of multiple parts. Used by templated flags so a value like
+ *    `dev-{folder}-{day}` becomes ONE shell argument with two embedded
+ *    substitutions, not three separate tokens.
+ *
+ * Composite parts are rendered together with no separating whitespace and
+ * with the appropriate close-outer / reopen-outer dance per shell.
+ */
+export type Segment =
+  | { kind: "literal"; text: string }
+  | { kind: "composite"; parts: SegmentPart[] };
+
+export type SegmentPart =
+  | { kind: "literal"; text: string }
+  | { kind: "raw"; posix: string; fish: string };
+
+/**
+ * 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: AliasConfig): Segment[] {
+  const out: Segment[] = [];
+  const seenXor = new Set<string>();
+
+  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;
+
+    // `--channels` is the union (own ∪ dev-load-if-enabled), computed here at
+    // render time — the union is NOT stored, so own/derived stay distinct in
+    // the UI. A dev-loaded channel must run, so derived values force `--channels`
+    // to emit even when the user's own channels list is disabled/empty.
+    const renderValue =
+      flag.id === CHANNELS_FLAG_ID
+        ? channelsUnionValue(config.flags, value)
+        : value;
+
+    const rendered = renderFlag(flag, renderValue);
+    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: AliasConfig): string[] {
+  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: FlagValue | undefined): boolean {
+  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: string): Segment {
+  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: string): Segment {
+  const parts = expandTemplateValue(value);
+  if (parts.length === 1 && parts[0].kind === "literal") {
+    return { kind: "literal", text: parts[0].text };
+  }
+  return { kind: "composite", parts };
+}
+
+/**
+ * Build the effective `--channels` value for rendering: the user's own
+ * channels unioned with the dev-load flag's values (when dev-load is enabled),
+ * deduped, own-first. Enabled when EITHER source contributes a value, so a
+ * dev-loaded channel still forces `--channels` to emit even if the user never
+ * enabled their own channels list. The union lives here, at render time — it
+ * is never written back to `channels.values`, so provenance is preserved.
+ */
+function channelsUnionValue(
+  flags: Record<string, FlagValue>,
+  own: FlagValue,
+): FlagValue {
+  const ownValues = own.kind === "text-list" && own.enabled
+    ? listValues(own)
+    : [];
+  const derived = derivedChannelValues(flags);
+  const merged = dedupe([...ownValues, ...derived]).filter((v) => v.length > 0);
+  return { kind: "text-list", enabled: merged.length > 0, values: merged };
+}
+
+function renderFlag(flag: AliasFlag, value: FlagValue): Segment[] {
+  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: Segment[] = [];
+      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: Record<string, { posix: string; fish: string }> = {
+  "{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: string): SegmentPart[] {
+  const out: SegmentPart[] = [];
+  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: string[]): string[] {
+  return Array.from(new Set(arr));
+}
+
+/**
+ * Fish quoting. Fish single quotes are simpler — only `\` and `'` need escapes.
+ */
+function quoteFish(s: string): string {
+  return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+
+export interface RenderedAlias {
+  shell: ShellKind;
+  /** The full block including BEGIN/END markers, ending with a newline. */
+  block: string;
+}
+
+export function renderAlias(
+  config: AliasConfig,
+  shell: ShellKind,
+): RenderedAlias {
+  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: string, segments: Segment[]): string {
+  // 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: Segment): string {
+  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: string): string {
+  return `'"${posixCode}"'`;
+}
+
+const POSIX_BARE = /^[A-Za-z0-9_\-=,:.\/!@%+]+$/;
+
+function quoteInsidePosixAlias(token: string): string {
+  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: Segment[]): string[] {
+  const out: string[] = [];
+  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: string, segments: Segment[]): string {
+  // 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: Segment): string {
+  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: string): string {
+  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: string, block: string): string {
+  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 interface WriteResult {
+  shell: ShellKind;
+  path: string;
+  /** "created" if the file did not exist; "updated" otherwise. */
+  action: "created" | "updated";
+}
+
+export interface WriteOptions {
+  /**
+   * Line range [start, end] (zero-based, inclusive) of a hand-written alias
+   * to REPLACE in place with the managed block — the adoption path. Only
+   * honored when the file has no managed block yet (a first write after
+   * adoption); subsequent writes find the markers and ignore this. Guarantees
+   * the adopted line is removed so no duplicate alias survives.
+   */
+  adoptLineRange?: [number, number];
+}
+
+export async function writeAliasToShell(
+  config: AliasConfig,
+  target: ShellTarget,
+  options: WriteOptions = {},
+): Promise<WriteResult> {
+  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") : "";
+
+  // Adoption: when a line range was supplied AND the file has no managed block
+  // yet, replace the adopted alias line in place — the managed block takes its
+  // slot, so the original can't survive as a duplicate. Once a managed block
+  // exists, marker-based splicing is position-independent and takes over.
+  const hasBlock = existing.includes(BLOCK_BEGIN);
+  const next =
+    options.adoptLineRange && !hasBlock
+      ? spliceManagedBlockAtRange(existing, rendered.block, options.adoptLineRange)
+      : spliceManagedBlock(existing, rendered.block);
+
+  await writeFile(target.path, next, "utf8");
+  return {
+    shell: target.kind,
+    path: target.path,
+    action: target.exists ? "updated" : "created",
+  };
+}
+
+// ─── Validation summary (UI helper) ───────────────────────────────────────
+
+export interface FlagValidationIssue {
+  flagId: string;
+  reason: string;
+}
+
+/**
+ * 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: AliasConfig): FlagValidationIssue[] {
+  const issues: FlagValidationIssue[] = [];
+
+  // xor groups
+  const groups = new Map<string, string[]>();
+  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;
+}
+
+// ─── Parser ──────────────────────────────────────────────────────────────
+//
+// Reverses what the writer emits. Read shell rc text, extract the managed
+// block, find the `alias <name>='claude <body>'` line, tokenize the body
+// into argv strings (undoing POSIX nested-quote escapes and template
+// substitution embeds), then map argv to a FlagValue per the catalog.
+//
+// Only the POSIX dialect (zsh/bash) is supported on parse today. Fish round-
+// trip isn't symmetric to POSIX in our writer's output anyway (fish's auto-
+// concat of adjacent quoted strings makes parsing more involved), and the
+// vast majority of users are on zsh.
+
+export interface ParseResult {
+  aliasName: string | null;
+  args: string[];
+}
+
+/**
+ * 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: string): ParseResult | null {
+  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: string): ParseResult | null {
+  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: string): string[] {
+  const tokens: string[] = [];
+  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: string): string {
+  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: string[]): Record<string, FlagValue> {
+  return argsToFlagValuesWithLeftovers(args).flags;
+}
+
+/**
+ * Result of {@link argsToFlagValuesWithLeftovers}: the parsed flag map plus the
+ * argv tokens that didn't map to any catalog flag.
+ *
+ * `leftovers` is the lossless gate for alias adoption: a hand-written alias is
+ * safe to absorb into the managed block ONLY when `leftovers` is empty, i.e.
+ * every token was recognized. Any leftover token would be silently lost if we
+ * deleted the original line and re-rendered from the parsed flags, so a
+ * non-empty `leftovers` means "import the flags for the user to see, but do NOT
+ * take ownership / do NOT remove their line".
+ */
+export interface ParsedFlagsWithLeftovers {
+  flags: Record<string, FlagValue>;
+  /** argv tokens that matched no catalog flag (and so would be dropped). */
+  leftovers: string[];
+}
+
+/**
+ * Like {@link argsToFlagValues}, but reports every token it couldn't map to a
+ * catalog flag. Unknown `--flag value` pairs contribute BOTH tokens to
+ * `leftovers` (the flag and its consumed value) so the adoption gate sees the
+ * full extent of what wouldn't round-trip.
+ */
+export function argsToFlagValuesWithLeftovers(
+  args: string[],
+): ParsedFlagsWithLeftovers {
+  // Index every flag by its primary `flag` string AND its triStateOff variant.
+  const byFlag = new Map<string, { flag: AliasFlag; off?: boolean }>();
+  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: Record<string, FlagValue> = {};
+  const leftovers: string[] = [];
+  let i = 0;
+  while (i < args.length) {
+    const tok = args[i];
+    const entry = byFlag.get(tok);
+    if (!entry) {
+      // Unknown token — record it. If the next token looks like its value
+      // (doesn't start with `-`), consume and record that too so unknown
+      // flag/value pairs don't cascade-corrupt the rest of the parse, and so
+      // the adoption gate sees the full unrecognized span.
+      leftovers.push(tok);
+      i += 1;
+      if (i < args.length && !args[i].startsWith("-")) {
+        leftovers.push(args[i]);
+        i += 1;
+      }
+      continue;
+    }
+    const { flag, off } = entry;
+    const peek = (): string | undefined => args[i + 1];
+    const takeValue = (): string => {
+      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: string[] = [];
+        // 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: string[] = [];
+          const custom: string[] = [];
+          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;
+      }
+    }
+  }
+
+  // Restore channels provenance: the writer emits `--channels` as
+  // (own ∪ dev-load), so a naive parse folds derived values back into
+  // channels.values. Subtract the dev-load values (when that flag was
+  // emitted/enabled) so channels.values holds only the user's OWN channels —
+  // the derived ones come from the dev-load flag at display/render time.
+  const channels = out[CHANNELS_FLAG_ID];
+  const derived = derivedChannelValues(out);
+  if (channels && channels.kind === "text-list" && derived.length > 0) {
+    const ownOnly = channels.values.filter((v) => !derived.includes(v));
+    out[CHANNELS_FLAG_ID] = {
+      kind: "text-list",
+      // Keep enabled only if the user has their own channels; a channels list
+      // that was purely derived shouldn't appear enabled after the subtraction.
+      enabled: ownOnly.length > 0,
+      values: ownOnly,
+    };
+  }
+
+  return { flags: out, leftovers };
+}
+
+/**
+ * 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: string): {
+  aliasName: string;
+  flags: Record<string, FlagValue>;
+} | null {
+  const parsed = parseManagedBlock(rcText);
+  if (!parsed || !parsed.aliasName) return null;
+  return {
+    aliasName: parsed.aliasName,
+    flags: argsToFlagValues(parsed.args),
+  };
+}
+
+// ─── Adoption (detect & offer to import a hand-written alias) ───────────────
+//
+// When the screen opens and there is NO managed block, the user may still have
+// a hand-written `alias c='claude …'` line elsewhere in the rc file. Rather
+// than ignore it (and look broken), we DETECT it and OFFER to adopt it: import
+// its flags into the editor and, on the next write, replace that line in place
+// with the managed block so ownership transfers cleanly with no duplicate.
+//
+// Safety is built on a single invariant: we only mark an alias `lossless` —
+// and therefore safe to remove — when every token round-trips. Two checks:
+//   1. Leftover-empty: every argv token mapped to a catalog flag.
+//   2. Fixpoint: re-rendering the parsed flags and re-parsing yields the same
+//      flag map (catches peek-based mis-maps that consume a token into the
+//      wrong bucket without surfacing as a leftover).
+// Both are order- and quote-insensitive by construction. A NON-lossless alias
+// is still offered (the user sees its recognized flags) but its original line
+// is never removed — we keep what we couldn't fully understand.
+
+/**
+ * A hand-written `claude`-wrapping alias found OUTSIDE the managed block.
+ */
+export interface AdoptableAlias {
+  /** The alias name (e.g. `c`). */
+  name: string;
+  /** Parsed flag values from the alias body. */
+  flags: Record<string, FlagValue>;
+  /**
+   * Zero-based line indices [start, end] of the alias line in the rc file.
+   * Single-line today (start === end), but kept as a range so the splice
+   * helper has the exact span to replace.
+   */
+  lineRange: [number, number];
+  /** argv tokens that didn't map to any catalog flag (data we'd drop). */
+  leftovers: string[];
+  /**
+   * True when the alias round-trips exactly: leftovers empty AND the parsed
+   * flags survive a render→reparse fixpoint. Only a lossless alias may have
+   * its original line removed on adoption.
+   */
+  lossless: boolean;
+  /** The raw alias line, verbatim (for display / preservation). */
+  rawLine: string;
+  /**
+   * Other top-level `claude`-wrapping alias lines we found but did NOT pick.
+   * Surfaced so the UI can note "also found N other claude aliases" rather
+   * than silently choosing the first.
+   */
+  others: string[];
+}
+
+const ANY_ALIAS_LINE_RE =
+  /^alias\s+([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(['"])(.*)\2\s*$/;
+
+/**
+ * Tokenize a general (hand-written) POSIX alias body into argv strings.
+ *
+ * Unlike {@link tokenizePosixAliasBody} — which only undoes OUR writer's escape
+ * scheme — this handles the shapes a human would type: bare words, single-
+ * quoted runs (literal, no escapes), and double-quoted runs (we treat the
+ * content literally; we do NOT expand `$VAR` or `$(cmd)`). Adjacent quoted and
+ * bare pieces with no whitespace between them concatenate into one argv token,
+ * matching shell word-joining (`foo' bar'` → `foo bar`).
+ *
+ * Returns `null` for anything we can't cleanly tokenize: unterminated quotes,
+ * or a body containing a shell substitution (`$(`, backtick) or variable (`$`)
+ * — those can't be faithfully represented as a static flag value, so the
+ * caller treats the whole alias as not-adoptable rather than guessing.
+ */
+export function tokenizeGeneralAliasBody(body: string): string[] | null {
+  const tokens: string[] = [];
+  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;
+    }
+
+    // Bail on dynamic content — we can't round-trip a variable/substitution.
+    if (ch === "$" || ch === "`") return null;
+
+    if (ch === "'") {
+      // Single-quoted run: literal until the next single quote.
+      const end = body.indexOf("'", i + 1);
+      if (end === -1) return null; // unterminated
+      current += body.slice(i + 1, end);
+      inToken = true;
+      i = end + 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      // Double-quoted run: literal until the next double quote. We reject any
+      // `$` or backtick inside (caught at the top of the loop on the next
+      // pass only if unquoted — so scan the run explicitly here).
+      const end = body.indexOf('"', i + 1);
+      if (end === -1) return null; // unterminated
+      const inner = body.slice(i + 1, end);
+      if (inner.includes("$") || inner.includes("`")) return null;
+      current += inner;
+      inToken = true;
+      i = end + 1;
+      continue;
+    }
+
+    // Bare character.
+    current += ch;
+    inToken = true;
+    i += 1;
+  }
+  flush();
+  return tokens;
+}
+
+/**
+ * Parse a single hand-written `alias <name>=<quote><body><quote>` line into an
+ * AdoptableAlias (sans `lineRange`/`others`, which the scanner fills in), or
+ * null when the line isn't a `claude`-wrapping alias we can tokenize.
+ */
+function parseAdoptableLine(line: string): Omit<
+  AdoptableAlias,
+  "lineRange" | "others"
+> | null {
+  const match = ANY_ALIAS_LINE_RE.exec(line.trim());
+  if (!match) return null;
+  const [, name, , body] = match;
+  const tokens = tokenizeGeneralAliasBody(body);
+  if (!tokens || tokens.length === 0 || tokens[0] !== "claude") return null;
+
+  const args = tokens.slice(1);
+  const { flags, leftovers } = argsToFlagValuesWithLeftovers(args);
+
+  // Fixpoint: render the parsed flags back to tokens and re-parse. If the
+  // result differs, a token was mis-bucketed (e.g. a select value mistaken
+  // for bare). Only an exact fixpoint with no leftovers is lossless.
+  const config: AliasConfig = { aliasName: name, flags: withDefaults(flags) };
+  const reparsed = argsToFlagValues(renderArgsAsTokens(config));
+  const fixpoint = flagsDeepEqual(withDefaults(flags), withDefaults(reparsed));
+  const lossless = leftovers.length === 0 && fixpoint;
+
+  return { name, flags, leftovers, lossless, rawLine: line };
+}
+
+/**
+ * Scan rc text for a top-level, hand-written `claude`-wrapping alias OUTSIDE
+ * the managed block. Returns the first such alias (with any others noted), or
+ * null when none is found.
+ *
+ * "Top-level" = the line's indentation is zero. We deliberately skip indented
+ * lines: an alias nested in a function or `if` block can't be replaced by the
+ * managed block without dragging the block into that scope.
+ *
+ * Lines inside an existing managed block are ignored — adoption is only for
+ * the no-managed-block case (the screen's mount checks that separately, but we
+ * guard here too so the function is correct in isolation).
+ */
+export function findAdoptableAlias(rcText: string): AdoptableAlias | null {
+  const lines = rcText.split("\n");
+
+  // Compute the [begin, end] line span of the managed block, if present, so we
+  // can exclude any alias inside it.
+  let blockStart = -1;
+  let blockEnd = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(BLOCK_BEGIN)) blockStart = i;
+    else if (lines[i].includes(BLOCK_END)) {
+      blockEnd = i;
+      break;
+    }
+  }
+  const insideBlock = (i: number) =>
+    blockStart !== -1 && blockEnd !== -1 && i >= blockStart && i <= blockEnd;
+
+  let picked: AdoptableAlias | null = null;
+  const others: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (insideBlock(i)) continue;
+    // Top-level only: no leading whitespace.
+    if (/^\s/.test(line)) continue;
+    const parsed = parseAdoptableLine(line);
+    if (!parsed) continue;
+    if (picked === null) {
+      picked = { ...parsed, lineRange: [i, i], others: [] };
+    } else {
+      others.push(line.trim());
+    }
+  }
+
+  if (picked) picked.others = others;
+  return picked;
+}
+
+/**
+ * Replace a line range in `existing` (inclusive, zero-based) with `block`.
+ * Used to absorb an adopted hand-written alias: the original line is removed
+ * and the managed block takes its place, guaranteeing no duplicate alias.
+ * Pure function — no I/O. Falls back to {@link spliceManagedBlock} semantics
+ * (append) when the range is out of bounds.
+ */
+export function spliceManagedBlockAtRange(
+  existing: string,
+  block: string,
+  range: [number, number],
+): string {
+  const lines = existing.split("\n");
+  const [start, end] = range;
+  if (start < 0 || end >= lines.length || start > end) {
+    return spliceManagedBlock(existing, block);
+  }
+  // `block` ends with a newline; splice it as its own line(s) where the old
+  // alias line was. Rejoin and drop the duplicate trailing newline `block`
+  // would introduce when followed by more lines.
+  const before = lines.slice(0, start);
+  const after = lines.slice(end + 1);
+  const blockLines = block.replace(/\n$/, "").split("\n");
+  return [...before, ...blockLines, ...after].join("\n");
+}
+
+/** Fill any catalog flags missing from a partial map with their defaults. */
+function withDefaults(
+  partial: Record<string, FlagValue>,
+): Record<string, FlagValue> {
+  const out: Record<string, FlagValue> = {};
+  for (const flag of ALIAS_FLAGS) {
+    out[flag.id] = partial[flag.id] ?? defaultValueFor(flag);
+  }
+  return out;
+}
+
+/** Deep-equal two flag maps via per-key JSON compare (small maps). */
+function flagsDeepEqual(
+  a: Record<string, FlagValue>,
+  b: Record<string, FlagValue>,
+): boolean {
+  const aKeys = Object.keys(a).sort();
+  const bKeys = Object.keys(b).sort();
+  if (aKeys.length !== bKeys.length) return false;
+  for (let i = 0; i < aKeys.length; i++) {
+    if (aKeys[i] !== bKeys[i]) return false;
+  }
+  for (const k of aKeys) {
+    if (JSON.stringify(a[k]) !== JSON.stringify(b[k])) return false;
+  }
+  return true;
+}