claudeup 4.18.0 → 4.22.0

package/src/prerunner/index.ts

@@ -1,31 +1,32 @@
-import fs from "fs-extra";
-import path from "node:path";
 import os from "node:os";
-import { UpdateCache } from "../services/update-cache.js";
-import {
-	getAvailablePlugins,
-	clearMarketplaceCache,
-} from "../services/plugin-manager.js";
+import path from "node:path";
+import fs from "fs-extra";
+import { isClaudeAvailable, updatePlugin } from "../services/claude-cli.js";
 import { runClaude } from "../services/claude-runner.js";
 import {
-	recoverMarketplaceSettings,
-	migrateMarketplaceRename,
 	cleanupExtraKnownMarketplaces,
+	gapFillInstalledPluginVersions,
+	migrateMarketplaceRename,
 	readGlobalSettings,
-	writeGlobalSettings,
+	recoverMarketplaceSettings,
 	saveGlobalInstalledPluginVersion,
-	gapFillInstalledPluginVersions,
+	writeGlobalSettings,
 } from "../services/claude-settings.js";
-import {
-	checkPluginVersionMismatches,
-	formatMismatchWarning,
-} from "../services/plugin-version-check.js";
-import { updatePlugin, isClaudeAvailable } from "../services/claude-cli.js";
-import { autoAddMissingMarketplaces } from "../services/marketplace-sync.js";
 import {
 	checkGitignore,
 	formatPrerunWarning as formatGitignoreWarning,
 } from "../services/gitignore-prerun.js";
+import { refreshRegisteredMarketplaces } from "../services/marketplace-refresh.js";
+import { autoAddMissingMarketplaces } from "../services/marketplace-sync.js";
+import {
+	clearMarketplaceCache,
+	getAvailablePlugins,
+} from "../services/plugin-manager.js";
+import {
+	checkPluginVersionMismatches,
+	formatMismatchWarning,
+} from "../services/plugin-version-check.js";
+import { UpdateCache } from "../services/update-cache.js";
 
 export interface PrerunOptions {
 	force?: boolean; // Bypass cache and force update check
@@ -133,9 +134,7 @@ export async function prerunClaude(
 		// otherwise a freshly cloned repo whose only @magus references live
 		// in project settings looks "clean" from the global-scope view.
 		if (await isClaudeAvailable()) {
-			const addedMarketplaces = await autoAddMissingMarketplaces(
-				process.cwd(),
-			);
+			const addedMarketplaces = await autoAddMissingMarketplaces(process.cwd());
 			if (addedMarketplaces.length > 0) {
 				console.log(
 					`✓ Auto-added marketplace(s): ${addedMarketplaces.join(", ")}`,
@@ -238,20 +237,40 @@ export async function prerunClaude(
 				console.log(
 					`✓ Re-registered as GitHub source: ${recovery.reregistered.join(", ")}`,
 				);
-				// Trigger marketplace update for re-registered entries so the local
-				// clone gets refreshed with the latest plugins.
+				// Re-registration only rewrites known_marketplaces.json (directory →
+				// github source); it does NOT create the on-disk clone. Clone any whose
+				// directory is missing, using the NON-DESTRUCTIVE `marketplace add` —
+				// never `marketplace update`, which deletes the directory before
+				// re-cloning and can leave it permanently gone on failure (see
+				// marketplace-refresh.ts / marketplace-sync.ts). Clones that already
+				// exist are left to STEP 1.7's safe `git pull --ff-only`.
 				const cliAvailable = await isClaudeAvailable();
 				if (cliAvailable) {
-					const { updateMarketplace } = await import(
-						"../services/claude-cli.js"
+					const { addMarketplace } = await import("../services/claude-cli.js");
+					const { defaultMarketplaces } = await import(
+						"../data/marketplaces.js"
+					);
+					const marketplacesDir = path.join(
+						os.homedir(),
+						".claude",
+						"plugins",
+						"marketplaces",
 					);
 					for (const mpName of recovery.reregistered) {
+						// Already on disk → STEP 1.7 fast-forwards it; nothing to clone.
+						if (await fs.pathExists(path.join(marketplacesDir, mpName))) {
+							continue;
+						}
+						const repo = defaultMarketplaces.find(
+							(m) => m.name === mpName,
+						)?.source.repo;
+						if (!repo) continue;
 						try {
-							await updateMarketplace(mpName);
-							console.log(`✓ Updated marketplace: ${mpName}`);
+							await addMarketplace(repo);
+							console.log(`✓ Cloned re-registered marketplace: ${mpName}`);
 						} catch (error) {
 							console.warn(
-								`⚠ Failed to update marketplace ${mpName}:`,
+								`⚠ Failed to clone marketplace ${mpName}:`,
 								error instanceof Error ? error.message : "Unknown error",
 							);
 						}
@@ -259,6 +278,22 @@ export async function prerunClaude(
 				}
 			}
 
+			// STEP 1.7: Fast-forward the on-disk clones of every registered
+			// marketplace. Recovery above only *clones* re-registered ones that were
+			// missing; nothing else advances an existing healthy clone, so updated
+			// plugin setup metadata — e.g. a pinned dependency version — is never seen
+			// even though the fetched plugin list is current. Non-destructive
+			// `git pull --ff-only`: a failed pull leaves the clone stale, never gone.
+			const mpRefresh = await refreshRegisteredMarketplaces();
+			if (mpRefresh.refreshed.length > 0) {
+				console.log(
+					`✓ Refreshed marketplaces: ${mpRefresh.refreshed.join(", ")}`,
+				);
+			}
+			for (const name of mpRefresh.failed) {
+				console.warn(`⚠ Failed to refresh marketplace: ${name}`);
+			}
+
 			// STEP 2: Clear cache to force fresh plugin info
 			clearMarketplaceCache();
 

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

@@ -16,7 +16,14 @@ import {
   getFlagById,
   type AliasFlag,
 } from "../data/alias-flags.js";
-import type { AliasConfig, FlagValue } from "./alias-store.js";
+import {
+  CHANNELS_FLAG_ID,
+  defaultValueFor,
+  derivedChannelValues,
+  listValues,
+  type AliasConfig,
+  type FlagValue,
+} from "./alias-store.js";
 
 export type ShellKind = "zsh" | "bash" | "fish";
 
@@ -128,7 +135,16 @@ export function renderArgs(config: AliasConfig): Segment[] {
     const value = config.flags[flag.id];
     if (!value) continue;
 
-    const rendered = renderFlag(flag, value);
+    // `--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);
@@ -184,6 +200,26 @@ function templatedSegment(value: string): Segment {
   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":
@@ -455,9 +491,21 @@ export interface WriteResult {
   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);
@@ -472,7 +520,17 @@ export async function writeAliasToShell(
   }
   const rendered = renderAlias(config, target.kind);
   const existing = target.exists ? await readFile(target.path, "utf8") : "";
-  const next = spliceManagedBlock(existing, rendered.block);
+
+  // 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,
@@ -712,6 +770,35 @@ function unparseSubstitution(posixCode: string): string {
  * 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) {
@@ -722,16 +809,22 @@ export function argsToFlagValues(args: string[]): Record<string, FlagValue> {
   }
 
   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 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.
+      // 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("-")) i += 1;
+      if (i < args.length && !args[i].startsWith("-")) {
+        leftovers.push(args[i]);
+        i += 1;
+      }
       continue;
     }
     const { flag, off } = entry;
@@ -852,7 +945,26 @@ export function argsToFlagValues(args: string[]): Record<string, FlagValue> {
       }
     }
   }
-  return out;
+
+  // 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 };
 }
 
 /**
@@ -871,3 +983,265 @@ export function parseAliasFromRc(rcText: string): {
     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;
+}

package/src/services/alias-store.ts

@@ -79,6 +79,66 @@ export function defaultAliasConfig(): AliasConfig {
   return { aliasName: DEFAULT_ALIAS_NAME, flags };
 }
 
+// ─── Channels ⊇ dev-load (derive-on-display) ───────────────────────────
+//
+// `--channels` is the approved-channel allowlist; `--dangerously-load-
+// development-channels` sideloads channels for local dev. A dev-loaded
+// channel must also run, so at the COMMAND LINE the channels list is the
+// union of both. We do NOT store that union — provenance would be lost
+// (you couldn't tell an own channel from a derived one). Instead:
+//   - `channels.values` holds the user's OWN approved channels only.
+//   - The dev-load flag is the single source of truth for derived channels.
+//   - The editor shows them as a separate read-only section (display).
+//   - The writer unions `own ∪ dev-load(if enabled)` at RENDER time.
+// This keeps the two lists distinct everywhere except the emitted alias.
+
+/** Id of the channels allowlist flag. */
+export const CHANNELS_FLAG_ID = "channels";
+/** Id of the dev-load flag whose values are derived into channels. */
+export const DEVLOAD_FLAG_ID = "dangerously-load-development-channels";
+
+/** Read the value list off a flag value, or `[]` for non-list kinds. */
+export function listValues(v: FlagValue | undefined): string[] {
+  return v && v.kind === "text-list" ? v.values : [];
+}
+
+/**
+ * Channels that `--channels` derives from the dev-load flag for DISPLAY and
+ * for the render-time union: the dev-load flag's values, but only when that
+ * flag is enabled (a disabled dev-load contributes nothing to the alias).
+ */
+export function derivedChannelValues(
+  flags: Record<string, FlagValue>,
+): string[] {
+  const devload = flags[DEVLOAD_FLAG_ID];
+  if (!devload || devload.kind !== "text-list" || !devload.enabled) return [];
+  return devload.values;
+}
+
+/**
+ * Return a new flags map with `value` removed from the dev-load flag (the
+ * SOURCE of derived channels). Used when the user deletes a "Dev-loaded
+ * channels" row inside the --channels editor: the deletion must land on the
+ * source flag, never on `channels.values`. Disables dev-load when emptied so
+ * it stops emitting. Pure — leaves `channels.values` untouched.
+ */
+export function withoutDerivedChannel(
+  flags: Record<string, FlagValue>,
+  value: string,
+): Record<string, FlagValue> {
+  const cur = flags[DEVLOAD_FLAG_ID];
+  if (!cur || cur.kind !== "text-list") return flags;
+  const values = cur.values.filter((v) => v !== value);
+  return {
+    ...flags,
+    [DEVLOAD_FLAG_ID]: {
+      kind: "text-list",
+      enabled: values.length > 0 && cur.enabled,
+      values,
+    },
+  };
+}
+
 export function defaultValueFor(flag: AliasFlag): FlagValue {
   switch (flag.kind) {
     case "boolean":