@sailresearch/code 0.1.0

package/src/setup.js

@@ -0,0 +1,482 @@
+/**
+ * `sail-code setup` — persist the Sail env block into Claude Code's
+ * settings.json so a bare `claude` (launched from anywhere) routes to Sail.
+ * VS Code extension sessions read this env block too, but the extension's
+ * own pre-launch login check does not — account-less users additionally
+ * need `claudeCode.environmentVariables` in VS Code's settings (the setup
+ * output prints the snippet).
+ *
+ * The write is reversible: the original file is backed up to
+ * `settings.json.sail-backup` before the first change, and `--revert`
+ * restores it (or, without a backup, removes exactly the keys we own).
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  CONFLICTING_PROVIDER_VARS,
+  HEADER_INJECTION_VARS,
+  MODEL_ALIAS_COMPANION_VARS,
+  OWNED_ENV_KEYS,
+  buildClaudeEnv,
+} from "./constants.js";
+import { atomicWrite } from "./credentials.js";
+import { resolveCredentials } from "./run.js";
+
+export const BACKUP_SUFFIX = ".sail-backup";
+
+/**
+ * Backup sentinel recorded when the settings file did NOT exist before the
+ * first `setup`. A re-run then finds a backup already present (so it won't
+ * capture the Sail-injected file as if it were the user's original), and
+ * `--revert` sees the sentinel and DELETES the file we created rather than
+ * "restoring" a token-bearing file. Deliberately not valid JSON so it can
+ * never be mistaken for a real settings backup.
+ */
+export const ABSENT_SENTINEL = "SAIL_ORIGINAL_ABSENT\n";
+
+/**
+ * Merge the Sail env block into a settings object and neutralize any inherited
+ * keys that would outrank or mutate our routing once Claude Code reads the
+ * settings-file `env` at startup: provider selectors (`CLAUDE_CODE_USE_*`,
+ * which precede `ANTHROPIC_AUTH_TOKEN` in the auth precedence), header
+ * injectors (`ANTHROPIC_CUSTOM_HEADERS`), and alias companion vars
+ * (`ANTHROPIC_DEFAULT_<ALIAS>_MODEL_{NAME,DESCRIPTION,SUPPORTED_CAPABILITIES}`,
+ * which would mis-describe the GLM model the alias pins point at). Mirrors the
+ * child-env scrub on the `run` path so bare `claude`/VS Code can't silently
+ * bypass Sail or mis-advertise GLM's capabilities after `setup`.
+ *
+ * Deleting a key only clears it when the file we write is the one that holds
+ * it — but a conflict can also come from a place our write can't reach by
+ * omission, so for those we set a falsy override (like the temp `--settings`
+ * layer) instead of deleting:
+ *   - a sibling `settings.json` that the higher-precedence project
+ *     `settings.local.json` MERGES over (project scope; we can't see it from
+ *     here, so we override unconditionally); and
+ *   - the current shell/profile: a settings-file `env` value overrides the
+ *     inherited process env, so a shell-exported `CLAUDE_CODE_USE_*` /
+ *     `ANTHROPIC_CUSTOM_HEADERS` survives a delete-from-file (there's nothing
+ *     in the file to delete) and would still outrank Sail. We override the
+ *     keys actually present in `shellEnv` — for either scope — so a clean
+ *     settings file isn't littered with empty markers.
+ * Companion vars stay deleted even then: empty string isn't a documented
+ * "unset" for `_SUPPORTED_CAPABILITIES` (it could read as "no capabilities"),
+ * so a companion var in a repo-shared `settings.json` is a residual gap.
+ *
+ * Mutates `settings.env`; returns the keys that were actually removed (so the
+ * caller can surface them). `--revert` restores them from the byte backup, or
+ * clears the falsy overrides we wrote. Exported so tests exercise the real
+ * merge, not a copy.
+ */
+export function mergeSailEnv(
+  settings,
+  env,
+  { scope = "user", shellEnv = process.env } = {},
+) {
+  const merged = { ...(settings.env ?? {}), ...env };
+  const removed = [];
+  // Companion vars: delete inherited ones (empty string is unsafe for these),
+  // but keep the values OUR env block sets — buildClaudeEnv declares
+  // `_SUPPORTED_CAPABILITIES` for aliases pinned to the default GLM model so
+  // effort/thinking aren't dropped for the custom model ID.
+  for (const key of MODEL_ALIAS_COMPANION_VARS) {
+    if (key in env) continue; // ours — already overlaid by the spread above
+    if (key in merged) removed.push(key);
+    delete merged[key];
+  }
+  for (const key of [...CONFLICTING_PROVIDER_VARS, ...HEADER_INJECTION_VARS]) {
+    if (scope === "project" || key in shellEnv) {
+      // Falsy override beats a conflict we can't clear by omission: a sibling
+      // settings.json this local file merges over (project scope), or a shell-
+      // exported var (either scope) that a settings-file env value outranks.
+      // revert clears these empty markers.
+      merged[key] = "";
+    } else if (key in merged) {
+      // Our env block never sets these keys, so presence == inherited in the
+      // file; user scope is lowest-precedence, so deleting fully clears it.
+      removed.push(key);
+      delete merged[key];
+    }
+  }
+  settings.env = merged;
+  return removed;
+}
+
+export function settingsPath(scope) {
+  if (scope === "project") {
+    // The project scope writes the *local* settings file, not the shared
+    // `settings.json`: it carries the API key, and `.claude/settings.local
+    // .json` is Claude Code's documented personal/not-committed file (higher
+    // precedence than `settings.json`, still below our temp `--settings`). We
+    // gitignore it on write since Claude Code only auto-ignores files it
+    // creates itself.
+    return path.join(process.cwd(), ".claude", "settings.local.json");
+  }
+  // Honor CLAUDE_CONFIG_DIR: when it's set, Claude Code reads user config from
+  // that directory instead of ~/.claude (credentials live at
+  // `$CLAUDE_CONFIG_DIR/.credentials.json`, settings at
+  // `$CLAUDE_CONFIG_DIR/settings.json`). Writing ~/.claude/settings.json there
+  // would report success while the launched session reads the relocated file
+  // and ignores the Sail env. Only the user scope relocates; project settings
+  // stay in the repo's `.claude/`.
+  const configDir = process.env.CLAUDE_CONFIG_DIR?.trim();
+  if (configDir) {
+    return path.join(configDir, "settings.json");
+  }
+  return path.join(os.homedir(), ".claude", "settings.json");
+}
+
+/**
+ * Ensure `.claude/settings.local.json` (and its `.sail-backup`) are gitignored,
+ * so a project-scoped setup can't leak the API key into a commit. Claude Code
+ * auto-ignores this file only when *it* creates it; we create it, so we write a
+ * scoped `.claude/.gitignore`. Best-effort: a failure here never blocks setup.
+ * Exported for tests.
+ */
+export function ensureLocalSettingsIgnored(filePath) {
+  try {
+    const claudeDir = path.dirname(filePath);
+    fs.mkdirSync(claudeDir, { recursive: true });
+    const ignoreFile = path.join(claudeDir, ".gitignore");
+    const wanted = ["settings.local.json", "settings.local.json.sail-backup"];
+    let lines = [];
+    if (fs.existsSync(ignoreFile)) {
+      lines = fs.readFileSync(ignoreFile, "utf8").split(/\r?\n/);
+    }
+    const have = new Set(lines.map((l) => l.trim()));
+    const missing = wanted.filter((w) => !have.has(w));
+    if (missing.length === 0) return;
+    const prefix = lines.length && lines[lines.length - 1] !== "" ? "\n" : "";
+    fs.appendFileSync(ignoreFile, prefix + missing.join("\n") + "\n");
+  } catch {
+    // A missing/unwritable .claude dir surfaces on the settings write instead;
+    // never fail setup just because we couldn't touch .gitignore.
+  }
+}
+
+/** The nearest ancestor of `dir` that exists on disk (walks up to the root). */
+function firstExistingDir(dir) {
+  let cur = path.resolve(dir);
+  while (!fs.existsSync(cur)) {
+    const parent = path.dirname(cur);
+    if (parent === cur) break; // reached the filesystem root
+    cur = parent;
+  }
+  return cur;
+}
+
+/**
+ * Whether `filePath` is tracked in git. `git ls-files` reads the INDEX, so a
+ * file tracked but absent from the working tree (deleted locally, sparse
+ * checkout) still counts — but we must run git from a directory that EXISTS,
+ * or spawn fails with ENOENT and we'd wrongly read "not tracked". Run from the
+ * nearest existing ancestor of the file. Only `true` when git confirms it — a
+ * non-repo, a missing git binary, or an untracked file all read as `false`
+ * (we refuse only when we're certain, never on a can't-tell). Exported for
+ * tests.
+ */
+export function isGitTracked(filePath) {
+  // Resolve to an absolute path: a relative filePath (e.g. a relative
+  // CLAUDE_CONFIG_DIR like `.claude`) would be interpreted relative to git's
+  // cwd (the file's own dir), so the pathspec would miss the real file and
+  // wrongly read "not tracked". An absolute pathspec resolves correctly.
+  const abs = path.resolve(filePath);
+  try {
+    execFileSync("git", ["ls-files", "--error-unmatch", "--", abs], {
+      cwd: firstExistingDir(path.dirname(abs)),
+      stdio: "ignore",
+      timeout: 5000,
+    });
+    return true; // exit 0 → tracked
+  } catch {
+    return false; // non-zero: untracked, not a repo, or git unavailable
+  }
+}
+
+/**
+ * Whether git considers `filePath` ignored. `git check-ignore` evaluates the
+ * effective ignore rules (including parent `.gitignore`s and negations), not
+ * just our scoped file, and works on a path that doesn't exist yet.
+ * Returns "ignored" (exit 0), "not-ignored" (exit 1 — a real repo where it
+ * isn't ignored), or "unknown" (exit 128 / no repo / git missing — can't tell,
+ * so no `git add` risk we can confirm). Exported for tests.
+ */
+export function gitIgnoreState(filePath) {
+  // Absolute pathspec (see isGitTracked) so a relative filePath can't be
+  // misresolved against git's cwd.
+  const abs = path.resolve(filePath);
+  try {
+    execFileSync("git", ["check-ignore", "-q", "--", abs], {
+      cwd: firstExistingDir(path.dirname(abs)),
+      stdio: "ignore",
+      timeout: 5000,
+    });
+    return "ignored"; // exit 0
+  } catch (err) {
+    return err && err.status === 1 ? "not-ignored" : "unknown";
+  }
+}
+
+/** Read settings.json as an object; missing file → {}; malformed → error. */
+function readSettings(filePath) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return { settings: {}, existed: false };
+    throw new Error(`could not read ${filePath}: ${err.message}`);
+  }
+  try {
+    // Strip a UTF-8 BOM (some Windows editors add one; JSON.parse rejects it).
+    const settings = JSON.parse(text.replace(/^\uFEFF/, ""));
+    if (
+      settings === null ||
+      typeof settings !== "object" ||
+      Array.isArray(settings)
+    ) {
+      throw new Error("top level is not an object");
+    }
+    return { settings, existed: true, originalText: text };
+  } catch (err) {
+    throw new Error(
+      `${filePath} is not valid JSON (${err.message}) — fix it before running setup`,
+    );
+  }
+}
+
+function writeSettings(filePath, settings, { containsSecret = false } = {}) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  // Preserve an existing file's permissions in general, but once the content
+  // includes the API key, mask group/other bits (0644 → 0600) so the token
+  // isn't readable by other local users. Fresh files get 0600. A --revert
+  // restores the original file (and its original mode) from the backup.
+  atomicWrite(filePath, JSON.stringify(settings, null, 2) + "\n", {
+    preserveMode: true,
+    tighten: containsSecret,
+  });
+}
+
+/**
+ * Refuse to write a secret into a git-tracked settings file (or its backup):
+ * `.gitignore` can't untrack an already-tracked file, so the token would show
+ * in `git diff`/`status` and could be committed. Applies to BOTH scopes — user
+ * settings can live in a tracked `~/.claude` dotfiles checkout or a
+ * `CLAUDE_CONFIG_DIR` inside a repo, not just project settings. Throws before
+ * any key is minted or written (resolveCredentials can trigger a browser login).
+ */
+function assertSettingsNotGitTracked(filePath) {
+  for (const p of [filePath, filePath + BACKUP_SUFFIX]) {
+    if (isGitTracked(p)) {
+      throw new Error(
+        `${p} is tracked in git — setup won't write a secret into a tracked ` +
+          "file (a .gitignore entry won't untrack it). Untrack it with `git rm " +
+          "--cached`, or set SAIL_API_KEY in your environment instead (nothing " +
+          "is persisted then).",
+      );
+    }
+  }
+}
+
+/** Apply the Sail env block to settings.json (backing up the original). */
+export async function setup({
+  scope = "user",
+  modeFlag,
+  model,
+  backgroundModel,
+}) {
+  const filePath = settingsPath(scope);
+  const backupPath = filePath + BACKUP_SUFFIX;
+  // Never write a secret into a git-tracked file — for EITHER scope. Project
+  // settings live in the repo, but user settings can too (a tracked ~/.claude
+  // dotfiles checkout, or CLAUDE_CONFIG_DIR pointing inside a repo). Refuse
+  // before a key is minted/written rather than leak it.
+  assertSettingsNotGitTracked(filePath);
+
+  if (scope === "project") {
+    // Ensure both the file and its backup are git-ignored BEFORE we resolve/
+    // mint a key or write the token. A read-only or locked `.claude/.gitignore`
+    // makes the append fail silently, which would leave the secret stageable by
+    // `git add .` despite the "added ignore rules" message. Append, then verify
+    // with `git check-ignore`; refuse if a real repo confirms either still
+    // isn't ignored (no key minted, no token written yet).
+    ensureLocalSettingsIgnored(filePath);
+    for (const p of [filePath, backupPath]) {
+      if (gitIgnoreState(p) === "not-ignored") {
+        throw new Error(
+          `couldn't ensure ${p} is git-ignored (is .claude/.gitignore ` +
+            "writable?) — refusing to write a secret where `git add` could " +
+            "stage it. Fix that, or use `--user` instead.",
+        );
+      }
+    }
+    console.error(
+      `Note: this writes your Sail API key into ${filePath} (Claude Code's ` +
+        "personal, not-shared project settings), now git-ignored via " +
+        "`.claude/.gitignore`. Double-check it stays out of commits, or use " +
+        "`--user` instead.",
+    );
+  } else if (
+    gitIgnoreState(filePath) === "not-ignored" ||
+    gitIgnoreState(backupPath) === "not-ignored"
+  ) {
+    // User settings resolved INSIDE a git repo (dotfiles / CLAUDE_CONFIG_DIR)
+    // and aren't ignored: not tracked yet, but a `git add .` there could stage
+    // the token. Fail closed like the tracked-file and project-scope guards —
+    // a warning scrolls past and the key still lands where git can stage it.
+    // We don't edit the user's own dotfiles-repo .gitignore for them; the
+    // error says how to fix it. Throws before any key is minted/written.
+    throw new Error(
+      `${filePath} is inside a git repo and isn't git-ignored — a ` +
+        "`git add .` there could stage your Sail API key. Add it (and its " +
+        ".sail-backup) to that repo's .gitignore, or set SAIL_API_KEY in " +
+        "your environment instead (nothing is persisted then).",
+    );
+  }
+
+  const { apiKey, apiUrl } = await resolveCredentials({ modeFlag });
+  const env = buildClaudeEnv({ apiUrl, apiKey, model, backgroundModel });
+
+  const { settings, existed } = readSettings(filePath);
+  // Create the settings dir before writing the backup/sentinel. On a fresh
+  // machine (no ~/.claude, or a brand-new CLAUDE_CONFIG_DIR) the sentinel write
+  // below would otherwise ENOENT — after the key was already minted — since
+  // writeSettings only creates the parent later. mkdir is a no-op when it
+  // exists (and project scope already made it via ensureLocalSettingsIgnored).
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  // The FIRST setup records the true pre-Sail state so --revert restores it;
+  // a re-run must never overwrite that record with an already-Sail-injected
+  // file. When the file existed, back up its bytes (carrying its mode). When
+  // it did NOT, write the absent-sentinel so a re-run (file now present)
+  // doesn't capture the Sail file as the "original", and --revert deletes
+  // what we created instead of leaving the API key behind. Both writes are
+  // create-exclusive (COPYFILE_EXCL / "wx"): a plain existsSync check would
+  // race two concurrent setups, letting the second clobber the first's backup
+  // — which by then may already hold the Sail-injected file — and lose the
+  // real original. An atomic create fails with EEXIST instead; that just means
+  // a prior/concurrent setup already recorded the state, so it's expected.
+  try {
+    if (existed) {
+      fs.copyFileSync(filePath, backupPath, fs.constants.COPYFILE_EXCL);
+    } else {
+      fs.writeFileSync(backupPath, ABSENT_SENTINEL, {
+        mode: 0o600,
+        flag: "wx",
+      });
+    }
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+
+  const removedKeys = mergeSailEnv(settings, env, { scope });
+  writeSettings(filePath, settings, { containsSecret: true });
+
+  if (removedKeys.length > 0) {
+    console.error(
+      `Removed conflicting env ${removedKeys.join(", ")} from ${filePath} so ` +
+        "it can't outrank or mutate Sail routing (--revert restores them).",
+    );
+  }
+  if (scope === "project") {
+    console.error(
+      "Set empty overrides for provider/header env in the local file so they " +
+        "beat any conflicting value in a repo-shared `.claude/settings.json` " +
+        "(--revert clears them).",
+    );
+  }
+  const shellConflicts = [
+    ...CONFLICTING_PROVIDER_VARS,
+    ...HEADER_INJECTION_VARS,
+  ].filter((key) => key in process.env);
+  if (shellConflicts.length > 0) {
+    console.error(
+      `Your shell exports ${shellConflicts.join(", ")} — wrote empty overrides ` +
+        `in ${filePath} so bare \`claude\` still routes to Sail (a settings-file ` +
+        "env value outranks the shell). --revert clears them; you can also unset " +
+        "them in your shell profile.",
+    );
+  }
+
+  const revertCmd =
+    "sail-code setup --revert" + (scope === "project" ? " --project" : "");
+  // User settings are the LOWEST-precedence settings source, so a repo that
+  // already carries `.claude/settings.json` (or settings.local.json) with its
+  // own ANTHROPIC_BASE_URL / provider selector overrides this write inside
+  // that repo. Don't claim it applies everywhere — point those repos at
+  // `--project`. Project scope writes the near-top local file, so it does win.
+  const reach =
+    scope === "project"
+      ? "This applies to `claude` launched from THIS directory — Claude Code " +
+        "reads project settings from the launch directory (verified " +
+        "empirically; not the git root), so run setup where you run `claude`. " +
+        "Project settings outrank user settings."
+      : "This applies to `claude` launched from anywhere, EXCEPT a repo whose " +
+        "own `.claude/settings.json` sets a conflicting ANTHROPIC_BASE_URL / " +
+        "provider var — those outrank user settings; run `setup --project` " +
+        "there.";
+  console.error(
+    `Wrote Sail routing to ${filePath}` +
+      (existed ? ` (original backed up to ${backupPath})` : "") +
+      " — permissions set to owner-only since the file now holds your API key." +
+      "\n" +
+      reach +
+      " Undo anytime with: " +
+      revertCmd +
+      "\n\nVS Code note: the extension reads this file for its sessions, but " +
+      "its own pre-launch login check does not — if you have no saved " +
+      "Anthropic login, also add these to VS Code's user settings " +
+      "(Preferences: Open User Settings (JSON)), then reload the window:\n" +
+      `  "claudeCode.disableLoginPrompt": true,\n` +
+      `  "claudeCode.environmentVariables": [\n` +
+      `    { "name": "ANTHROPIC_BASE_URL", "value": "${apiUrl}" },\n` +
+      `    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "<your SAIL_API_KEY>" }\n` +
+      `  ]`,
+  );
+  return 0;
+}
+
+/** Restore the pre-setup settings.json, or strip exactly our keys. */
+export function revert({ scope = "user" }) {
+  const filePath = settingsPath(scope);
+  const backupPath = filePath + BACKUP_SUFFIX;
+
+  if (fs.existsSync(backupPath)) {
+    if (fs.readFileSync(backupPath, "utf8") === ABSENT_SENTINEL) {
+      // setup created this file (nothing existed before). Remove what we made
+      // — deleting the API key — rather than "restoring" the Sail-injected
+      // file. Clear the sentinel too so the slate is truly clean.
+      fs.rmSync(filePath, { force: true });
+      fs.rmSync(backupPath, { force: true });
+      console.error(`Removed ${filePath} (it did not exist before setup).`);
+      return 0;
+    }
+    fs.renameSync(backupPath, filePath);
+    console.error(`Restored ${filePath} from ${backupPath}.`);
+    return 0;
+  }
+
+  const { settings, existed } = readSettings(filePath);
+  if (!existed) {
+    console.error(`Nothing to revert: ${filePath} does not exist.`);
+    return 0;
+  }
+  if (settings.env && typeof settings.env === "object") {
+    for (const key of OWNED_ENV_KEYS) delete settings.env[key];
+    // Clear the falsy overrides a project-scope setup wrote, but only when
+    // still empty — a real value re-added after setup is the user's, not ours.
+    for (const key of [
+      ...CONFLICTING_PROVIDER_VARS,
+      ...HEADER_INJECTION_VARS,
+    ]) {
+      if (settings.env[key] === "") delete settings.env[key];
+    }
+    if (Object.keys(settings.env).length === 0) delete settings.env;
+  }
+  writeSettings(filePath, settings);
+  console.error(
+    `Removed Sail routing keys from ${filePath} (no backup was present).`,
+  );
+  return 0;
+}

package/src/toml.js

@@ -0,0 +1,143 @@
+/**
+ * Minimal TOML subset shared with the Sail CLI's `~/.sail` files: flat
+ * `key = "value"` tables with comments. This is not a general TOML parser —
+ * it reads exactly the shape `sail auth` / `sail config` write (plus bare
+ * unquoted values from hand edits) and fails loudly on anything else, the
+ * same posture as the Rust CLI.
+ */
+
+/** Parse a flat TOML table into a plain object of string values. */
+export function parseTomlTable(text, sourcePath) {
+  const values = {};
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) {
+      throw new Error(
+        `could not parse ${sourcePath} (line ${i + 1}: expected "key = value"). ` +
+          `Edit the file to fix it, or delete it and log in again.`,
+      );
+    }
+    const key = line.slice(0, eq).trim();
+    if (!/^[A-Za-z0-9_-]+$/.test(key)) {
+      throw new Error(
+        `could not parse ${sourcePath} (line ${i + 1}: invalid key "${key}"). ` +
+          `Edit the file to fix it, or delete it and log in again.`,
+      );
+    }
+    const rawValue = line.slice(eq + 1).trim();
+    values[key] = parseTomlValue(rawValue, sourcePath, i + 1);
+  }
+  return values;
+}
+
+function parseTomlValue(raw, sourcePath, lineNo) {
+  if (raw.startsWith('"')) {
+    return parseBasicString(raw, sourcePath, lineNo);
+  }
+  if (raw.startsWith("'")) {
+    // TOML literal string: verbatim content, no escapes.
+    const end = raw.indexOf("'", 1);
+    if (end === -1) {
+      throw new Error(
+        `could not parse ${sourcePath} (line ${lineNo}: unterminated string).`,
+      );
+    }
+    const rest = raw.slice(end + 1).trim();
+    if (rest !== "" && !rest.startsWith("#")) {
+      throw new Error(
+        `could not parse ${sourcePath} (line ${lineNo}: trailing content after string).`,
+      );
+    }
+    return raw.slice(1, end);
+  }
+  // Bare value (hand-edited file): take up to a trailing comment.
+  const hash = raw.indexOf("#");
+  const bare = (hash === -1 ? raw : raw.slice(0, hash)).trim();
+  if (bare === "") {
+    throw new Error(
+      `could not parse ${sourcePath} (line ${lineNo}: empty value). ` +
+        `Edit the file to fix it, or delete it and log in again.`,
+    );
+  }
+  return bare;
+}
+
+function parseBasicString(raw, sourcePath, lineNo) {
+  let out = "";
+  let i = 1;
+  while (i < raw.length) {
+    const ch = raw[i];
+    if (ch === '"') {
+      const rest = raw.slice(i + 1).trim();
+      if (rest !== "" && !rest.startsWith("#")) {
+        throw new Error(
+          `could not parse ${sourcePath} (line ${lineNo}: trailing content after string).`,
+        );
+      }
+      return out;
+    }
+    if (ch === "\\") {
+      const esc = raw[i + 1];
+      const simple = {
+        '"': '"',
+        "\\": "\\",
+        b: "\b",
+        t: "\t",
+        n: "\n",
+        f: "\f",
+        r: "\r",
+      };
+      if (esc in simple) {
+        out += simple[esc];
+        i += 2;
+        continue;
+      }
+      if (esc === "u" || esc === "U") {
+        const width = esc === "u" ? 4 : 8;
+        const hex = raw.slice(i + 2, i + 2 + width);
+        if (!new RegExp(`^[0-9A-Fa-f]{${width}}$`).test(hex)) {
+          throw new Error(
+            `could not parse ${sourcePath} (line ${lineNo}: bad \\${esc} escape).`,
+          );
+        }
+        out += String.fromCodePoint(parseInt(hex, 16));
+        i += 2 + width;
+        continue;
+      }
+      throw new Error(
+        `could not parse ${sourcePath} (line ${lineNo}: unsupported escape \\${esc ?? ""}).`,
+      );
+    }
+    out += ch;
+    i += 1;
+  }
+  throw new Error(
+    `could not parse ${sourcePath} (line ${lineNo}: unterminated string).`,
+  );
+}
+
+/**
+ * Render a value as a TOML basic string with control characters escaped,
+ * byte-identical to the Rust CLI's `toml_basic_string`, so files written by
+ * either tool round-trip through the other.
+ */
+export function tomlBasicString(value) {
+  let out = '"';
+  for (const ch of String(value)) {
+    const code = ch.codePointAt(0);
+    if (ch === '"') out += '\\"';
+    else if (ch === "\\") out += "\\\\";
+    else if (ch === "\b") out += "\\b";
+    else if (ch === "\t") out += "\\t";
+    else if (ch === "\n") out += "\\n";
+    else if (ch === "\f") out += "\\f";
+    else if (ch === "\r") out += "\\r";
+    else if (code < 0x20 || code === 0x7f) {
+      out += `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+    } else out += ch;
+  }
+  return out + '"';
+}