claudeup 4.18.0 → 4.22.0

package/bin/claudeup.js

@@ -1,24 +1,48 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
+/**
+ * claudeup launcher.
+ *
+ * Prefers a prebuilt, self-contained binary shipped as a per-platform
+ * optionalDependency (claudeup-<platform>-<arch>) — that binary embeds the Bun
+ * runtime, so it runs without Bun installed. Falls back to running from source
+ * via Bun for dev checkouts and unsupported platforms.
+ */
 
-// Check Bun version
-const bunVersion = process.versions.bun;
-if (!bunVersion) {
-  console.error('Error: claudeup v3.0.0+ requires Bun runtime.');
-  console.error('Please install Bun: https://bun.sh');
-  console.error('');
-  console.error('Quick install:');
-  console.error('  curl -fsSL https://bun.sh/install | bash');
-  process.exit(1);
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+
+const require = createRequire(import.meta.url);
+const args = process.argv.slice(2);
+const { platform, arch } = process;
+
+// 1. Prefer the prebuilt platform binary.
+const pkgName = `claudeup-${platform}-${arch}`;
+let binaryPath = null;
+try {
+	const pkgJson = require.resolve(`${pkgName}/package.json`);
+	const candidate = join(dirname(pkgJson), "bin", "claudeup");
+	if (existsSync(candidate)) binaryPath = candidate;
+} catch {
+	// optional dep not installed for this platform — fall through
 }
 
-const [major] = bunVersion.split('.').map(Number);
-if (major < 1) {
-  console.error(`Error: claudeup requires Bun >=1.0.0 (current: ${bunVersion})`);
-  console.error('Please upgrade Bun: bun upgrade');
-  process.exit(1);
+if (binaryPath) {
+	const result = spawnSync(binaryPath, args, { stdio: "inherit" });
+	process.exit(result.status ?? 0);
 }
 
-import('../src/main.tsx').catch((err) => {
-  console.error('Failed to start claudeup:', err.message);
-  process.exit(1);
-});
+// 2. Fallback: run from source via Bun.
+const here = dirname(fileURLToPath(import.meta.url));
+const mainSrc = join(here, "..", "src", "main.tsx");
+const bunRun = spawnSync("bun", [mainSrc, ...args], { stdio: "inherit" });
+if (bunRun.error) {
+	console.error(
+		`claudeup: no prebuilt binary for ${platform}-${arch}, and Bun is not installed.`,
+	);
+	console.error("Install Bun (https://bun.sh) or use a supported platform.");
+	process.exit(1);
+}
+process.exit(bunRun.status ?? 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.18.0",
+  "version": "4.22.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -10,15 +10,14 @@
   "scripts": {
     "start": "bun run src/main.tsx",
     "dev": "bun --watch src/main.tsx",
-    "lint": "npm run eslint",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
     "format": "biome format --write src/",
-    "eslint": "eslint \"**/*.{js,cjs,ts,mjs,jsx,tsx}\"",
-    "lintfix": "npm run eslint -- --fix",
-    "postlint": "template-oss-check",
-    "template-oss-apply": "template-oss-apply --force",
-    "snap": "tap",
-    "test": "tap",
-    "posttest": "npm run lint"
+    "test": "bun test",
+    "test:ci": "bun scripts/test-isolated.ts",
+    "test:update": "bun test --update-snapshots",
+    "build:binaries": "bun scripts/build-binaries.ts",
+    "check:optional-deps": "bun scripts/check-optional-deps.ts"
   },
   "keywords": [
     "claude",
@@ -45,7 +44,8 @@
   },
   "files": [
     "bin/",
-    "src/"
+    "src/",
+    "scripts/"
   ],
   "dependencies": {
     "@opentui/core": "^0.1.75",
@@ -63,14 +63,9 @@
     "@types/semver": "^7.5.8",
     "typescript": "^5.6.3"
   },
-  "templateOSS": {
-    "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.",
-    "version": "4.25.1"
-  },
-  "tap": {
-    "nyc-arg": [
-      "--exclude",
-      "tap-snapshots/**"
-    ]
+  "optionalDependencies": {
+    "claudeup-darwin-arm64": "4.22.0",
+    "claudeup-darwin-x64": "4.22.0",
+    "claudeup-linux-x64": "4.22.0"
   }
 }

package/scripts/build-binaries.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env bun
+/**
+ * Build per-platform, self-contained claudeup binaries and their npm packages.
+ *
+ * Each target is compiled with `bun build --compile --target=bun-<os>-<arch>`,
+ * producing a binary that embeds the Bun runtime (runs without Bun installed).
+ * The output is a publishable package per platform under dist-binaries/:
+ *
+ *   dist-binaries/claudeup-darwin-arm64/
+ *     package.json   (os/cpu restricted, no `bin` — the launcher execs it)
+ *     bin/claudeup   (the compiled binary)
+ *
+ * The main `claudeup` package lists these as optionalDependencies; npm installs
+ * only the one matching the host os/cpu, and bin/claudeup.js execs it.
+ *
+ * Hard constraint: claudeup pins @opentui 0.1.x — 0.4.x breaks --compile.
+ */
+
+import { $ } from "bun";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import path from "node:path";
+import pkg from "../package.json";
+
+interface Target {
+	os: "darwin" | "linux";
+	cpu: "arm64" | "x64";
+	bunTarget: string;
+}
+
+const TARGETS: Target[] = [
+	{ os: "darwin", cpu: "arm64", bunTarget: "bun-darwin-arm64" },
+	{ os: "darwin", cpu: "x64", bunTarget: "bun-darwin-x64" },
+	{ os: "linux", cpu: "x64", bunTarget: "bun-linux-x64" },
+];
+
+const version = (pkg as { version: string }).version;
+const root = path.join(import.meta.dir, "..");
+const distRoot = path.join(root, "dist-binaries");
+const entry = path.join(root, "src", "main.tsx");
+
+// Optional filter: `bun scripts/build-binaries.ts darwin-arm64`
+const only = process.argv[2];
+
+await rm(distRoot, { recursive: true, force: true });
+
+for (const t of TARGETS) {
+	const id = `${t.os}-${t.cpu}`;
+	if (only && only !== id) continue;
+
+	const pkgName = `claudeup-${id}`;
+	const outDir = path.join(distRoot, pkgName);
+	const binPath = path.join(outDir, "bin", "claudeup");
+	await mkdir(path.join(outDir, "bin"), { recursive: true });
+
+	console.log(`Building ${pkgName} (${t.bunTarget})…`);
+	await $`bun build --compile --target=${t.bunTarget} ${entry} --outfile ${binPath}`;
+
+	// Platform package: os/cpu-restricted, ships only the binary, declares NO
+	// `bin` (the main package's launcher resolves and execs bin/claudeup).
+	const platformPkg = {
+		name: pkgName,
+		version,
+		description: `Prebuilt claudeup binary for ${id}`,
+		os: [t.os],
+		cpu: [t.cpu],
+		files: ["bin/"],
+		license: (pkg as { license: string }).license,
+		repository: (pkg as { repository: unknown }).repository,
+	};
+	await writeFile(
+		path.join(outDir, "package.json"),
+		`${JSON.stringify(platformPkg, null, 2)}\n`,
+	);
+}
+
+console.log(`\nDone. Packages in ${path.relative(process.cwd(), distRoot)}/`);
+console.log("Publish each with `npm publish` (then the main package).");

package/scripts/check-optional-deps.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+/**
+ * check-optional-deps.ts — assert the per-platform optionalDependencies are pinned
+ * to the main package's own version.
+ *
+ * build-binaries.ts stamps each generated per-platform package with
+ * `package.json`'s version, and the release workflow publishes those first so the
+ * main package's optionalDependencies already resolve. If the two drift, the main
+ * package ships pointing at versions that were never published.
+ *
+ * That failure is quiet: optionalDependencies are allowed to fail to resolve, so
+ * npm/bun install succeeds and the launcher silently falls back to running from
+ * source via Bun — meaning every user loses the prebuilt binary and anyone without
+ * Bun on PATH gets a broken `claudeup`. Nothing errors, so it can ship unnoticed.
+ *
+ * Bumping the package version without bumping these is easy to do by hand, which
+ * is exactly what happened going 4.20.0 -> 4.21.0.
+ */
+
+import pkg from "../package.json";
+
+const version = (pkg as { version: string }).version;
+const optional = (pkg as { optionalDependencies?: Record<string, string> })
+  .optionalDependencies;
+
+if (!optional || Object.keys(optional).length === 0) {
+  console.log("check:optional-deps — no optionalDependencies declared, nothing to verify");
+  process.exit(0);
+}
+
+const mismatched = Object.entries(optional).filter(([, v]) => v !== version);
+
+if (mismatched.length > 0) {
+  console.error(
+    `check:optional-deps FAILED — package version is ${version}, but:`,
+  );
+  for (const [name, v] of mismatched) {
+    console.error(`  ${name}: ${v}  (expected ${version})`);
+  }
+  console.error(
+    "\nThese are published from this same version by build-binaries.ts.\n" +
+      "Update optionalDependencies in package.json to match, then re-run.",
+  );
+  process.exit(1);
+}
+
+console.log(
+  `check:optional-deps — all ${Object.keys(optional).length} platform packages pinned to ${version}`,
+);

package/scripts/test-isolated.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+/**
+ * Run each test file in its own `bun test` process.
+ *
+ * Some tests use bun's `mock.module`, which is process-global and NOT restored
+ * across files (bun 1.3.10). In a single shared process the outcome depends on
+ * file order — fine locally, flaky on CI (different order / workers). Per-file
+ * isolation removes the cross-file coupling entirely: every file gets a fresh
+ * module registry. Slower than `bun test`, but deterministic — which is what CI
+ * needs. For fast local iteration use `bun test`.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+function findTests(dir: string): string[] {
+	const out: string[] = [];
+	for (const entry of readdirSync(dir)) {
+		const p = join(dir, entry);
+		if (statSync(p).isDirectory()) out.push(...findTests(p));
+		else if (p.endsWith(".test.ts")) out.push(p);
+	}
+	return out;
+}
+
+const root = join(import.meta.dir, "..");
+const files = findTests(join(root, "src")).sort();
+
+let failed = 0;
+for (const file of files) {
+	const rel = file.slice(root.length + 1);
+	process.stdout.write(`\n── ${rel}\n`);
+	const result = spawnSync("bun", ["test", file], {
+		stdio: "inherit",
+		cwd: root,
+	});
+	if (result.status !== 0) failed++;
+}
+
+const passed = files.length - failed;
+console.log(`\n${passed}/${files.length} test files passed (isolated).`);
+process.exit(failed > 0 ? 1 : 0);

package/src/__tests__/alias-adopt.test.ts

@@ -0,0 +1,364 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, rm, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  tokenizeGeneralAliasBody,
+  findAdoptableAlias,
+  spliceManagedBlockAtRange,
+  renderAlias,
+  writeAliasToShell,
+  argsToFlagValuesWithLeftovers,
+  type AdoptableAlias,
+  type ShellTarget,
+} from "../services/alias-shell-writer";
+import { defaultAliasConfig } from "../services/alias-store";
+
+// ─── tokenizeGeneralAliasBody ──────────────────────────────────────────────
+
+describe("tokenizeGeneralAliasBody", () => {
+  it("splits bare words on whitespace", () => {
+    expect(tokenizeGeneralAliasBody("claude --ide --effort high")).toEqual([
+      "claude",
+      "--ide",
+      "--effort",
+      "high",
+    ]);
+  });
+
+  it("treats single-quoted runs as literal (spaces preserved)", () => {
+    expect(
+      tokenizeGeneralAliasBody("claude --append-system-prompt 'be terse'"),
+    ).toEqual(["claude", "--append-system-prompt", "be terse"]);
+  });
+
+  it("treats double-quoted runs as literal", () => {
+    expect(
+      tokenizeGeneralAliasBody('claude --append-system-prompt "be terse"'),
+    ).toEqual(["claude", "--append-system-prompt", "be terse"]);
+  });
+
+  it("joins adjacent quoted + bare pieces into one token", () => {
+    // `foo' bar'baz` → one shell word `foo barbaz`
+    expect(tokenizeGeneralAliasBody("claude foo' bar'baz")).toEqual([
+      "claude",
+      "foo barbaz",
+    ]);
+  });
+
+  it("bails (null) on unterminated quotes", () => {
+    expect(tokenizeGeneralAliasBody("claude 'unterminated")).toBeNull();
+    expect(tokenizeGeneralAliasBody('claude "unterminated')).toBeNull();
+  });
+
+  it("bails (null) on shell substitutions and variables", () => {
+    expect(tokenizeGeneralAliasBody("claude --foo $(date)")).toBeNull();
+    expect(tokenizeGeneralAliasBody("claude --foo `date`")).toBeNull();
+    expect(tokenizeGeneralAliasBody("claude --foo $HOME")).toBeNull();
+    // Even inside double quotes — we don't expand, so we can't round-trip it.
+    expect(tokenizeGeneralAliasBody('claude --foo "$HOME/x"')).toBeNull();
+  });
+});
+
+// ─── argsToFlagValuesWithLeftovers ─────────────────────────────────────────
+
+describe("argsToFlagValuesWithLeftovers", () => {
+  it("reports no leftovers when every token is recognized", () => {
+    const { leftovers } = argsToFlagValuesWithLeftovers([
+      "--dangerously-skip-permissions",
+      "--effort",
+      "high",
+    ]);
+    expect(leftovers).toEqual([]);
+  });
+
+  it("records an unknown bare flag as a leftover", () => {
+    const { leftovers } = argsToFlagValuesWithLeftovers(["--ide", "--unknown"]);
+    expect(leftovers).toEqual(["--unknown"]);
+  });
+
+  it("records an unknown flag AND its consumed value", () => {
+    const { leftovers } = argsToFlagValuesWithLeftovers([
+      "--model",
+      "opus",
+      "--ide",
+    ]);
+    expect(leftovers).toEqual(["--model", "opus"]);
+  });
+
+  it("recognizes order-independently (no false leftovers on reorder)", () => {
+    // catalog order is ide(154) before effort(173); user wrote them reversed
+    const { flags, leftovers } = argsToFlagValuesWithLeftovers([
+      "--effort",
+      "high",
+      "--ide",
+    ]);
+    expect(leftovers).toEqual([]);
+    expect(flags["ide"]).toEqual({ kind: "boolean", enabled: true });
+    expect(flags["effort"]).toEqual({
+      kind: "select",
+      enabled: true,
+      value: "high",
+    });
+  });
+});
+
+// ─── findAdoptableAlias ────────────────────────────────────────────────────
+
+describe("findAdoptableAlias", () => {
+  it("returns null when there's no claude-wrapping alias", () => {
+    const rc = "export PATH=$PATH:/usr/local/bin\nalias ll='ls -la'\n";
+    expect(findAdoptableAlias(rc)).toBeNull();
+  });
+
+  it("detects a single-quoted hand-written claude alias and parses its flags", () => {
+    const rc =
+      "# rc\nalias c='claude --dangerously-skip-permissions'\nexport X=1\n";
+    const a = findAdoptableAlias(rc);
+    expect(a).not.toBeNull();
+    expect(a!.name).toBe("c");
+    expect(a!.flags["dangerously-skip-permissions"]).toEqual({
+      kind: "boolean",
+      enabled: true,
+    });
+    expect(a!.lineRange).toEqual([1, 1]);
+    expect(a!.leftovers).toEqual([]);
+    expect(a!.lossless).toBe(true);
+  });
+
+  it("detects a double-quoted hand-written claude alias", () => {
+    const rc = 'alias cc="claude --ide"\n';
+    const a = findAdoptableAlias(rc);
+    expect(a).not.toBeNull();
+    expect(a!.name).toBe("cc");
+    expect(a!.flags["ide"]).toEqual({ kind: "boolean", enabled: true });
+    expect(a!.lossless).toBe(true);
+  });
+
+  it("marks an alias with an uncatalogued flag as NOT lossless and lists the leftover", () => {
+    const rc = "alias c='claude --ide --model opus'\n";
+    const a = findAdoptableAlias(rc);
+    expect(a).not.toBeNull();
+    // The flags we DID recognize are imported for the user to see.
+    expect(a!.flags["ide"]).toEqual({ kind: "boolean", enabled: true });
+    // But the alias is not safe to absorb — its original line must be kept.
+    expect(a!.lossless).toBe(false);
+    expect(a!.leftovers).toEqual(["--model", "opus"]);
+  });
+
+  it("is lossless regardless of flag ordering or quote style (round-trip-safe)", () => {
+    const rc = "alias c='claude --effort high --ide'\n";
+    const a = findAdoptableAlias(rc);
+    expect(a!.lossless).toBe(true);
+    expect(a!.leftovers).toEqual([]);
+  });
+
+  it("skips indented (non-top-level) alias lines", () => {
+    const rc = "my_func() {\n  alias c='claude --ide'\n}\n";
+    expect(findAdoptableAlias(rc)).toBeNull();
+  });
+
+  it("ignores an alias inside the managed block", () => {
+    const rc =
+      "# >>> claudeup managed alias >>>\nalias c='claude --ide'\n# <<< claudeup managed alias <<<\n";
+    expect(findAdoptableAlias(rc)).toBeNull();
+  });
+
+  it("picks the first top-level claude alias and notes the others", () => {
+    const rc =
+      "alias c='claude --ide'\nalias cc='claude --worktree'\n";
+    const a = findAdoptableAlias(rc);
+    expect(a!.name).toBe("c");
+    expect(a!.others).toEqual(["alias cc='claude --worktree'"]);
+  });
+
+  it("bails on a claude alias whose body contains a substitution", () => {
+    // Can't round-trip a $(...) — not adoptable at all.
+    const rc = "alias c='claude --append-system-prompt $(cat ~/p.txt)'\n";
+    expect(findAdoptableAlias(rc)).toBeNull();
+  });
+});
+
+// ─── spliceManagedBlockAtRange ─────────────────────────────────────────────
+
+describe("spliceManagedBlockAtRange", () => {
+  const block =
+    "# >>> claudeup managed alias >>>\nalias c='claude --ide'\n# <<< claudeup managed alias <<<\n";
+
+  it("replaces the adopted line in place (no duplicate alias)", () => {
+    const rc = "# header\nalias c='claude --dangerously-skip-permissions'\nexport X=1\n";
+    const result = spliceManagedBlockAtRange(rc, block, [1, 1]);
+    // The old hand-written line is gone; the block sits where it was.
+    expect(result).not.toContain(
+      "alias c='claude --dangerously-skip-permissions'",
+    );
+    expect(result).toContain("# >>> claudeup managed alias >>>");
+    expect(result).toContain("# header");
+    expect(result).toContain("export X=1");
+    // Exactly one `alias c=` line.
+    const count = (result.match(/^alias c=/gm) ?? []).length;
+    expect(count).toBe(1);
+  });
+
+  it("falls back to append when the range is out of bounds", () => {
+    const rc = "alias g='git'\n";
+    const result = spliceManagedBlockAtRange(rc, block, [99, 99]);
+    expect(result).toContain("alias g='git'");
+    expect(result).toContain("# >>> claudeup managed alias >>>");
+  });
+});
+
+// ─── End-to-end: adopt → write yields a single, clean managed block ─────────
+
+describe("adoption end-to-end", () => {
+  it("lossless adoption: parse → render → splice-at-range = one alias, original gone", () => {
+    const rc =
+      "# my zshrc\nexport EDITOR=vim\nalias c='claude --dangerously-skip-permissions'\n# eof\n";
+    const a = findAdoptableAlias(rc) as AdoptableAlias;
+    expect(a.lossless).toBe(true);
+
+    // Build a config from the adopted name + flags and render the block.
+    const config = defaultAliasConfig();
+    config.aliasName = a.name;
+    config.flags = { ...config.flags, ...a.flags };
+    const rendered = renderAlias(config, "zsh");
+
+    const next = spliceManagedBlockAtRange(rc, rendered.block, a.lineRange);
+
+    // Original hand-written line removed.
+    expect(next).not.toContain(
+      "alias c='claude --dangerously-skip-permissions'\n# eof",
+    );
+    // Managed block present with the same flag.
+    expect(next).toContain("# >>> claudeup managed alias >>>");
+    expect(next).toContain("--dangerously-skip-permissions");
+    // Exactly one `alias c=` and surrounding content intact.
+    expect((next.match(/^alias c=/gm) ?? []).length).toBe(1);
+    expect(next).toContain("export EDITOR=vim");
+    expect(next).toContain("# eof");
+  });
+});
+
+// ─── writeAliasToShell honors adoptLineRange (file I/O) ─────────────────────
+
+describe("writeAliasToShell — adoption path", () => {
+  let home: string;
+
+  beforeEach(async () => {
+    home = await mkdtemp(join(tmpdir(), "alias-adopt-write-"));
+  });
+
+  afterEach(async () => {
+    await rm(home, { recursive: true, force: true });
+  });
+
+  it("replaces the adopted line in place — never leaves a duplicate alias", async () => {
+    const path = join(home, ".zshrc");
+    // A real-world rc: hand-written `alias c=` plus surrounding content.
+    await writeFile(
+      path,
+      "export EDITOR=vim\nalias c='claude --dangerously-skip-permissions'\nalias g='git'\n",
+      "utf8",
+    );
+    const rc = await readFile(path, "utf8");
+    const a = findAdoptableAlias(rc) as AdoptableAlias;
+    expect(a.lossless).toBe(true);
+
+    const config = defaultAliasConfig();
+    config.aliasName = a.name;
+    config.flags = { ...config.flags, ...a.flags };
+
+    const target: ShellTarget = {
+      kind: "zsh",
+      path,
+      exists: true,
+      isDefault: true,
+    };
+    await writeAliasToShell(config, target, { adoptLineRange: a.lineRange });
+
+    const written = await readFile(path, "utf8");
+    // Original hand-written line removed.
+    expect(written).not.toContain(
+      "alias c='claude --dangerously-skip-permissions'\nalias g=",
+    );
+    // Managed block now owns the alias.
+    expect(written).toContain("# >>> claudeup managed alias >>>");
+    expect(written).toContain("--dangerously-skip-permissions");
+    // Exactly ONE `alias c=` definition (the whole point).
+    expect((written.match(/^alias c=/gm) ?? []).length).toBe(1);
+    // Surrounding lines preserved.
+    expect(written).toContain("export EDITOR=vim");
+    expect(written).toContain("alias g='git'");
+  });
+
+  it("not-lossless: managed block under a DISTINCT name never shadows the surviving original", async () => {
+    // The not-lossless UI path keeps the original line and writes the managed
+    // block under a name distinct from the original (no adoptLineRange). This
+    // test pins the no-shadow outcome at the service layer: two differently-
+    // named aliases coexist, and the original keeps ALL its tokens.
+    const path = join(home, ".zshrc");
+    await writeFile(
+      path,
+      "export EDITOR=vim\nalias c='claude --dangerously-skip-permissions --model opus'\nalias g='git'\n",
+      "utf8",
+    );
+    const a = findAdoptableAlias(await readFile(path, "utf8")) as AdoptableAlias;
+    expect(a.lossless).toBe(false);
+    expect(a.leftovers).toEqual(["--model", "opus"]);
+
+    // Managed block uses a DIFFERENT name (mirrors pickDistinctName → "cm").
+    const config = defaultAliasConfig();
+    config.aliasName = "cm";
+    config.flags = { ...config.flags, ...a.flags };
+    const target: ShellTarget = {
+      kind: "zsh",
+      path,
+      exists: true,
+      isDefault: true,
+    };
+    // No adoptLineRange — the original line must be left untouched.
+    await writeAliasToShell(config, target, {});
+
+    const written = await readFile(path, "utf8");
+    // The original `alias c=` survives, complete with --model opus.
+    expect(written).toContain(
+      "alias c='claude --dangerously-skip-permissions --model opus'",
+    );
+    // The managed block uses the distinct name.
+    expect(written).toContain("alias cm='claude --dangerously-skip-permissions'");
+    // Exactly one of each name — no duplicate, no same-name shadow.
+    expect((written.match(/^alias c=/gm) ?? []).length).toBe(1);
+    expect((written.match(/^alias cm=/gm) ?? []).length).toBe(1);
+  });
+
+  it("a SECOND write (range still passed) doesn't double the block — markers win", async () => {
+    const path = join(home, ".zshrc");
+    await writeFile(
+      path,
+      "alias c='claude --ide'\n",
+      "utf8",
+    );
+    const a = findAdoptableAlias(await readFile(path, "utf8")) as AdoptableAlias;
+    const config = defaultAliasConfig();
+    config.aliasName = a.name;
+    config.flags = { ...config.flags, ...a.flags };
+    const target: ShellTarget = {
+      kind: "zsh",
+      path,
+      exists: true,
+      isDefault: true,
+    };
+    // First write absorbs the line.
+    await writeAliasToShell(config, target, { adoptLineRange: a.lineRange });
+    // Second write with the SAME stale range — a managed block now exists, so
+    // the writer must ignore the range and splice by markers (idempotent).
+    await writeAliasToShell(config, target, { adoptLineRange: a.lineRange });
+
+    const written = await readFile(path, "utf8");
+    const beginCount = (
+      written.match(/# >>> claudeup managed alias >>>/g) ?? []
+    ).length;
+    expect(beginCount).toBe(1);
+    expect((written.match(/^alias c=/gm) ?? []).length).toBe(1);
+  });
+});