openspec-playwright 0.3.73 → 0.3.75

package/dist/commands/editors.js

@@ -1,962 +1,40 @@
 /**
- * Editor adapter layer.
- *
- * Claude Code, OpenCode, Cline, and Cursor can host the /opsx:e2e command,
- * plus a project-level rules file (CLAUDE.md / AGENTS.md) and an MCP server
- * definition. Each editor has its own conventions — file path, frontmatter
- * shape, MCP install mechanism — so this module exposes a single
- * `EditorAdapter` interface and a registry that callers can iterate.
- *
- * Conventions follow the upstream OpenSpec reference implementation:
- *   - Claude:  `.claude/commands/opsx/<id>.md`, full frontmatter,
- *              `claude mcp add …`, reads CLAUDE.md directly.
- *   - OpenCode: `.opencode/commands/opsx-<id>.md`, description-only
- *              frontmatter, edits `opencode.json(c)`, reads files listed
- *              under `instructions` (CLAUDE.md is a built-in fallback).
- *   - Cline:   `.cline/skills/opsx-<id>/SKILL.md`, name+description
- *              frontmatter, edits `.cline/mcp.json`, auto-detects AGENTS.md.
- *   - Cursor:  `.cursor/commands/opsx-<id>.md` (plain MD) +
- *              `.cursor/skills/opsx-<id>/SKILL.md` (extraArtifacts),
- *              edits `.cursor/mcp.json`, auto-detects AGENTS.md.
- *   - Pi:      `.pi/prompts/opsx-<id>.md` (prompt template), description +
- *              argument-hint frontmatter, NO MCP client (supportsMcp:false),
- *              auto-detects AGENTS.md. Detected via `.pi/` or `~/.pi/agent/`.
- *   - Oh My Pi: `.omp/commands/opsx-<id>.md`, name+description frontmatter,
- *              edits `.omp/mcp.json` (same shape as Cline/Cursor),
- *              auto-detects AGENTS.md. Detected via `.omp/` or `~/.omp/agent/`.
- *   - DeepSeek Harness: `.dsh/skills/opsx-<id>/SKILL.md` (project-dsh skill,
- *              rank 100), name+description frontmatter, NO MCP client
- *              (supportsMcp:false — MCP is configured via cordis.yml plugin
- *              config, not a simple file), auto-detects AGENTS.md. Detected
- *              via `.dsh/` or `~/.dsh/` (DSH_HOME).
- */
-import { existsSync, lstatSync, mkdirSync, rmSync, writeFileSync, readFileSync, } from "fs";
-import { execFileSync } from "node:child_process";
-import { homedir } from "os";
-import { join, dirname, basename, resolve as pathResolve } from "path";
-import chalk from "chalk";
-import { modify, applyEdits, parseTree as parseJsonc, findNodeAtLocation, getNodeValue, } from "jsonc-parser";
-import { TIMEOUT } from "../shared/constants.js";
-import { needsShell } from "../shared/platform.js";
-// ─── YAML helpers (shared by Claude frontmatter and elsewhere) ───────────
-/** Escape a value for safe inclusion in a YAML frontmatter scalar. */
-export function escapeYamlValue(value) {
-    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
-    if (needsQuoting) {
-        const escaped = value
-            .replace(/\\/g, "\\\\")
-            .replace(/"/g, '\\"')
-            .replace(/\n/g, "\\n");
-        return `"${escaped}"`;
-    }
-    return value;
-}
-/** Format tags as a YAML inline array. */
-export function formatTagsArray(tags) {
-    return `[${tags.map((t) => escapeYamlValue(t)).join(", ")}]`;
-}
-// ─── Body transform ──────────────────────────────────────────────────────
-/**
- * OpenCode slash-command names are hyphenated (`/opsx-e2e`), Claude's are
- * colon-prefixed (`/opsx:e2e`). Rewrite all `/opsx:` references in a
- * command body for OpenCode installation.
- */
-export function transformToHyphenCommands(text) {
-    return text.replace(/\/opsx:/g, "/opsx-");
-}
-/** Build the command metadata for the /opsx:e2e command. */
-export function buildCommandMeta(body) {
-    return {
-        id: "e2e",
-        name: "OPSX: E2E",
-        description: "Run Playwright E2E verification for an OpenSpec change",
-        category: "OpenSpec",
-        tags: ["openspec", "playwright", "e2e", "testing"],
-        body,
-    };
-}
-const noop = () => { };
-const alwaysFalse = () => false;
-/**
- * Build an `EditorAdapter` from a partial init object. Fills in
- * defaults so each adapter only declares what's actually different.
- */
-export function defineAdapter(init) {
-    return {
-        id: init.id,
-        label: init.label,
-        displayName: init.displayName,
-        detect: init.detect,
-        commandFilePath: init.commandFilePath,
-        formatCommand: init.formatCommand,
-        supportsMcp: init.supportsMcp ?? true,
-        projectRulesPath: init.projectRulesPath ?? ((root) => join(root, "AGENTS.md")),
-        isMcpInstalled: init.isMcpInstalled ?? alwaysFalse,
-        installMcp: init.installMcp ?? noop,
-        removeMcp: init.removeMcp ?? noop,
-        registerInstructions: init.registerInstructions,
-        extraArtifacts: init.extraArtifacts,
-    };
-}
-// ─── Claude Code adapter ─────────────────────────────────────────────────
-export function formatClaudeCommand(meta) {
-    return `---
-name: ${escapeYamlValue(meta.name)}
-description: ${escapeYamlValue(meta.description)}
-category: ${escapeYamlValue(meta.category)}
-tags: ${formatTagsArray(meta.tags)}
----
-
-${meta.body}
-`;
-}
-export function getClaudeCommandPath(id) {
-    return join(".claude", "commands", "opsx", `${id}.md`);
-}
-export function hasClaudeCode(projectRoot) {
-    return existsSync(join(projectRoot, ".claude"));
-}
-// ─── OpenCode adapter ────────────────────────────────────────────────────
-export function formatOpenCodeCommand(meta) {
-    const body = transformToHyphenCommands(meta.body);
-    return `---
-description: ${escapeYamlValue(meta.description)}
----
-
-${body}
-`;
-}
-export function getOpenCodeCommandPath(id) {
-    return join(".opencode", "commands", `opsx-${id}.md`);
-}
-export function hasOpenCode(projectRoot) {
-    return existsSync(join(projectRoot, ".opencode"));
-}
-const JSONC_FORMAT = { tabSize: 2, insertSpaces: true };
-/** Find the first existing opencode.json(c), or null. */
-function findOpenCodeConfig(projectRoot) {
-    for (const name of ["opencode.jsonc", "opencode.json"]) {
-        const p = join(projectRoot, name);
-        if (existsSync(p))
-            return { path: p, text: readFileSync(p, "utf-8") };
-    }
-    return null;
-}
-/**
- * Set a value at a JSON path inside opencode.json(c), creating the file
- * with a `$schema` scaffold if it doesn't exist. Replaces any existing
- * value at the path (does not merge arrays).
- */
-function setOpenCodeValue(projectRoot, keySegments, value) {
-    const existing = findOpenCodeConfig(projectRoot);
-    const targetPath = existing?.path ?? join(projectRoot, "opencode.jsonc");
-    if (!existing) {
-        const scaffold = {
-            $schema: "https://opencode.ai/config.json",
-        };
-        // Build nested scaffold for multi-segment keys (e.g. ["mcp", "playwright"])
-        let cursor = scaffold;
-        for (let i = 0; i < keySegments.length - 1; i++) {
-            const k = String(keySegments[i]);
-            cursor[k] = {};
-            cursor = cursor[k];
-        }
-        cursor[String(keySegments[keySegments.length - 1])] = value;
-        // ponytail: new file uses 2-space indent; modify branch preserves existing formatting.
-        writeFileSync(targetPath, JSON.stringify(scaffold, null, 2) + "\n");
-        return;
-    }
-    const edits = modify(existing.text, keySegments, value, {
-        formattingOptions: JSONC_FORMAT,
-    });
-    writeFileSync(targetPath, applyEdits(existing.text, edits));
-}
-/** Read the current value at a JSON path (returns undefined if missing). */
-function readOpenCodeValue(text, keySegments) {
-    try {
-        const tree = parseJsonc(text);
-        if (!tree)
-            return undefined;
-        const node = findNodeAtLocation(tree, keySegments);
-        return node ? getNodeValue(node) : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Read the current `instructions` array from opencode.json(c), or undefined. */
-function readOpenCodeInstructions(projectRoot) {
-    const config = findOpenCodeConfig(projectRoot);
-    if (!config)
-        return undefined;
-    const value = readOpenCodeValue(config.text, ["instructions"]);
-    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
-        return value;
-    }
-    return undefined;
-}
-// ─── Cline adapter ───────────────────────────────────────────────────────
-/**
- * Cline stores project-level config in `.cline/` (skills/, rules/, mcp.json).
- * `.clinerules/` is the legacy rules-only directory, still auto-detected.
- *
- * Conventions follow the Cline documentation (2026):
- *   - Skills:   `.cline/skills/<name>/SKILL.md` with YAML frontmatter
- *                (name + description). Triggered via `/<name>` slash command.
- *   - MCP:      `.cline/mcp.json` with `{ "mcpServers": { ... } }` structure.
- *   - Rules:    Cline auto-detects `AGENTS.md` — no wrapper file needed.
- */
-export function formatClineCommand(meta) {
-    const body = transformToHyphenCommands(meta.body);
-    const skillName = `opsx-${meta.id}`;
-    return `---
-name: ${escapeYamlValue(skillName)}
-description: ${escapeYamlValue(meta.description)}
----
-
-${body}
-`;
-}
-export function getClineCommandPath(id) {
-    return join(".cline", "skills", `opsx-${id}`, "SKILL.md");
-}
-export function hasCline(projectRoot) {
-    return (existsSync(join(projectRoot, ".cline")) ||
-        existsSync(join(projectRoot, ".clinerules")));
-}
-/**
- * Read an MCP config file with a top-level `mcpServers` map, or null if
- * missing/unparseable. Preserves unknown top-level fields.
- */
-export function readMcpServersFile(configPath) {
-    if (!existsSync(configPath))
-        return null;
-    try {
-        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
-        if (raw.mcpServers && typeof raw.mcpServers === "object") {
-            return raw;
-        }
-        raw.mcpServers = {};
-        return raw;
-    }
-    catch {
-        return null;
-    }
-}
-/** Write an MCP config file, creating parent directories if needed. */
-export function writeMcpServersFile(configPath, config) {
-    mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-export function isMcpServerInFile(configPath, serverName) {
-    const config = readMcpServersFile(configPath);
-    if (!config)
-        return false;
-    return config.mcpServers[serverName] !== undefined;
-}
-export function installMcpServerInFile(configPath, serverName, command) {
-    const config = readMcpServersFile(configPath) ?? { mcpServers: {} };
-    config.mcpServers[serverName] = {
-        command: command[0],
-        args: command.slice(1),
-    };
-    writeMcpServersFile(configPath, config);
-}
-export function removeMcpServerFromFile(configPath, serverName) {
-    const config = readMcpServersFile(configPath);
-    if (!config)
-        return;
-    if (config.mcpServers[serverName] === undefined)
-        return;
-    delete config.mcpServers[serverName];
-    writeMcpServersFile(configPath, config);
-}
-/** Path to the project-level MCP config file for Cline. */
-function clineMcpPath(projectRoot) {
-    return join(projectRoot, ".cline", "mcp.json");
-}
-/** Path to the project-level MCP config file for Cursor. */
-function cursorMcpPath(projectRoot) {
-    return join(projectRoot, ".cursor", "mcp.json");
-}
-/** Path to the project-level MCP config file for Oh My Pi. */
-function ompMcpPath(projectRoot) {
-    return join(projectRoot, ".omp", "mcp.json");
-}
-// ─── Cursor adapter (format / paths) ─────────────────────────────────────
-/**
- * Cursor slash commands are plain markdown (no frontmatter); the filename
- * is the command name. `$1` is the change-name argument.
- */
-export function formatCursorCommand(meta) {
-    const body = transformToHyphenCommands(meta.body);
-    return `<!-- Change name: $1 (e.g. /opsx-${meta.id} my-change) -->
-
-${body}
-`;
-}
-export function getCursorCommandPath(id) {
-    return join(".cursor", "commands", `opsx-${id}.md`);
-}
-export function getCursorSkillPath(id) {
-    return join(".cursor", "skills", `opsx-${id}`, "SKILL.md");
-}
-/**
- * Cursor Agent Skill — explicit invocation only (`disable-model-invocation`).
- * No `$1` placeholders (those belong to the slash command file).
- */
-export function formatCursorSkill(meta) {
-    const body = transformToHyphenCommands(meta.body);
-    const skillName = `opsx-${meta.id}`;
-    return `---
-name: ${escapeYamlValue(skillName)}
-description: ${escapeYamlValue(meta.description)}
-disable-model-invocation: true
----
-
-${body}
-`;
-}
-export function hasCursor(projectRoot) {
-    return existsSync(join(projectRoot, ".cursor"));
-}
-// ─── Pi adapter ──────────────────────────────────────────────────────────
-/**
- * Pi stores project resources in `.pi/` (skills/, prompts/, extensions/).
- * Prompt templates are Markdown with optional YAML frontmatter; the
- * filename becomes the slash command name (`opsx-e2e.md` → `/opsx-e2e`),
- * `description` feeds autocomplete, and `argument-hint` shows expected
- * arguments. `$1` / `$ARGUMENTS` placeholders expand at prompt time.
- *
- * Conventions follow the Pi docs (packages/coding-agent/docs):
- *   - Prompts:   `.pi/prompts/*.md`, invoked via `/name`.
- *   - Skills:    `.pi/skills/` (root `.md` files or `SKILL.md` dirs),
- *                invoked via `/skill:name`.
- *   - Rules:     Pi loads `AGENTS.md` (or `CLAUDE.md`) walking up from cwd
- *                natively — no wrapper file needed.
- *   - MCP:       Pi has NO MCP client (built-in tools only). The adapter
- *                still implements the interface with no-ops and declares
- *                `supportsMcp: false` so shared MCP phases skip it.
- */
-export function formatPiCommand(meta) {
-    const body = transformToHyphenCommands(meta.body);
-    return `---
-description: ${escapeYamlValue(meta.description)}
-argument-hint: "<change-name>"
----
-
-${body}
-`;
-}
-export function getPiCommandPath(id) {
-    return join(".pi", "prompts", `opsx-${id}.md`);
-}
-/**
- * True when Pi is in use: a project `.pi/` dir, or a global Pi config dir
- * (`~/.pi/agent/`, created by Pi on first run). The home signal lets
- * `openspec-pw init` detect Pi in a fresh project that has no `.pi/` yet.
- */
-export function hasPi(projectRoot, homeDir = homedir()) {
-    return (existsSync(join(projectRoot, ".pi")) ||
-        existsSync(join(homeDir, ".pi", "agent")));
-}
-// ─── Oh My Pi adapter ────────────────────────────────────────────────────
-/**
- * Oh My Pi (omp) stores project slash commands in `.omp/commands/*.md`
- * (non-recursive scan, project before user). Native commands are parsed
- * with FATAL frontmatter parsing, so the YAML must be valid; `name`
- * overrides the filename and `description` feeds autocomplete. `$1` /
- * `$ARGUMENTS` placeholders expand at prompt time.
- *
- * Conventions follow the omp docs (docs/slash-command-internals.md,
- * docs/mcp-config.md):
- *   - Commands:  `.omp/commands/*.md`, invoked via `/name`.
- *   - MCP:       `.omp/mcp.json` with `{ "mcpServers": { ... } }` — same
- *                shape as Cline/Cursor. omp also inherits `.claude/` /
- *                `.cursor/` / opencode MCP configs when present.
- *   - Rules:     omp reads `AGENTS.md` natively — no wrapper file needed.
- */
-export function formatOmpCommand(meta) {
-    const body = transformToHyphenCommands(meta.body);
-    const cmdName = `opsx-${meta.id}`;
-    return `---
-name: ${escapeYamlValue(cmdName)}
-description: ${escapeYamlValue(meta.description)}
----
-
-${body}
-`;
-}
-export function getOmpCommandPath(id) {
-    return join(".omp", "commands", `opsx-${id}.md`);
-}
-/**
- * True when Oh My Pi is in use: a project `.omp/` dir, or a global omp
- * config dir (`~/.omp/agent/`, created by omp on first run).
- */
-export function hasOmp(projectRoot, homeDir = homedir()) {
-    return (existsSync(join(projectRoot, ".omp")) ||
-        existsSync(join(homeDir, ".omp", "agent")));
-}
-// ─── DeepSeek Harness adapter ────────────────────────────────────────────
-/**
- * DeepSeek Harness (dsh) stores project skills in `.dsh/skills/` — the
- * `project-dsh` local provider root, rank 100 (highest local priority).
- * Skills are directory bundles (`<name>/SKILL.md`) with YAML frontmatter
- * (name + description); the kebab-case name becomes the model-invocable
- * skill name (`opsx-e2e`).
- *
- * Conventions follow the dsh skills subsystem (docs/subsystems/skills.md):
- *   - Skills:   `.dsh/skills/<name>/SKILL.md`, invoked via the `skill` tool.
- *   - Rules:    dsh reads `AGENTS.md` / `CLAUDE.md` natively (default
- *               instructionFileCandidates) — no wrapper file needed.
- *   - MCP:      dsh configures MCP via `cordis.yml` plugin config
- *               (@deepseek-ai/dsh-mcp-client), not a simple mcpServers file —
- *               the adapter declares `supportsMcp: false` so shared MCP phases
- *               skip it (configure Playwright MCP manually in cordis.yml).
- *   - Detected via `.dsh/` or the global `~/.dsh/` (DSH_HOME).
- */
-export function formatDshCommand(meta) {
-    const body = transformToHyphenCommands(meta.body);
-    const skillName = `opsx-${meta.id}`;
-    return `---
-name: ${escapeYamlValue(skillName)}
-description: ${escapeYamlValue(meta.description)}
----
-
-${body}
-`;
-}
-export function getDshCommandPath(id) {
-    return join(".dsh", "skills", `opsx-${id}`, "SKILL.md");
-}
-/**
- * True when DeepSeek Harness is in use: a project `.dsh/` dir, or the global
- * dsh home (`~/.dsh/`, DSH_HOME). The home signal lets `openspec-pw init`
- * detect dsh in a fresh project that has no `.dsh/` yet.
- */
-export function hasDsh(projectRoot, homeDir = homedir()) {
-    return (existsSync(join(projectRoot, ".dsh")) ||
-        existsSync(join(homeDir, ".dsh")));
-}
-// ─── Registry ────────────────────────────────────────────────────────────
-const ADAPTERS = [
-// Adapters are registered after const declarations at the bottom of this file.
-];
-// ─── Tool selection (--tools flag) ───────────────────────────────────────
-/** Aliases accepted by `--tools` in addition to canonical EditorIds. */
-const TOOL_ID_ALIASES = {
-    "oh-my-pi": "omp",
-};
-const RESERVED_TOOLS = new Set(["all", "none"]);
-/**
- * Parse the `--tools` flag value for `openspec-pw init`.
- *
- * Returns the selected editor ids, or `null` when the flag was not provided.
- * Mirrors the upstream OpenSpec `openspec init --tools` semantics:
- *   - "all" → every registered editor
- *   - "none" → no editors
- *   - comma-separated ids, case-insensitive; "oh-my-pi" aliases "omp"
- *   - mixing "all"/"none" with specific ids, or unknown ids, throw
- *   - duplicate ids are deduplicated preserving first-occurrence order
- */
-export function resolveToolsArg(toolsArg) {
-    if (typeof toolsArg === "undefined")
-        return null;
-    const raw = toolsArg.trim();
-    if (raw.length === 0) {
-        throw new Error('The --tools option requires a value. Use "all", "none", or a comma-separated list of editor ids.');
-    }
-    const editorIds = ADAPTERS.map((a) => a.id);
-    const availableList = ["all", "none", ...editorIds].join(", ");
-    const lowerRaw = raw.toLowerCase();
-    if (lowerRaw === "all")
-        return [...editorIds];
-    if (lowerRaw === "none")
-        return [];
-    const tokens = raw
-        .split(",")
-        .map((t) => t.trim())
-        .filter((t) => t.length > 0);
-    if (tokens.length === 0) {
-        throw new Error('The --tools option requires at least one editor id when not using "all" or "none".');
-    }
-    const normalized = tokens.map((t) => {
-        const lower = t.toLowerCase();
-        return TOOL_ID_ALIASES[lower] ?? lower;
-    });
-    if (normalized.some((t) => RESERVED_TOOLS.has(t))) {
-        throw new Error('Cannot combine reserved values "all" or "none" with specific editor ids.');
-    }
-    const invalid = normalized.filter((t) => !editorIds.includes(t));
-    if (invalid.length > 0) {
-        throw new Error(`Invalid tool id(s): ${invalid.join(", ")}. Available values: ${availableList}`);
-    }
-    // Deduplicate while preserving order
-    const deduped = [];
-    for (const id of normalized) {
-        const editorId = id;
-        if (!deduped.includes(editorId))
-            deduped.push(editorId);
-    }
-    return deduped;
-}
-export function getAdapter(id) {
-    return ADAPTERS.find((a) => a.id === id);
-}
-/** All registered editors, regardless of detection. */
-export function getAllAdapters() {
-    return [...ADAPTERS];
-}
-export function detectAdapters(projectRoot, homeDir) {
-    return ADAPTERS.filter((a) => a.detect(projectRoot, homeDir));
-}
-function registerAdapter(adapter) {
-    ADAPTERS.push(adapter);
-}
-/** Slash-command hint for user-facing messages. */
-export function slashCommandForAdapter(adapter) {
-    return adapter.id === "claude" ? "/opsx:e2e" : "/opsx-e2e";
-}
-/** Relative paths installCommand writes for this adapter + meta. */
-export function listCommandArtifactPaths(adapter, meta) {
-    const paths = [adapter.commandFilePath(meta.id)];
-    for (const extra of adapter.extraArtifacts?.(meta) ?? []) {
-        paths.push(extra.relativePath);
-    }
-    return paths;
-}
-// ─── Install helpers ─────────────────────────────────────────────────────
-/** Install the command file (and optional extraArtifacts) for one adapter. */
-export function installCommand(adapter, meta, projectRoot) {
-    const relPath = adapter.commandFilePath(meta.id);
-    const absPath = pathResolve(projectRoot, relPath);
-    mkdirSync(dirname(absPath), { recursive: true });
-    writeFileSync(absPath, adapter.formatCommand(meta));
-    console.log(chalk.green(`  ✓ ${adapter.label}: ${relPath}`));
-    for (const extra of adapter.extraArtifacts?.(meta) ?? []) {
-        const extraAbs = pathResolve(projectRoot, extra.relativePath);
-        mkdirSync(dirname(extraAbs), { recursive: true });
-        writeFileSync(extraAbs, extra.contents);
-        console.log(chalk.green(`  ✓ ${adapter.label}: ${extra.relativePath}`));
-    }
-}
-// ─── Project rules file (CLAUDE.md / AGENTS.md) ──────────────────────────
-/**
- * Read the OPENSPEC marker block from a rules file, or `null` when the file
- * is missing / has no markers. Used by drift detection and update to decide
- * whether a rules file needs rewriting.
- */
-export function readOpenSpecBlock(projectRoot, adapter) {
-    const dest = adapter.projectRulesPath(projectRoot);
-    if (!existsSync(dest))
-        return null;
-    const content = readFileSync(dest, "utf-8");
-    const startIdx = content.indexOf("<!-- OPENSPEC:START -->");
-    const endIdx = content.indexOf("<!-- OPENSPEC:END -->");
-    if (startIdx === -1 || endIdx === -1)
-        return null;
-    return content.slice(startIdx + "<!-- OPENSPEC:START -->".length, endIdx).trim();
-}
-/**
- * Whether a rules file's OPENSPEC block matches the expected content.
- * A missing file or absent/truncated markers counts as "does not match"
- * (the caller will rewrite it), which keeps update idempotent but safe.
- */
-export function blockMatchesExpected(projectRoot, adapter, expected) {
-    const block = readOpenSpecBlock(projectRoot, adapter);
-    if (block === null)
-        return false;
-    return block === expected.trim();
-}
-/**
- * Install employee-grade standards into the editor's rules file
- * (CLAUDE.md for Claude, AGENTS.md for OpenCode, Cline, and Cursor). Wraps content in
- * `<!-- OPENSPEC:START -->` / `<!-- OPENSPEC:END -->` markers so future
- * updates can replace the block without touching the rest of the file.
- */
-export function installOpenSpecBlock(projectRoot, standardsContent, adapter = claudeAdapter) {
-    const dest = adapter.projectRulesPath(projectRoot);
-    const fileLabel = basename(dest);
-    const markerStart = "<!-- OPENSPEC:START -->";
-    const markerEnd = "<!-- OPENSPEC:END -->";
-    if (!existsSync(dest)) {
-        const projName = projectRoot.split("/").pop() ?? "Project";
-        const content = `# ${projName}\n\n${markerStart}\n\n${standardsContent.trim()}\n\n${markerEnd}\n`;
-        writeFileSync(dest, content);
-        console.log(chalk.green(`  ✓ ${fileLabel}: created with employee-grade standards`));
-        return;
-    }
-    const existing = readFileSync(dest, "utf-8");
-    const hasStart = existing.includes(markerStart);
-    const hasEnd = existing.includes(markerEnd);
-    if (hasStart && hasEnd) {
-        const startIdx = existing.indexOf(markerStart);
-        const endIdx = existing.indexOf(markerEnd) + markerEnd.length;
-        const before = existing.slice(0, startIdx).trimEnd();
-        const after = existing.slice(endIdx);
-        const updated = before +
-            "\n" +
-            markerStart +
-            "\n\n" +
-            standardsContent.trim() +
-            "\n\n" +
-            markerEnd +
-            after;
-        writeFileSync(dest, updated);
-        console.log(chalk.green(`  ✓ ${fileLabel}: updated employee-grade standards (markers preserved, content refreshed)`));
-    }
-    else if (!hasStart && !hasEnd) {
-        const updated = existing.trim() +
-            "\n\n" +
-            markerStart +
-            "\n\n" +
-            standardsContent.trim() +
-            "\n\n" +
-            markerEnd +
-            "\n";
-        writeFileSync(dest, updated);
-        console.log(chalk.green(`  ✓ ${fileLabel}: appended employee-grade standards with markers`));
-    }
-    else {
-        // Incomplete markers (only START, or only END) — corrupted tool territory.
-        // Keep everything before the first marker (user content), discard the
-        // truncated tool output after it, and write a clean complete block so
-        // `doctor`/`update` converge instead of dead-ending on a skipped file.
-        const firstIdx = hasStart
-            ? existing.indexOf(markerStart)
-            : existing.indexOf(markerEnd);
-        const header = existing.slice(0, firstIdx).trimEnd();
-        const updated = header +
-            "\n\n" +
-            markerStart +
-            "\n\n" +
-            standardsContent.trim() +
-            "\n\n" +
-            markerEnd +
-            "\n";
-        writeFileSync(dest, updated);
-        console.log(chalk.green(`  ✓ ${fileLabel}: repaired incomplete OPENSPEC markers with employee-grade standards`));
-    }
-}
-/**
- * CodeGraph-first guidance prepended to the Claude wrapper so the model sees
- * it in the main rules file instead of relying on the AGENTS.md import
- * (imported content ranks lower and is treated as optional by the model).
- */
-const CODE_GRAPH_FIRST_BLOCK = `## CodeGraph 优先 🔴
-
-有 \`.codegraph/\` 时：结构性任务（定义/调用链/影响面/流程）默认第一步用 \`codegraph_explore\`，直接用结果回答，别先 grep/read（仅字面文本、已打开文件、结果不足时补查）。不派子 agent 重建索引。无 \`.codegraph/\` 跳过。`;
-/**
- * The expected OPENSPEC block content for a thin CLAUDE.md wrapper
- * (CodeGraph-first guidance + workflow hint + `@AGENTS.md` import). Exported
- * so drift detection / update can compare against it.
- *
- * The `@AGENTS.md` line is Claude Code's documented way to reuse AGENTS.md
- * inside CLAUDE.md — AGENTS.md is NOT read by default ("Claude Code reads
- * CLAUDE.md, not AGENTS.md"). Contract per
- * https://code.claude.com/docs/en/memory.md:
- * - Position is irrelevant — the doc says "@ ... anywhere in your CLAUDE.md"
- *   (examples even inline it mid-sentence or in a list item). The one real
- *   constraint: the `@` line must NOT sit inside a code span (backticks) or
- *   a fenced code block — the resolver skips those. This wrapper keeps the
- *   import at the end of the block as a bare line.
- * - The path resolves relative to the importing CLAUDE.md; import recursion
- *   is capped at 4 hops.
- * - Block-level HTML comments (`<!-- ... -->`) are stripped before context
- *   injection, so the OPENSPEC markers vanish while the live `@AGENTS.md`
- *   line inside them is still honored.
- */
-export function claudeWrapperStandardsContent() {
-    return `${CODE_GRAPH_FIRST_BLOCK}\n\n**工作流**：优先使用 OpenSpec 工作流（/opsx 命令），而非 plan mode。\n\n@AGENTS.md\n`;
-}
-/**
- * Install a thin CLAUDE.md that imports AGENTS.md.
- *
- * Uses the same OPENSPEC:START/END markers as the full standards block so
- * `cleanProjectRules` can remove it uniformly. The CodeGraph-first block is
- * written directly into CLAUDE.md (before the @AGENTS.md import) so Claude
- * Code picks it up without depending on the import.
- *
- * Also handles migration: if CLAUDE.md has an existing OPENSPEC:START block
- * (old format that wrote standards directly to CLAUDE.md), calling
- * `installOpenSpecBlock` replaces the content with the CodeGraph block +
- * `@AGENTS.md` import.
- */
-export function installClaudeWrapper(projectRoot) {
-    const dest = join(projectRoot, "CLAUDE.md");
-    // CLAUDE.md symlinked (typically → AGENTS.md, the officially documented
-    // reuse pattern): AGENTS.md itself is what Claude Code reads, and
-    // installProjectRules already keeps the full standards in it. Writing a
-    // wrapper here would overwrite them through the symlink (and the wrapper's
-    // @AGENTS.md import would self-reference). Skip instead.
-    if (existsSync(dest)) {
-        if (lstatSync(dest).isSymbolicLink()) {
-            console.log(chalk.gray("  - CLAUDE.md is a symlink to AGENTS.md — standards live there, no wrapper needed"));
-            return;
-        }
-    }
-    // No-op if our full wrapper (CodeGraph block + @AGENTS.md import) is already
-    // in place — content-equal, so a user edit inside the markers is detected.
-    // A bare @AGENTS.md without our markers (added by openspec CLI or the user)
-    // is left untouched — but tell the user CodeGraph-first won't be written.
-    if (existsSync(dest)) {
-        const existing = readFileSync(dest, "utf-8");
-        const hasMarkers = existing.includes("<!-- OPENSPEC:START -->");
-        if (!hasMarkers && /^@AGENTS\.md\r?$/m.test(existing)) {
-            console.log(chalk.yellow("  ⚠ CLAUDE.md 是裸 @AGENTS.md 导入（无 OPENSPEC 标记），CodeGraph 优先约束未写入。如需启用：删除该行后重跑 openspec-pw update。"));
-            return;
-        }
-        if (hasMarkers && blockMatchesExpected(projectRoot, claudeAdapter, claudeWrapperStandardsContent())) {
-            return;
-        }
-    }
-    // Delegate to installOpenSpecBlock which handles create/update/append
-    // with OPENSPEC:START/END markers.
-    installOpenSpecBlock(projectRoot, claudeWrapperStandardsContent(), claudeAdapter);
-}
-/**
- * Route employee-grade standards into project rules files.
- *
- * AGENTS.md is always the single source of truth, regardless of which
- * editors are detected. If Claude is in use, a thin CLAUDE.md wrapper
- * with `@AGENTS.md` import is created so Claude loads AGENTS.md as
- * its project rules. Cline and Cursor auto-detect AGENTS.md natively — no
- * wrapper needed.
- */
-export function installProjectRules(projectRoot, standardsContent, detected) {
-    if (detected.length === 0)
-        return;
-    // AGENTS.md is always the single source of truth
-    installOpenSpecBlock(projectRoot, standardsContent, opencodeAdapter);
-    // Thin CLAUDE.md with @AGENTS.md import if Claude is in use
-    if (detected.some((a) => a.id === "claude")) {
-        installClaudeWrapper(projectRoot);
-    }
-    // Register AGENTS.md in opencode.json for OpenCode
-    if (detected.some((a) => a.id === "opencode") && opencodeAdapter.registerInstructions) {
-        const existing = readOpenCodeInstructions(projectRoot);
-        const next = Array.from(new Set([...(existing ?? []), "AGENTS.md"]));
-        opencodeAdapter.registerInstructions(projectRoot, next);
-    }
-}
-/** Remove all OpenSpec marker blocks from AGENTS.md (always) and CLAUDE.md (for claude adapter). */
-export function cleanProjectRules(adapter, projectRoot) {
-    // AGENTS.md always has the employee standards (SSOT)
-    removeMarkersFromFile(join(projectRoot, "AGENTS.md"), "AGENTS.md");
-    // CLAUDE.md may have the wrapper import if Claude is detected
-    if (adapter.id === "claude") {
-        removeMarkersFromFile(adapter.projectRulesPath(projectRoot), basename(adapter.projectRulesPath(projectRoot)));
-    }
-}
-/** Remove OpenSpec marker blocks from a single file. Only edits within markers. */
-function removeMarkersFromFile(dest, fileLabel) {
-    if (!existsSync(dest)) {
-        console.log(chalk.gray(`  - ${fileLabel} not found, skipping`));
-        return;
-    }
-    const existing = readFileSync(dest, "utf-8");
-    if (!existing.includes("<!-- OPENSPEC:START -->")) {
-        console.log(chalk.gray(`  - No OpenSpec markers found in ${fileLabel}`));
-        return;
-    }
-    // Remove markers and their content, consuming surrounding whitespace.
-    // Then collapse runs of 3+ blank lines to at most 2 for a clean result.
-    let updated = existing.replace(/\s*<!-- OPENSPEC:START -->[\s\S]*?<!-- OPENSPEC:END -->\s*/g, "\n\n").replace(/\n{3,}/g, "\n\n").trim();
-    // Delete empty file rather than leaving a ghost.
-    if (updated === "") {
-        rmSync(dest);
-        console.log(chalk.green(`  ✓ Removed empty ${fileLabel}`));
-        return;
-    }
-    writeFileSync(dest, updated + "\n");
-    console.log(chalk.green(`  ✓ Removed OpenSpec markers from ${fileLabel}`));
-}
-/** Read the employee-grade standards source file (empty string if missing). */
-export function readEmployeeStandards(srcPath) {
-    return existsSync(srcPath) ? readFileSync(srcPath, "utf-8") : "";
-}
-// ─── Adapter instances (registered after helpers above are defined) ──────
-//
-// We declare them here (not at the top) so they can reference the helper
-// functions defined in this same module. JS hoisting covers `function`
-// declarations; `const` arrows don't get hoisted, so the order matters.
-export const claudeAdapter = defineAdapter({
-    id: "claude",
-    label: "claude",
-    displayName: "Claude Code",
-    detect: hasClaudeCode,
-    commandFilePath: getClaudeCommandPath,
-    formatCommand: formatClaudeCommand,
-    // Claude Code reads CLAUDE.md directly — override the AGENTS.md default.
-    projectRulesPath: (root) => join(root, "CLAUDE.md"),
-    isMcpInstalled(root, serverName) {
-        // Project scope: Playwright MCP lives in the project-root .mcp.json.
-        // Read the file directly instead of `claude mcp list` — zero CLI
-        // dependency, testable, and never confuses a global user-scope entry
-        // with a project-scoped one.
-        try {
-            const mcpJson = readFileSync(join(root, ".mcp.json"), "utf-8");
-            const parsed = JSON.parse(mcpJson);
-            return (typeof parsed === "object" &&
-                parsed !== null &&
-                typeof parsed.mcpServers === "object" &&
-                parsed.mcpServers !== null &&
-                Object.hasOwn(parsed.mcpServers, serverName));
-        }
-        catch {
-            // Missing or unparseable file — server not installed
-            return false;
-        }
-    },
-    installMcp(_root, serverName, command) {
-        execFileSync("claude", ["mcp", "add", "--scope", "project", serverName, ...command], {
-            encoding: "utf-8",
-            timeout: TIMEOUT.MCP_LIST,
-            stdio: ["pipe", "pipe", "pipe"],
-            shell: needsShell,
-        });
-    },
-    removeMcp(_root, serverName) {
-        execFileSync("claude", ["mcp", "remove", "--scope", "project", serverName], {
-            encoding: "utf-8",
-            timeout: TIMEOUT.MCP_LIST,
-            stdio: ["pipe", "pipe", "pipe"],
-            shell: needsShell,
-        });
-    },
-});
-export const opencodeAdapter = defineAdapter({
-    id: "opencode",
-    label: "opencode",
-    displayName: "OpenCode",
-    detect: hasOpenCode,
-    commandFilePath: getOpenCodeCommandPath,
-    formatCommand: formatOpenCodeCommand,
-    // AGENTS.md is the default; not declared explicitly.
-    isMcpInstalled(projectRoot, serverName) {
-        const config = findOpenCodeConfig(projectRoot);
-        if (!config)
-            return false;
-        const value = readOpenCodeValue(config.text, ["mcp", serverName]);
-        return value !== undefined;
-    },
-    installMcp(projectRoot, serverName, command) {
-        setOpenCodeValue(projectRoot, ["mcp", serverName], {
-            type: "local",
-            command,
-        });
-    },
-    removeMcp(projectRoot, serverName) {
-        // Read current mcp map, rebuild without this server, write back
-        const config = findOpenCodeConfig(projectRoot);
-        if (!config)
-            return;
-        const value = readOpenCodeValue(config.text, ["mcp", serverName]);
-        if (value === undefined)
-            return;
-        const current = readOpenCodeValue(config.text, ["mcp"]);
-        if (current && typeof current === "object") {
-            const next = { ...current };
-            delete next[serverName];
-            setOpenCodeValue(projectRoot, ["mcp"], next);
-        }
-    },
-    registerInstructions(projectRoot, instructions) {
-        setOpenCodeValue(projectRoot, ["instructions"], instructions);
-    },
-});
-export const clineAdapter = defineAdapter({
-    id: "cline",
-    label: "cline",
-    displayName: "Cline",
-    detect: hasCline,
-    commandFilePath: getClineCommandPath,
-    formatCommand: formatClineCommand,
-    // Cline auto-detects AGENTS.md — that's the default.
-    isMcpInstalled(projectRoot, serverName) {
-        return isMcpServerInFile(clineMcpPath(projectRoot), serverName);
-    },
-    installMcp(projectRoot, serverName, command) {
-        installMcpServerInFile(clineMcpPath(projectRoot), serverName, command);
-    },
-    removeMcp(projectRoot, serverName) {
-        removeMcpServerFromFile(clineMcpPath(projectRoot), serverName);
-    },
-});
-export const cursorAdapter = defineAdapter({
-    id: "cursor",
-    label: "cursor",
-    displayName: "Cursor",
-    detect: hasCursor,
-    commandFilePath: getCursorCommandPath,
-    formatCommand: formatCursorCommand,
-    // Cursor auto-detects AGENTS.md — that's the default.
-    isMcpInstalled(projectRoot, serverName) {
-        return isMcpServerInFile(cursorMcpPath(projectRoot), serverName);
-    },
-    installMcp(projectRoot, serverName, command) {
-        installMcpServerInFile(cursorMcpPath(projectRoot), serverName, command);
-    },
-    removeMcp(projectRoot, serverName) {
-        removeMcpServerFromFile(cursorMcpPath(projectRoot), serverName);
-    },
-    extraArtifacts(meta) {
-        return [
-            {
-                relativePath: getCursorSkillPath(meta.id),
-                contents: formatCursorSkill(meta),
-            },
-        ];
-    },
-});
-export const piAdapter = defineAdapter({
-    id: "pi",
-    label: "pi",
-    displayName: "Pi",
-    detect: hasPi,
-    // Pi has no MCP client — shared MCP phases skip this adapter.
-    supportsMcp: false,
-    commandFilePath: getPiCommandPath,
-    formatCommand: formatPiCommand,
-    // Pi loads AGENTS.md natively (walking up from cwd) — that's the default.
-});
-export const ompAdapter = defineAdapter({
-    id: "omp",
-    label: "omp",
-    displayName: "Oh My Pi",
-    detect: hasOmp,
-    commandFilePath: getOmpCommandPath,
-    formatCommand: formatOmpCommand,
-    // omp reads AGENTS.md natively — that's the default.
-    isMcpInstalled(projectRoot, serverName) {
-        return isMcpServerInFile(ompMcpPath(projectRoot), serverName);
-    },
-    installMcp(projectRoot, serverName, command) {
-        installMcpServerInFile(ompMcpPath(projectRoot), serverName, command);
-    },
-    removeMcp(projectRoot, serverName) {
-        removeMcpServerFromFile(ompMcpPath(projectRoot), serverName);
-    },
-});
-export const dshAdapter = defineAdapter({
-    id: "dsh",
-    label: "dsh",
-    displayName: "DeepSeek Harness",
-    detect: hasDsh,
-    // dsh configures MCP via cordis.yml plugin config, not a simple file —
-    // shared MCP phases skip this adapter (configure Playwright MCP manually).
-    supportsMcp: false,
-    commandFilePath: getDshCommandPath,
-    formatCommand: formatDshCommand,
-    // dsh reads AGENTS.md natively — that's the default.
-});
-// Register the adapters now that the const arrows exist
-registerAdapter(claudeAdapter);
-registerAdapter(opencodeAdapter);
-registerAdapter(clineAdapter);
-registerAdapter(cursorAdapter);
-registerAdapter(piAdapter);
-registerAdapter(ompAdapter);
-registerAdapter(dshAdapter);
+ * ─────────────────────────────────────────────────────────────────────────
+ *  FACADE FILE — implementation lives in ./editors/*
+ * ─────────────────────────────────────────────────────────────────────────
+ * This file only re-exports the public API of the editor adapter layer so
+ * every existing `import ... from ".../editors.js"` keeps working.
+ *
+ * Why a facade instead of letting callers import "./editors/index.js"?
+ * Node ESM and TypeScript nodenext do NOT resolve directory indexes:
+ * `"./editors.js"` with only `editors/index.ts` on disk fails (TS2307).
+ * Keeping this thin file preserves zero-churn imports for all callers.
+ *
+ * Do NOT add logic here. Add implementations under ./editors/ and
+ * re-export below.
+ *
+ * Re-export order matters for adapter self-registration: importing the
+ * adapter modules loads them, and each calls `registerAdapter()` — the
+ * order below fixes ADAPTERS registration order (claude → opencode →
+ * cline → cursor → pi → omp → dsh), which `resolveToolsArg("all")`, the
+ * interactive prompt order, and tests/editors-tools.test.ts depend on.
+ */
+// Types & factory (zero internal deps)
+export { buildCommandMeta, defineAdapter, } from "./editors/types.js";
+// Cross-editor shared helpers
+export { escapeYamlValue, formatTagsArray, transformToHyphenCommands, readMcpServersFile, writeMcpServersFile, isMcpServerInFile, installMcpServerInFile, removeMcpServerFromFile, } from "./editors/shared.js";
+// Registry (lookup / detection / install helpers) — no adapter imports here
+export { registerAdapter, getAdapter, getAllAdapters, detectAdapters, slashCommandForAdapter, listCommandArtifactPaths, installCommand, } from "./editors/registry.js";
+// Adapters — import order = registration order (do not reorder)
+export { formatClaudeCommand, getClaudeCommandPath, hasClaudeCode, claudeAdapter, } from "./editors/adapters/claude.js";
+export { formatOpenCodeCommand, getOpenCodeCommandPath, hasOpenCode, opencodeAdapter, readOpenCodeInstructions, } from "./editors/adapters/opencode.js";
+export { formatClineCommand, getClineCommandPath, hasCline, clineAdapter, } from "./editors/adapters/cline.js";
+export { formatCursorCommand, getCursorCommandPath, getCursorSkillPath, formatCursorSkill, hasCursor, cursorAdapter, } from "./editors/adapters/cursor.js";
+export { formatPiCommand, getPiCommandPath, hasPi, piAdapter, } from "./editors/adapters/pi.js";
+export { formatOmpCommand, getOmpCommandPath, hasOmp, ompAdapter, } from "./editors/adapters/omp.js";
+export { formatDshCommand, getDshCommandPath, hasDsh, dshAdapter, } from "./editors/adapters/dsh.js";
+// Tool selection (--tools flag parsing)
+export { resolveToolsArg } from "./editors/tool-selection.js";
+// Project rules file management (AGENTS.md SSOT + CLAUDE.md wrapper)
+export { readOpenSpecBlock, blockMatchesExpected, installOpenSpecBlock, claudeWrapperStandardsContent, installClaudeWrapper, installProjectRules, cleanProjectRules, readEmployeeStandards, } from "./editors/project-rules.js";
 //# sourceMappingURL=editors.js.map