@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/plugins/skills.d.ts

@@ -1,13 +1,4 @@
-/**
- * Skill management -- discovery, installation, and syncing of SKILL.md bundles.
- *
- * Skills are knowledge packs stored in ~/.agents/skills/. Each skill directory
- * contains a SKILL.md (with frontmatter metadata) and optional supporting files
- * (rules/, examples/, etc.). This module handles parsing skill metadata,
- * installing skills into agent version homes, and tracking installation state.
- */
 import type { AgentId, SkillMetadata, InstalledSkill } from '../types.js';
-/** User-scoped skills dir (~/.agents/skills/). Used for installs. */
 export declare function getSkillsDir(): string;
 export declare function ensureCentralSkillsDir(): void;
 export declare function getAgentSkillsDir(agentId: AgentId): string;
@@ -28,20 +19,9 @@ export interface SkillParseResult {
     metadata: SkillMetadata | null;
     error?: string;
 }
-/**
- * Parse skill metadata from SKILL.md, returning both result and any error.
- */
 export declare function tryParseSkillMetadata(skillDir: string): SkillParseResult;
-/**
- * Parse skill metadata from SKILL.md (backward-compatible, returns null on error).
- */
 export declare function parseSkillMetadata(skillDir: string): SkillMetadata | null;
 export declare function countSkillRules(skillDir: string): number;
-/**
- * Count bundled resource files in a skill directory: every regular file
- * beyond SKILL.md itself (reference docs, scripts, assets, etc). Hidden
- * files and hidden directories are skipped.
- */
 export declare function countSkillFiles(skillDir: string): number;
 export interface DiscoveredSkill {
     name: string;
@@ -50,11 +30,6 @@ export interface DiscoveredSkill {
     ruleCount: number;
     validation: ValidationResult;
     parseError?: string;
-    /**
-     * Which repo the skill was discovered in. `undefined` means the primary
-     * ~/.agents/ repo; otherwise the alias of an extra repo registered via
-     * `agents repo add`. Primary wins on name collisions.
-     */
     source?: string;
 }
 export declare function discoverSkillsFromRepo(repoPath: string): DiscoveredSkill[];
@@ -63,51 +38,12 @@ export declare function installSkill(sourcePath: string, skillName: string, agen
     error?: string;
     warnings?: string[];
 };
-/**
- * Check if a skill exists for an agent.
- */
 export declare function skillExists(agentId: AgentId, skillName: string): boolean;
-/**
- * Check if installed skill content matches source content.
- * Compares SKILL.md and all rules/*.md files.
- */
 export declare function skillContentMatches(agentId: AgentId, skillName: string, sourcePath: string): boolean;
-/**
- * List skill names from user (~/.agents/skills/) and system (~/.agents/.system/skills/) dirs.
- * User dir takes priority; deduplication preserves first occurrence.
- */
 export declare function listCentralSkills(): string[];
-/**
- * Resolve a skill name to its source directory. Searches user dir first,
- * then system dir, then extra repos, then plugin-bundled skills
- * (`plugins/<plugin>/skills/<name>` under any trusted base). Returns null if no
- * source has a SKILL.md.
- *
- * Crediting plugins here is load-bearing (PHNX-3185): a skill materialized from
- * `plugins/design/skills/design` has a real source, so it must resolve — else
- * `versionSkillMatches` finds no source and the skill reads as drifted, and
- * {@link diffVersionSkills} classes it an orphan `prune cleanup` would delete.
- */
 export declare function resolveSkillSourcePath(skillName: string): string | null;
-/**
- * Union of skill names available across the primary and all enabled extras.
- * Primary wins on name collision.
- */
 export declare function listAllSkills(): string[];
-/**
- * Path to the skills dir of a specific version home (not the active one).
- */
 export declare function getVersionSkillsDir(agent: AgentId, version: string): string;
-/**
- * List real skill names installed in a specific version home.
- *
- * Command-as-skill WRAPPERS (a `skills/<name>/SKILL.md` carrying the
- * `agents_command` marker — how command-runtime agents like Codex/Kimi install
- * commands) are excluded: they are commands, reconciled by the commands diff
- * against the command source, not skills. Counting them here made the skill
- * orphan/extra detectors flag every command wrapper (tickets, prune, swarm-plan,
- * …) as an unmanaged skill — a false positive that `prune cleanup` would delete.
- */
 export declare function listSkillsInVersionHome(agent: AgentId, version: string): string[];
 export interface VersionSkillDiff {
     agent: AgentId;
@@ -117,33 +53,15 @@ export interface VersionSkillDiff {
     matched: string[];
     orphans: string[];
 }
-/**
- * Compare a version home's skills against central. Returns the reconciliation diff.
- */
 export declare function diffVersionSkills(agent: AgentId, version: string): VersionSkillDiff;
-/**
- * Install a single skill from central into a specific version home.
- *
- * Copy mode preserves any files that exist in the version home but NOT in
- * central — e.g. user-populated `.env` alongside the git-tracked `.env.example`.
- * Without this, re-running `sync` whenever central content changes would wipe
- * local secrets.
- */
 export declare function installSkillToVersion(agent: AgentId, version: string, skillName: string, method?: 'symlink' | 'copy'): {
     success: boolean;
     error?: string;
 };
-/**
- * Remove a single skill from a specific version home.
- */
 export declare function removeSkillFromVersion(agent: AgentId, version: string, skillName: string): {
     success: boolean;
     error?: string;
 };
-/**
- * Iterate all (agent, version) pairs that support skills and are installed,
- * optionally scoped to a single agent/version.
- */
 export declare function iterSkillsCapableVersions(filter?: {
     agent?: AgentId;
     version?: string;
@@ -162,10 +80,6 @@ export declare function listInstalledSkillsWithScope(agentId: AgentId, cwd?: str
 }): InstalledSkill[];
 export declare function getSkillInfo(skillName: string): DiscoveredSkill | null;
 export declare function getSkillRules(skillName: string): string[];
-/**
- * Install a skill to central ~/.agents/skills/ directory only.
- * Does not create per-agent symlinks (shims handle that for synced agents).
- */
 export declare function installSkillCentrally(sourcePath: string, skillName: string): {
     success: boolean;
     error?: string;

package/dist/lib/plugins/skills.js

@@ -1,11 +1,3 @@
-/**
- * Skill management -- discovery, installation, and syncing of SKILL.md bundles.
- *
- * Skills are knowledge packs stored in ~/.agents/skills/. Each skill directory
- * contains a SKILL.md (with frontmatter metadata) and optional supporting files
- * (rules/, examples/, etc.). This module handles parsing skill metadata,
- * installing skills into agent version homes, and tracking installation state.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -19,7 +11,6 @@ import { listCommandSkillsInVersion } from '../command-skills.js';
 import { pluginSkillDirs, listPluginSkillNames } from '../staleness/writers/sources.js';
 import { emit } from '../feed/events.js';
 const HOME = os.homedir();
-/** User-scoped skills dir (~/.agents/skills/). Used for installs. */
 export function getSkillsDir() {
     return getUserSkillsDir();
 }
@@ -40,7 +31,6 @@ export function getProjectSkillsDir(agentId, cwd = process.cwd()) {
         dirs.push(path.join(projectAgentsDir, 'skills'));
     }
     dirs.push(path.join(cwd, `.${agentId}`, 'skills'));
-    // Return the first existing dir, otherwise default to the first candidate
     for (const dir of dirs) {
         if (fs.existsSync(dir))
             return dir;
@@ -54,7 +44,6 @@ export function validateSkillMetadata(metadata, skillName) {
         errors.push('SKILL.md not found or has no valid frontmatter');
         return { valid: false, errors, warnings };
     }
-    // name is required
     if (!metadata.name || metadata.name.trim() === '') {
         errors.push('Missing required field: name');
     }
@@ -66,7 +55,6 @@ export function validateSkillMetadata(metadata, skillName) {
             warnings.push('name should be lowercase with hyphens (e.g., my-skill-name)');
         }
     }
-    // description is required
     if (!metadata.description || metadata.description.trim() === '') {
         errors.push('Missing required field: description');
     }
@@ -75,9 +63,6 @@ export function validateSkillMetadata(metadata, skillName) {
     }
     return { valid: errors.length === 0, errors, warnings };
 }
-/**
- * Parse skill metadata from SKILL.md, returning both result and any error.
- */
 export function tryParseSkillMetadata(skillDir) {
     const skillMdPath = path.join(skillDir, 'SKILL.md');
     if (!fs.existsSync(skillMdPath)) {
@@ -86,7 +71,6 @@ export function tryParseSkillMetadata(skillDir) {
     try {
         const content = fs.readFileSync(skillMdPath, 'utf-8');
         const lines = content.split('\n');
-        // Check for YAML frontmatter (required)
         if (lines[0] === '---') {
             const endIndex = lines.slice(1).findIndex((l) => l === '---');
             if (endIndex > 0) {
@@ -105,7 +89,6 @@ export function tryParseSkillMetadata(skillDir) {
                 };
             }
         }
-        // No valid frontmatter
         return { metadata: null, error: 'No valid YAML frontmatter found' };
     }
     catch (e) {
@@ -113,9 +96,6 @@ export function tryParseSkillMetadata(skillDir) {
         return { metadata: null, error: `Invalid YAML: ${msg}` };
     }
 }
-/**
- * Parse skill metadata from SKILL.md (backward-compatible, returns null on error).
- */
 export function parseSkillMetadata(skillDir) {
     return tryParseSkillMetadata(skillDir).metadata;
 }
@@ -132,11 +112,6 @@ export function countSkillRules(skillDir) {
         return 0;
     }
 }
-/**
- * Count bundled resource files in a skill directory: every regular file
- * beyond SKILL.md itself (reference docs, scripts, assets, etc). Hidden
- * files and hidden directories are skipped.
- */
 export function countSkillFiles(skillDir) {
     if (!fs.existsSync(skillDir))
         return 0;
@@ -168,11 +143,10 @@ export function countSkillFiles(skillDir) {
 }
 export function discoverSkillsFromRepo(repoPath) {
     const skills = [];
-    // Look for skills in common locations
     const searchPaths = [
         path.join(repoPath, 'skills'),
         path.join(repoPath, 'agent-skills'),
-        repoPath, // Root level skill directories
+        repoPath,
     ];
     for (const searchPath of searchPaths) {
         if (!fs.existsSync(searchPath))
@@ -182,7 +156,6 @@ export function discoverSkillsFromRepo(repoPath) {
             for (const entry of entries) {
                 if (!entry.isDirectory())
                     continue;
-                // Skip hidden directories (e.g., .system)
                 if (entry.name.startsWith('.'))
                     continue;
                 const skillDir = path.join(searchPath, entry.name);
@@ -190,7 +163,6 @@ export function discoverSkillsFromRepo(repoPath) {
                 if (fs.existsSync(skillMdPath)) {
                     const parseResult = tryParseSkillMetadata(skillDir);
                     const validation = validateSkillMetadata(parseResult.metadata, entry.name);
-                    // Include even if invalid (for discovery/listing with warnings)
                     skills.push({
                         name: entry.name,
                         path: skillDir,
@@ -203,13 +175,11 @@ export function discoverSkillsFromRepo(repoPath) {
             }
         }
         catch {
-            // Skip inaccessible directories
         }
     }
     return skills;
 }
 export function installSkill(sourcePath, skillName, agents, method = 'symlink') {
-    // Validate skill metadata before installation
     const metadata = parseSkillMetadata(sourcePath);
     const validation = validateSkillMetadata(metadata, skillName);
     if (!validation.valid) {
@@ -221,7 +191,6 @@ export function installSkill(sourcePath, skillName, agents, method = 'symlink')
     }
     ensureCentralSkillsDir();
     const centralPath = path.join(getSkillsDir(), skillName);
-    // Copy to central location if not already there
     if (!fs.existsSync(centralPath)) {
         try {
             fs.cpSync(sourcePath, centralPath, { recursive: true });
@@ -230,20 +199,17 @@ export function installSkill(sourcePath, skillName, agents, method = 'symlink')
             return { success: false, error: `Failed to copy skill: ${err.message}` };
         }
     }
-    // Symlink to each agent
     for (const agentId of agents) {
         if (!isCapable(agentId, 'skills')) {
             continue;
         }
         ensureSkillsDir(agentId);
         const agentSkillPath = path.join(getAgentSkillsDir(agentId), skillName);
-        // Remove existing if present
         if (fs.existsSync(agentSkillPath)) {
             try {
                 fs.rmSync(agentSkillPath, { recursive: true, force: true });
             }
             catch {
-                // Ignore removal errors
             }
         }
         try {
@@ -264,22 +230,13 @@ export function installSkill(sourcePath, skillName, agents, method = 'symlink')
     emit('skill.install', { skill: skillName, agents });
     return { success: true };
 }
-/**
- * Check if a skill exists for an agent.
- */
 export function skillExists(agentId, skillName) {
     const agentSkillPath = path.join(getAgentSkillsDir(agentId), skillName);
     return fs.existsSync(agentSkillPath);
 }
-/**
- * Normalize content for comparison (trim, normalize line endings).
- */
 function normalizeContent(content) {
     return content.replace(/\r\n/g, '\n').trim();
 }
-/**
- * Compare two directories recursively for content equality.
- */
 function directoriesMatch(dir1, dir2) {
     if (!fs.existsSync(dir1) || !fs.existsSync(dir2)) {
         return fs.existsSync(dir1) === fs.existsSync(dir2);
@@ -304,10 +261,6 @@ function directoriesMatch(dir1, dir2) {
         return false;
     }
 }
-/**
- * Check if installed skill content matches source content.
- * Compares SKILL.md and all rules/*.md files.
- */
 export function skillContentMatches(agentId, skillName, sourcePath) {
     const installedPath = path.join(getAgentSkillsDir(agentId), skillName);
     if (!fs.existsSync(installedPath) || !fs.existsSync(sourcePath)) {
@@ -332,10 +285,6 @@ export function skillContentMatches(agentId, skillName, sourcePath) {
         return false;
     }
 }
-/**
- * List skill names from user (~/.agents/skills/) and system (~/.agents/.system/skills/) dirs.
- * User dir takes priority; deduplication preserves first occurrence.
- */
 export function listCentralSkills() {
     const seen = new Set();
     for (const dir of [getUserSkillsDir(), getSystemSkillsDir()]) {
@@ -351,17 +300,6 @@ export function listCentralSkills() {
     }
     return Array.from(seen).sort();
 }
-/**
- * Resolve a skill name to its source directory. Searches user dir first,
- * then system dir, then extra repos, then plugin-bundled skills
- * (`plugins/<plugin>/skills/<name>` under any trusted base). Returns null if no
- * source has a SKILL.md.
- *
- * Crediting plugins here is load-bearing (PHNX-3185): a skill materialized from
- * `plugins/design/skills/design` has a real source, so it must resolve — else
- * `versionSkillMatches` finds no source and the skill reads as drifted, and
- * {@link diffVersionSkills} classes it an orphan `prune cleanup` would delete.
- */
 export function resolveSkillSourcePath(skillName) {
     for (const dir of [getUserSkillsDir(), getSystemSkillsDir()]) {
         const candidate = path.join(dir, skillName);
@@ -380,10 +318,6 @@ export function resolveSkillSourcePath(skillName) {
     }
     return null;
 }
-/**
- * Union of skill names available across the primary and all enabled extras.
- * Primary wins on name collision.
- */
 export function listAllSkills() {
     const seen = new Set(listCentralSkills());
     for (const extra of getEnabledExtraRepos()) {
@@ -400,23 +334,10 @@ export function listAllSkills() {
     }
     return Array.from(seen).sort();
 }
-/**
- * Path to the skills dir of a specific version home (not the active one).
- */
 export function getVersionSkillsDir(agent, version) {
     const home = getVersionHomePath(agent, version);
     return path.join(home, agentConfigDirName(agent), 'skills');
 }
-/**
- * List real skill names installed in a specific version home.
- *
- * Command-as-skill WRAPPERS (a `skills/<name>/SKILL.md` carrying the
- * `agents_command` marker — how command-runtime agents like Codex/Kimi install
- * commands) are excluded: they are commands, reconciled by the commands diff
- * against the command source, not skills. Counting them here made the skill
- * orphan/extra detectors flag every command wrapper (tickets, prune, swarm-plan,
- * …) as an unmanaged skill — a false positive that `prune cleanup` would delete.
- */
 export function listSkillsInVersionHome(agent, version) {
     const dir = getVersionSkillsDir(agent, version);
     if (!fs.existsSync(dir))
@@ -429,9 +350,6 @@ export function listSkillsInVersionHome(agent, version) {
         .filter((name) => !commandWrappers.has(name))
         .sort();
 }
-/**
- * Check if a skill installed in a specific version matches central content.
- */
 function versionSkillMatches(agent, version, skillName) {
     const installedPath = path.join(getVersionSkillsDir(agent, version), skillName);
     const sourcePath = resolveSkillSourcePath(skillName);
@@ -452,17 +370,8 @@ function versionSkillMatches(agent, version, skillName) {
     }
     return directoriesMatch(path.join(installedPath, 'rules'), path.join(sourcePath, 'rules'));
 }
-/**
- * Compare a version home's skills against central. Returns the reconciliation diff.
- */
 export function diffVersionSkills(agent, version) {
-    // Plugin-provided skills (`plugins/<plugin>/skills`) are legitimate sources too, so a
-    // skill materialized from a plugin is NOT an orphan (PHNX-3185). Without this
-    // the detector offered to delete the entire plugin-installed skill library.
     const available = new Set([...listAllSkills(), ...listPluginSkillNames({ agent })]);
-    // Goose and other native ~/.agents/skills consumers read central storage
-    // directly. They intentionally have no per-version copy to diff, so every
-    // available central skill is already current for every supported version.
     if (AGENTS[agent].nativeAgentsSkillsDir) {
         return {
             agent,
@@ -495,10 +404,6 @@ export function diffVersionSkills(agent, version) {
     }
     return { agent, version, toAdd: toAdd.sort(), toUpdate: toUpdate.sort(), matched, orphans: orphans.sort() };
 }
-/**
- * Walk a directory and return every file's path relative to base.
- * Follows no symlinks. Returns empty set if the dir doesn't exist.
- */
 function walkRelativeFiles(base) {
     const out = new Set();
     if (!fs.existsSync(base))
@@ -526,14 +431,6 @@ function walkRelativeFiles(base) {
     }
     return out;
 }
-/**
- * Install a single skill from central into a specific version home.
- *
- * Copy mode preserves any files that exist in the version home but NOT in
- * central — e.g. user-populated `.env` alongside the git-tracked `.env.example`.
- * Without this, re-running `sync` whenever central content changes would wipe
- * local secrets.
- */
 export function installSkillToVersion(agent, version, skillName, method = 'copy') {
     const sourcePath = resolveSkillSourcePath(skillName);
     if (!sourcePath) {
@@ -544,10 +441,6 @@ export function installSkillToVersion(agent, version, skillName, method = 'copy'
         fs.mkdirSync(skillsDir, { recursive: true });
     }
     const target = path.join(skillsDir, skillName);
-    // Snapshot files unique to the version home so we can restore them after
-    // the fresh copy (copy mode only; symlink shares the source so there's
-    // nothing local to preserve — and writing a .env into a symlinked skill
-    // would pollute the git-tracked source dir anyway).
     const preserved = [];
     if (method === 'copy' && fs.existsSync(target) && !fs.lstatSync(target).isSymbolicLink()) {
         const sourceFiles = walkRelativeFiles(sourcePath);
@@ -564,7 +457,6 @@ export function installSkillToVersion(agent, version, skillName, method = 'copy'
                 });
             }
             catch {
-                // Unreadable — skip rather than fail the whole install
             }
         }
     }
@@ -587,7 +479,6 @@ export function installSkillToVersion(agent, version, skillName, method = 'copy'
     catch (err) {
         return { success: false, error: `Failed to ${method}: ${err.message}` };
     }
-    // Restore preserved files on top of the fresh copy.
     for (const { rel, buf, mode } of preserved) {
         try {
             const dest = path.join(target, rel);
@@ -596,15 +487,11 @@ export function installSkillToVersion(agent, version, skillName, method = 'copy'
             fs.chmodSync(dest, mode);
         }
         catch {
-            // Best-effort; failure here shouldn't unwind the install
         }
     }
     emit('skill.install', { skill: skillName, agent, version });
     return { success: true };
 }
-/**
- * Remove a single skill from a specific version home.
- */
 export function removeSkillFromVersion(agent, version, skillName) {
     const target = path.join(getVersionSkillsDir(agent, version), skillName);
     if (!fs.existsSync(target) && !fs.lstatSync(target, { throwIfNoEntry: false })) {
@@ -622,10 +509,6 @@ export function removeSkillFromVersion(agent, version, skillName) {
     }
     return { success: true };
 }
-/**
- * Iterate all (agent, version) pairs that support skills and are installed,
- * optionally scoped to a single agent/version.
- */
 export function iterSkillsCapableVersions(filter) {
     const pairs = [];
     const agents = filter?.agent ? [filter.agent] : capableAgents('skills');
@@ -642,12 +525,10 @@ export function iterSkillsCapableVersions(filter) {
     return pairs;
 }
 export function uninstallSkill(skillName) {
-    // Remove from central location
     const centralPath = path.join(getSkillsDir(), skillName);
     if (!fs.existsSync(centralPath)) {
         return { success: false, error: `Skill '${skillName}' not found` };
     }
-    // Remove from all agents
     for (const agentId of capableAgents('skills')) {
         const agentSkillPath = path.join(getAgentSkillsDir(agentId), skillName);
         if (fs.existsSync(agentSkillPath)) {
@@ -655,7 +536,6 @@ export function uninstallSkill(skillName) {
                 fs.rmSync(agentSkillPath, { recursive: true, force: true });
             }
             catch {
-                // Ignore removal errors
             }
         }
     }
@@ -663,7 +543,6 @@ export function uninstallSkill(skillName) {
         fs.rmSync(centralPath, { recursive: true, force: true });
     }
     catch {
-        // Ignore removal errors
     }
     emit('skill.remove', { skill: skillName });
     return { success: true };
@@ -678,10 +557,8 @@ export function listInstalledSkills() {
             for (const entry of entries) {
                 if (!entry.isDirectory())
                     continue;
-                // Skip hidden directories (e.g., .system)
                 if (entry.name.startsWith('.'))
                     continue;
-                // Primary wins on name collisions.
                 if (skills.has(entry.name))
                     continue;
                 const skillDir = path.join(dir, entry.name);
@@ -700,7 +577,6 @@ export function listInstalledSkills() {
             }
         }
         catch {
-            // Ignore errors
         }
     };
     scan(getSkillsDir());
@@ -712,7 +588,6 @@ export function listInstalledSkills() {
 export function listInstalledSkillsWithScope(agentId, cwd = process.cwd(), options) {
     const results = [];
     const seen = new Set();
-    // Project-scoped skills
     const projectCandidates = [];
     const projectAgentsDir = getProjectAgentsDir(cwd);
     if (projectAgentsDir) {
@@ -764,10 +639,8 @@ export function listInstalledSkillsWithScope(agentId, cwd = process.cwd(), optio
             }
         }
         catch {
-            // Ignore errors
         }
     }
-    // User-scoped skills (version-aware when home is provided)
     const userSkillsDir = options?.home
         ? path.join(options.home, agentConfigDirName(agentId), 'skills')
         : getAgentSkillsDir(agentId);
@@ -814,7 +687,6 @@ export function listInstalledSkillsWithScope(agentId, cwd = process.cwd(), optio
             }
         }
         catch {
-            // Ignore errors
         }
     }
     return results;
@@ -854,35 +726,25 @@ export function getSkillRules(skillName) {
         return [];
     }
 }
-/**
- * Install a skill to central ~/.agents/skills/ directory only.
- * Does not create per-agent symlinks (shims handle that for synced agents).
- */
 export function installSkillCentrally(sourcePath, skillName) {
-    // Validate skill metadata (warnings only, don't block installation)
     const metadata = parseSkillMetadata(sourcePath);
     const validation = validateSkillMetadata(metadata, skillName);
     const allWarnings = [...validation.warnings];
-    // Convert validation errors to warnings instead of blocking
     if (!validation.valid) {
         allWarnings.push(...validation.errors.map(e => `Validation: ${e}`));
     }
     ensureCentralSkillsDir();
     const centralPath = path.join(getSkillsDir(), skillName);
-    // Resolve to absolute paths for comparison
     const resolvedSource = path.resolve(sourcePath);
     const resolvedCentral = path.resolve(centralPath);
-    // If source is already the central path, nothing to copy
     if (resolvedSource === resolvedCentral) {
         return { success: true, warnings: allWarnings.length > 0 ? allWarnings : undefined };
     }
-    // Remove existing if present
     if (fs.existsSync(centralPath)) {
         try {
             fs.rmSync(centralPath, { recursive: true, force: true });
         }
         catch {
-            // Ignore removal errors
         }
     }
     try {

package/dist/lib/pr-land-detach.d.ts

@@ -1,23 +1,10 @@
-/**
- * Snapshot of the current branch's open PR (if any), for the headless-exit
- * fail-loud path. Returns null when there is no open PR or `gh` cannot answer.
- */
 interface BranchOpenPr {
     number: number;
     url: string;
     state: string;
 }
-/**
- * Pure classifier: should the exit path warn about this open PR?
- * Warn when the PR exists and is still OPEN.
- */
 export declare function shouldWarnOrphanedOpenPr(pr: BranchOpenPr | null): boolean;
-/** Human-readable warning for an open PR the exiting run left unattended. */
 export declare function formatOrphanedOpenPrWarning(pr: BranchOpenPr): string;
-/**
- * Probe `cwd` for an open PR on the current branch via `gh pr view`.
- * Fail-open: any error / missing gh → null (never block the run's exit).
- */
 export declare function getBranchOpenPr(cwd: string, execFileAsync: (file: string, args: string[], opts: {
     cwd: string;
     timeout: number;
@@ -25,9 +12,5 @@ export declare function getBranchOpenPr(cwd: string, execFileAsync: (file: strin
 }) => Promise<{
     stdout: string;
 }>): Promise<BranchOpenPr | null>;
-/**
- * Headless-exit fail-loud: if the cwd's branch has an OPEN PR, print a loud
- * stderr warning. Never throws.
- */
 export declare function warnOrphanedOpenPr(cwd?: string): Promise<void>;
 export {};