@koriit/opencode-claude-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksander Stelmaczonek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# opencode-claude-bridge
+
+An [OpenCode](https://opencode.ai) plugin that bridges your **enabled Claude Code plugins** —
+the bundles managed by `claude plugin install` and stored under `~/.claude/plugins/cache/…` — into
+OpenCode at runtime. Their **commands, agents, skills** (and, opt-in, **MCP** and **LSP** servers)
+become available inside OpenCode, namespaced so they never shadow your existing items.
+
+It is a single plugin: no wrapper binary, no generated files, no lockfile. You run plain
+`opencode`; the plugin reads Claude's enabled-plugin state via `claude plugin list --json` and
+injects the components live on each launch.
+
+> **Status.** Early development. Commands, agents, skills, MCP servers, and LSP servers from
+> enabled Claude plugins are all injected into OpenCode (see below). MCP and LSP are opt-in and
+> off by default.
+
+## Requirements
+
+- **OpenCode** within the supported range below.
+- The **`claude` CLI** on your `PATH` at OpenCode runtime — the bridge's entire purpose is reading
+  Claude's plugin state. If it is missing, the bridge logs a warning and injects nothing (OpenCode
+  still starts normally).
+
+### Supported OpenCode version
+
+```text
+>=1.15.0 <1.16.0
+```
+
+Verified against **OpenCode 1.15.10**. The bridge relies on OpenCode-internal behavior that is not
+a documented public contract, so it pins a conservative same-minor window. At startup it reads the
+running OpenCode version and logs a one-line warning if you are outside this range — it still
+attempts to work, but treat that as untested. The range is widened only after the end-to-end suite
+passes against a new version.
+
+## Install
+
+Add the plugin to your **global** `~/.config/opencode/opencode.json` so it applies across all
+projects:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@koriit/opencode-claude-bridge",
+      {
+        "allowMcp": false,
+        "allowLsp": false,
+        "blockedPlugins": []
+      }
+    ]
+  ]
+}
+```
+
+The bare-string form works too and uses all defaults:
+
+```jsonc
+{
+  "plugin": ["@koriit/opencode-claude-bridge"]
+}
+```
+
+**How it works.** OpenCode installs plugins via Arborist with `ignoreScripts: true` — no build step
+runs on install. The package entry points at `src/index.ts` intentionally: OpenCode runs on Bun,
+which imports TypeScript directly. Zero runtime dependencies; all `@opencode-ai/plugin` imports are
+`import type` (erased at runtime).
+
+### Releasing (maintainer)
+
+1. Bump `version` in `package.json`, commit.
+2. Create a GitHub Release with tag `v<version>` (e.g. `v0.1.1`).
+3. The [publish workflow](.github/workflows/publish.yml) runs the test gates and publishes to npm
+   automatically (requires the `NPM_TOKEN` secret to be configured in the repo — see the workflow
+   file header for setup instructions).
+
+## Configuration
+
+All keys are optional; the table shows their defaults.
+
+| Key              | Type              | Default         | Meaning                                                        |
+| ---------------- | ----------------- | --------------- | -------------------------------------------------------------- |
+| `mode`           | `"mirror-claude"` | `mirror-claude` | The only accepted mode (mirror exactly Claude's enabled set).  |
+| `allowMcp`       | boolean           | `false`         | Inject MCP servers from plugins (global on/off).               |
+| `allowLsp`       | boolean           | `false`         | Inject LSP servers from plugins (global on/off).               |
+| `blockedPlugins` | `string[]`        | `[]`            | Plugin ids (`name@marketplace`) to never inject.               |
+| `strict`         | boolean           | `false`         | Promote warnings (parse failures, missing CLI) to hard errors. |
+
+Unknown keys and ill-typed values are ignored with a warning.
+
+### What gets bridged (`mirror-claude`)
+
+A Claude plugin is bridged when `claude plugin list --json` reports it as **enabled** and it is in
+scope for the current project:
+
+- `user`-scoped plugins always apply (they are global).
+- `project`/`local`-scoped plugins apply only when their project matches your current directory.
+- ids listed in `blockedPlugins` are never bridged.
+
+### What is injected
+
+| Component | Status   | Notes                                                                                                                                                                                                  |
+| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Commands  | Injected | `commands/**/*.md` → `cfg.command`; `$ARGUMENTS`/`$1..n` pass through                                                                                                                                  |
+| Agents    | Injected | `agents/*.md` → `cfg.agent`; `prompt` field (not `system`); `mode` defaults to `subagent` (also accepts `primary`/`all`); `temperature`, `top_p`, `steps`, `hidden`, `color`, `variant` passed through |
+| Skills    | Injected | `skills/<name>/SKILL.md` dirs → `cfg.skills.paths`; zero files copied in the common case; collision-renamed copies go to `~/.cache/opencode-claude-bridge/skills/` (see below)                         |
+| MCP       | Injected | Opt-in (`allowMcp: true`). Source: `<installPath>/.mcp.json`. Claude `type:"http"` → OpenCode `type:"remote"`; stdio/command → `type:"local"`. Processes spawned on connection.                        |
+| LSP       | Injected | Opt-in (`allowLsp: true`). Source: `<installPath>/.lsp.json`. `cfg.lsp === false` is respected. Processes spawned per file-type activation.                                                            |
+
+### Skills: no-copy in the common case, bridge cache on collision
+
+Each skill in a plugin's `skills/<name>/` directory is discovered by reading its `SKILL.md`
+frontmatter `name`. In the common case — no name collision — the plugin's own skill directory is
+pushed directly onto `cfg.skills.paths`: **zero files are copied**.
+
+When a collision is detected (the bare name is already taken by a native OpenCode skill, a built-in,
+or an earlier-processed plugin), the entire skill directory is copied to the bridge cache at:
+
+```text
+~/.cache/opencode-claude-bridge/skills/<marketplace>/<plugin>/<version>/<allocatedName>/
+```
+
+where `<marketplace>` and `<plugin>` are the two halves of the plugin id (e.g. `acme` and
+`my-plugin` from `my-plugin@acme`). The copy's `SKILL.md` frontmatter `name` is patched to
+the prefixed name; all other files (assets, sub-directories) are preserved so relative references
+within the skill continue to work. The `.git` directory and other dot-directories are excluded
+from copies.
+
+Copies are keyed by `<marketplace>/<plugin>/<version>/<allocatedName>` and regenerated when the
+source is newer. When the plugin version changes, the old version's cache directories are pruned
+automatically (version GC). The bridge cache is distinct from OpenCode's own
+`~/.cache/opencode/skills`.
+
+To override the cache location (e.g. in CI or test environments), set the
+`OPENCODE_CLAUDE_BRIDGE_CACHE_ROOT` environment variable before starting OpenCode.
+
+> **URL-sourced skills:** if your `opencode.json` lists entries in `cfg.skills.urls`, the bridge
+> cannot detect collision against them at hook time (fetching URL skills would force the lazy Skill
+> service to load before our injected paths). A warning is logged when URLs are present.
+
+### MCP servers (opt-in)
+
+When `allowMcp: true`, the bridge reads each enabled plugin's top-level `.mcp.json` and injects
+the declared servers into OpenCode's flat `cfg.mcp` record. The mapping:
+
+- Claude `type:"http"` → OpenCode `{ type:"remote", url, headers?, oauth? }`
+- Claude stdio/command servers → OpenCode `{ type:"local", command:[cmd, ...args], environment? }`
+- `${CLAUDE_PLUGIN_ROOT}` is resolved to the plugin's `installPath` in all string fields.
+- OAuth: the `clientId`, `callbackPort`, etc. field names are identical between Claude and OpenCode.
+
+**Name:** `<plugin>-<server>` (e.g. a plugin `slack@official` with server `slack` becomes
+`slack-slack`). The same no-shadowing + collision-rename rules apply.
+
+Because MCP servers spawn external processes (and can initiate network connections), they are
+gated behind an explicit `allowMcp: true` toggle — **off by default.**
+
+### LSP servers (opt-in)
+
+When `allowLsp: true`, the bridge reads each enabled plugin's top-level `.lsp.json` and injects
+the declared servers into `cfg.lsp`. The mapping:
+
+- Claude `command` (string) + `args` (array) → OpenCode `command` (string array)
+- Claude `extensionToLanguage` keys (e.g. `{ ".rs": "rust" }`) → OpenCode `extensions` array
+- `env`, `initializationOptions` (falling back to `settings`) → `env`, `initialization`
+  (only one is used; `initializationOptions` takes precedence — they do not merge)
+- `${CLAUDE_PLUGIN_ROOT}` is resolved in command, args, and env values.
+- Servers with no `.`-prefixed keys in `extensionToLanguage`, or with `transport: "socket"`,
+  are skipped with a warning (OpenCode requires `extensions` for custom LSP servers and has
+  no socket transport support).
+
+**`cfg.lsp === false` is respected.** If the user explicitly set `lsp: false` in their
+`opencode.json`, the bridge injects no LSP servers. This only skips LSP — commands, agents,
+skills, and MCP still inject normally.
+
+**Name:** `<plugin>-<server>` with the same collision-rename ladder.
+
+Because LSP servers spawn external processes, they are gated behind `allowLsp: true` — **off by
+default.**
+
+> **LSP source note:** the `.lsp.json` convention is derived from Claude Code's plugin loader
+> source. No real installed Claude LSP plugin with a `.lsp.json` was available to validate against
+> at the time of implementation; validate against a live LSP plugin if you enable this feature.
+
+### No-shadowing & naming
+
+Injected items are namespaced so they **never shadow** your existing OpenCode commands, agents, or
+skills (including OpenCode's built-ins). When a name collision is detected the **bridge's item** is
+renamed — the native/existing item is never touched. The rename ladder:
+
+1. `<plugin>-<name>` (e.g. `kio-development-audit`)
+2. `<marketplace>-<plugin>-<name>` if still colliding
+3. `<marketplace>-<plugin>-<name>-<8hex>` deterministic hash tiebreak
+
+Processing order is sorted by plugin id, so the first claimant of a bare name wins
+deterministically across runs.
+
+Every injected item's description is suffixed with `[plugin-id]` for traceability.
+
+### Security defaults
+
+Commands, agents, and skills are text prompts (lower risk) and are always bridged — but always
+namespaced so they can never shadow your own items. MCP and LSP servers **spawn processes** and
+can initiate network connections, so they are gated behind the explicit `allowMcp` / `allowLsp`
+toggles, both **off by default**.
+
+- `blockedPlugins` hard-excludes plugin ids from all injection (commands, agents, skills, MCP, LSP).
+- The `allowMcp`/`allowLsp` toggles are all-or-nothing per type — there is no per-plugin trust level.
+- Disabled plugins (those reported as `enabled: false` by `claude plugin list --json`) are always skipped.
+
+## Development
+
+This is a Bun + TypeScript package.
+
+```bash
+bun install              # install dev dependencies
+bun run typecheck        # type-check src + tests
+bun run build            # emit dist/
+bun run test             # unit tests (sets OCB_TMPDIR=.tmp)
+bun run test:e2e         # end-to-end tests (sets OCB_TMPDIR=.tmp; launches real opencode)
+bun run test:all         # unit + e2e
+bun run test:coverage    # unit tests with line/function coverage report
+```
+
+> **Note on test commands:** always use `bun run test` (the npm script) rather than `bun test test/`
+> directly. The scripts set `OCB_TMPDIR=.tmp` to keep test scratch off a potentially small system
+> `/tmp`.
+
+### Bridge diagnostics
+
+Bridge log lines are prefixed `[opencode-claude-bridge]` and are written to the
+`opencode` process's **stderr**. OpenCode does not rebind `console.*` and does not
+capture plugin output into its own log file — the bridge's messages only reach
+OpenCode's log file if they are written through OpenCode's own `Log.*` API, which
+the bridge does not use.
+
+**In-TUI nudge.** If the bridge emitted any warnings during startup, a single
+`warning` toast appears on your first message in the TUI:
+
+> opencode-claude-bridge encountered issues — run with --print-logs for details
+
+The toast is deferred to your first chat interaction (rather than shown at startup)
+because the TUI's event subscription is not yet guaranteed at the moment the config
+hook runs (the hook fires on the first instance request, concurrent with the TUI
+subscribing to the server's event stream). The toast fires at most once per session.
+
+**Full diagnostic detail.** To see every `[opencode-claude-bridge]` log line,
+run `opencode` (or `opencode serve`) with `--print-logs`:
+
+```bash
+opencode --print-logs
+```
+
+In non-TUI mode (`opencode serve`) or when running without `--print-logs`, all
+bridge output goes to stderr only — the toast nudge is not shown in non-TUI mode.
+If something appears to be missing or misbehaving, rerun with `--print-logs` to
+surface the full set of skip/warn messages.
+
+The end-to-end suite launches a real `opencode serve` with the plugin loaded and a fake `claude`
+CLI on `PATH`, then asserts behavior against the live HTTP API. It also acts as the
+version-compatibility canary: run it after every OpenCode upgrade before widening the supported
+range.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@koriit/opencode-claude-bridge",
+  "version": "0.1.0",
+  "description": "An OpenCode plugin that bridges enabled Claude Code plugins (commands, agents, skills, MCP, LSP) into OpenCode at runtime, namespaced so they never shadow your existing items.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Koriit/opencode-claude-bridge.git"
+  },
+  "homepage": "https://github.com/Koriit/opencode-claude-bridge#readme",
+  "bugs": "https://github.com/Koriit/opencode-claude-bridge/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "clean": "rm -rf dist .tmp",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "OCB_TMPDIR=.tmp bun test test/",
+    "test:e2e": "OCB_TMPDIR=.tmp bun test e2e/",
+    "test:all": "OCB_TMPDIR=.tmp bun test",
+    "test:coverage": "bun run scripts/coverage-gate.ts"
+  },
+  "keywords": [
+    "opencode",
+    "claude",
+    "claude-code",
+    "plugin",
+    "bridge"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "opencode": {
+    "supportedRange": ">=1.15.0 <1.16.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.15.13",
+    "@opencode-ai/sdk": "1.15.13",
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,82 @@
+import { DEFAULT_BRIDGE_CONFIG, type BridgeConfig } from "./types.js"
+
+export interface ParsedBridgeConfig {
+  config: BridgeConfig
+  /**
+   * Validation warnings collected while parsing. These are strict-promotable: the
+   * caller replays them through the logger (which throws under `strict`). Parsing
+   * itself is pure and never throws, so `strict` can be resolved first and the
+   * logger built from it.
+   */
+  warnings: string[]
+}
+
+const DOCUMENTED_KEYS = new Set(["mode", "allowMcp", "allowLsp", "blockedPlugins", "strict"])
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Parse the `opencode.json` plugin-tuple options into a {@link BridgeConfig}, honoring
+ * only the documented keys (§4.2). Unknown keys and ill-typed values are dropped to
+ * their defaults and reported as warnings. Pure and total — never throws.
+ */
+export function parseBridgeConfig(options: unknown): ParsedBridgeConfig {
+  const config: BridgeConfig = {
+    ...DEFAULT_BRIDGE_CONFIG,
+    blockedPlugins: [...DEFAULT_BRIDGE_CONFIG.blockedPlugins],
+  }
+  const warnings: string[] = []
+
+  if (options === undefined || options === null) {
+    return { config, warnings }
+  }
+  if (!isPlainObject(options)) {
+    warnings.push(
+      `ignoring plugin options: expected an object, got ${Array.isArray(options) ? "array" : typeof options}`,
+    )
+    return { config, warnings }
+  }
+
+  if ("mode" in options) {
+    if (options["mode"] !== "mirror-claude") {
+      warnings.push(
+        `unsupported mode ${JSON.stringify(options["mode"])}; only "mirror-claude" is supported, using it`,
+      )
+    }
+    // mode is effectively hardcoded; nothing to assign beyond the default.
+  }
+
+  for (const key of ["allowMcp", "allowLsp", "strict"] as const) {
+    if (key in options) {
+      const value = options[key]
+      if (typeof value === "boolean") {
+        config[key] = value
+      } else {
+        warnings.push(`ignoring "${key}": expected boolean, got ${typeof value}`)
+      }
+    }
+  }
+
+  if ("blockedPlugins" in options) {
+    const value = options["blockedPlugins"]
+    if (Array.isArray(value)) {
+      const strings = value.filter((v): v is string => typeof v === "string")
+      if (strings.length !== value.length) {
+        warnings.push(`ignoring non-string entries in "blockedPlugins"`)
+      }
+      config.blockedPlugins = strings
+    } else {
+      warnings.push(`ignoring "blockedPlugins": expected string[], got ${typeof value}`)
+    }
+  }
+
+  for (const key of Object.keys(options)) {
+    if (!DOCUMENTED_KEYS.has(key)) {
+      warnings.push(`ignoring unknown option "${key}"`)
+    }
+  }
+
+  return { config, warnings }
+}

package/src/frontmatter.ts

@@ -0,0 +1,159 @@
+/**
+ * Minimal zero-dependency frontmatter parser for Claude command/agent/skill files.
+ *
+ * Claude frontmatter is a flat key-value YAML block. The fields we care about are all
+ * scalar strings, booleans, or numbers. We parse only those and silently ignore anything
+ * that requires full YAML parsing (nested maps, sequences, multi-line block scalars, etc.),
+ * consistent with the lenient approach used in `skill-scan.ts` for skill name extraction.
+ *
+ * This deliberately avoids adding a `gray-matter` or any other npm dependency.
+ */
+
+export const FRONTMATTER_FENCE = "---"
+
+/**
+ * A parsed frontmatter block: the extracted flat scalar values and the markdown body
+ * (everything after the closing `---` fence, trimmed).
+ *
+ * Fields that were present but not parseable as flat scalars are omitted (not reported
+ * as errors — consistent with the lenient parse posture).
+ */
+export interface ParsedFrontmatter {
+  data: Record<string, string | boolean | number>
+  body: string
+}
+
+/**
+ * Sentinel returned when the file has an opening `---` fence but no closing one.
+ * Callers should skip the file and warn rather than treating the broken YAML as
+ * a no-frontmatter plain-markdown file (§10).
+ */
+export const FRONTMATTER_PARSE_ERROR: unique symbol = Symbol("FRONTMATTER_PARSE_ERROR")
+export type FrontmatterParseError = typeof FRONTMATTER_PARSE_ERROR
+
+/**
+ * Split content into lines and locate the frontmatter fence boundaries.
+ *
+ * Returns:
+ *   - `null` if the file does not begin with a `---` fence (no frontmatter).
+ *   - `FRONTMATTER_PARSE_ERROR` if an opening fence is found but never closed.
+ *   - `{ lines, closingIdx }` on success — `lines[1..closingIdx-1]` are the
+ *     frontmatter key/value lines; `lines[closingIdx+1..]` is the body.
+ *
+ * This is the shared fence-detection core used by both `parseFrontmatter`
+ * (in this module) and `extractSkillName` (in `skill-scan.ts`). Both callers
+ * need fence detection but have different field-extraction semantics, so the
+ * extraction itself is left to each call site.
+ */
+export function locateFrontmatter(
+  content: string,
+): { lines: string[]; closingIdx: number } | null | FrontmatterParseError {
+  const lines = content.split(/\r?\n/)
+
+  if (lines[0]?.trim() !== FRONTMATTER_FENCE) return null
+
+  let closingIdx = -1
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === FRONTMATTER_FENCE) {
+      closingIdx = i
+      break
+    }
+  }
+  if (closingIdx === -1) return FRONTMATTER_PARSE_ERROR
+
+  return { lines, closingIdx }
+}
+
+/**
+ * Parse a markdown file's YAML frontmatter and return the flat scalar fields plus the body.
+ *
+ * Handles:
+ *   - Bare values: `key: value`
+ *   - Single- and double-quoted strings: `key: "value"` / `key: 'value'`
+ *   - Booleans: `true` / `false` (case-insensitive)
+ *   - Numbers: integer and floating-point decimal strings
+ *
+ * Ignores:
+ *   - Lines that start with whitespace (nested YAML — inside a block scalar or map)
+ *   - Lines whose value starts with `{`, `[`, or `|` (maps, sequences, block scalars)
+ *   - YAML comments (`#`)
+ *   - Anything that looks like a multi-line scalar continuation
+ *
+ * Returns:
+ *   - `null` if the file does not begin with a `---` fence (no frontmatter — treat
+ *     the whole file as the body).
+ *   - `FRONTMATTER_PARSE_ERROR` if an opening fence is found but never closed —
+ *     the caller must skip and warn rather than injecting broken YAML as body text (§10).
+ *   - `ParsedFrontmatter` on success.
+ */
+export function parseFrontmatter(
+  content: string,
+): ParsedFrontmatter | null | FrontmatterParseError {
+  const located = locateFrontmatter(content)
+  if (located === null || located === FRONTMATTER_PARSE_ERROR) return located
+
+  const { lines, closingIdx } = located
+  const data: Record<string, string | boolean | number> = {}
+  const fmLines = lines.slice(1, closingIdx)
+
+  for (const line of fmLines) {
+    // Skip blank lines, indented lines (nested values), and YAML comments.
+    if (!line || /^\s/.test(line) || line.trimStart().startsWith("#")) continue
+
+    // Match `key: value` — key must start at column 0.
+    const colonIdx = line.indexOf(":")
+    if (colonIdx < 1) continue
+
+    const key = line.slice(0, colonIdx).trim()
+    if (!key) continue
+
+    const rawValue = line.slice(colonIdx + 1).trim()
+
+    // Skip empty values, block scalars (|, >), sequences ([), maps ({).
+    if (!rawValue || rawValue[0] === "|" || rawValue[0] === ">" || rawValue[0] === "[" || rawValue[0] === "{")
+      continue
+
+    data[key] = parseScalar(rawValue)
+  }
+
+  const bodyLines = lines.slice(closingIdx + 1)
+  const body = bodyLines.join("\n").trim()
+
+  return { data, body }
+}
+
+/**
+ * Parse a YAML scalar value into a TypeScript primitive.
+ *
+ * Handles quoted strings, booleans, and numbers. Anything that doesn't fit is
+ * returned as a trimmed string (safe fallback for unknown values).
+ */
+function parseScalar(raw: string): string | boolean | number {
+  // Quoted string: strip surrounding quotes (single or double).
+  // Require both opening and closing quote to be the same character and the
+  // string to be at least 2 chars long (a lone `"` or `'` is not a valid
+  // YAML scalar — treat it as a bare string to avoid a silent empty result).
+  const startsDouble = raw.startsWith('"')
+  const startsSingle = raw.startsWith("'")
+  const endsDouble = raw.endsWith('"')
+  const endsSingle = raw.endsWith("'")
+  if (raw.length >= 2) {
+    if (startsDouble && endsDouble) return raw.slice(1, -1)
+    if (startsSingle && endsSingle) return raw.slice(1, -1)
+  }
+  // Unbalanced quotes (e.g. `"missing closing`) are returned as-is — the
+  // caller receives the literal value including the opening quote, which is
+  // a better outcome than stripping half a pair and silently producing a
+  // wrong name.
+
+  // Boolean literals.
+  const lower = raw.toLowerCase()
+  if (lower === "true") return true
+  if (lower === "false") return false
+
+  // Numeric literal (integer or float; no octal/hex — YAML 1.2 only has these forms).
+  // The regex already guarantees a finite decimal, so Number() cannot return NaN here.
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw)
+
+  return raw
+}