browser-debugger-cli 0.12.0 → 0.14.0

package/dist/commands/helpJson.js

@@ -4,6 +4,7 @@
 import { getAllDomainSummaries } from '../cdp/schema.js';
 import { getOptionBehavior } from './optionBehaviors.js';
 import { readLiveDaemonPid } from '../session/cleanup/staleSession.js';
+import { helpJsonDetailsNote } from '../ui/messages/commands.js';
 import { getAllDecisionTrees } from '../utils/decisionTrees.js';
 import { EXIT_CODE_REGISTRY } from '../utils/exitCodes.js';
 import { getAllTaskMappings } from '../utils/taskMappings.js';
@@ -35,7 +36,7 @@ function convertOption(option, commandName) {
     if (option.argChoices) {
         metadata.choices = option.argChoices;
     }
-    const behavior = getOptionBehavior(commandName, option.flags);
+    const behavior = getOptionBehavior(commandName, option);
     if (behavior) {
         metadata.behavior = behavior;
     }
@@ -65,6 +66,21 @@ function convertArgument(argument) {
     }
     return metadata;
 }
+/**
+ * The text a command adds after its options in `--help` (examples, output
+ * legend), collected from its `afterHelp` listeners. Commander's Command is an
+ * EventEmitter at runtime; its typings leave that out.
+ *
+ * @param command - Commander command instance
+ * @returns The text, or undefined when the command adds none
+ */
+function afterHelpText(command) {
+    const chunks = [];
+    const emitter = command;
+    emitter.emit('afterHelp', { error: false, command, write: (text) => chunks.push(text) });
+    const text = chunks.join('').trim();
+    return text || undefined;
+}
 /**
  * Recursively converts a Commander Command to CommandMetadata.
  *
@@ -75,6 +91,7 @@ function convertArgument(argument) {
  */
 function convertCommand(command) {
     const commandName = command.name();
+    const helpText = afterHelpText(command);
     return {
         name: commandName,
         aliases: command.aliases(),
@@ -82,9 +99,45 @@ function convertCommand(command) {
         usage: command.usage(),
         arguments: command.registeredArguments.map(convertArgument),
         options: command.options.map((opt) => convertOption(opt, commandName)),
+        ...(helpText && { helpText }),
         subcommands: command.commands.map(convertCommand),
     };
 }
+/**
+ * An argument as written in usage: `<name>`, `[name]`, `<name...>`.
+ *
+ * @param argument - Commander argument instance
+ * @returns Usage term
+ */
+function argumentTerm(argument) {
+    const name = `${argument.name()}${argument.variadic ? '...' : ''}`;
+    return argument.required ? `<${name}>` : `[${name}]`;
+}
+/**
+ * Recursively converts a Commander Command to its compact summary: first
+ * description line, arguments, and visible options with their descriptions.
+ * Empty fields are left out.
+ *
+ * @param command - Commander command instance
+ * @returns Compact command summary
+ */
+function convertCompactCommand(command) {
+    const aliases = command.aliases();
+    const args = command.registeredArguments.map(argumentTerm).join(' ');
+    const options = command.options.filter((option) => !option.hidden);
+    return {
+        name: command.name(),
+        ...(aliases.length > 0 && { aliases }),
+        description: command.description().split('\n')[0] ?? '',
+        ...(args && { arguments: args }),
+        ...(options.length > 0 && {
+            options: Object.fromEntries(options.map((option) => [option.flags, option.description])),
+        }),
+        ...(command.commands.length > 0 && {
+            subcommands: command.commands.map(convertCompactCommand),
+        }),
+    };
+}
 /**
  * Generates runtime state information.
  *
@@ -150,10 +203,11 @@ function generateCapabilities() {
     };
 }
 /**
- * Generates machine-readable help from a Commander program.
+ * Generates the full machine-readable help from a Commander program
+ * (`bdg --help --json --full`).
  *
  * Includes comprehensive metadata for agent discovery:
- * - Command structure and options
+ * - Command structure and options with behaviors
  * - Exit codes with semantic meanings
  * - Task-to-command mappings with CDP alternatives
  * - Runtime state and command availability
@@ -162,15 +216,6 @@ function generateCapabilities() {
  *
  * @param program - Commander program instance
  * @returns Machine-readable help structure
- *
- * @example
- * ```typescript
- * import { program } from 'commander';
- * import { generateMachineReadableHelp } from './help/machineReadableHelp.js';
- *
- * const help = generateMachineReadableHelp(program);
- * console.log(JSON.stringify(help, null, 2));
- * ```
  */
 export function generateMachineReadableHelp(program) {
     return {
@@ -186,56 +231,82 @@ export function generateMachineReadableHelp(program) {
     };
 }
 /**
- * Finds a subcommand by traversing the command path.
+ * Generates the compact root help (`bdg --help --json`): the full help with
+ * the command tree reduced to names, one-line descriptions and flags.
+ *
+ * @param program - Commander program instance
+ * @returns Compact help structure
+ */
+export function generateCompactHelp(program) {
+    return {
+        ...generateMachineReadableHelp(program),
+        details: helpJsonDetailsNote(),
+        command: convertCompactCommand(program),
+    };
+}
+/**
+ * The command a command line addresses: follows the words that name
+ * subcommands and skips the others (option values, arguments), stopping at a
+ * command without subcommands.
  *
  * @param program - Root Commander program instance
- * @param commandPath - Array of command names to traverse (e.g., ['dom', 'query'])
- * @returns The target Command if found, null otherwise
+ * @param words - Command-line words, e.g. ['dom', 'query', '.item']
+ * @returns The addressed command (the program when no word names one)
+ *
+ * @example
+ * ```typescript
+ * resolveCommand(program, ['--session', 'a', 'dom', 'query', '.item']).name(); // 'query'
+ * ```
  */
-function findSubcommand(program, commandPath) {
+export function resolveCommand(program, words) {
     let current = program;
-    for (const name of commandPath) {
-        const found = current.commands.find((cmd) => cmd.name() === name || cmd.aliases().includes(name));
-        if (!found) {
-            return null;
-        }
-        current = found;
+    for (const word of words) {
+        if (current.commands.length === 0)
+            break;
+        const found = current.commands.find((cmd) => cmd.name() === word || cmd.aliases().includes(word));
+        if (found)
+            current = found;
     }
     return current;
 }
 /**
- * Generates machine-readable help for a specific subcommand.
+ * Full command path, e.g. "bdg dom query".
  *
- * Returns the same structure as generateMachineReadableHelp but with
- * the command field focused on the requested subcommand. If the subcommand
- * is not found, falls back to full root help.
+ * @param command - Commander command instance
+ * @returns Names from the program down to the command
+ */
+export function commandPath(command) {
+    const names = [];
+    for (let level = command; level; level = level.parent)
+        names.unshift(level.name());
+    return names.join(' ');
+}
+/**
+ * Generates machine-readable help for one command: its full metadata,
+ * compact subcommands (a group lists them like the root help does) and the
+ * exit codes.
  *
  * @param program - Root Commander program instance
- * @param commandPath - Array of command names (e.g., ['dom', 'query'])
- * @returns Machine-readable help structure for the subcommand
+ * @param command - The command (from {@link resolveCommand})
+ * @returns Help for the command
  *
  * @example
  * ```typescript
- * // Get help for 'bdg dom query'
- * const help = generateSubcommandHelp(program, ['dom', 'query']);
- * console.log(help.command.name); // 'query'
+ * const help = generateCommandHelp(program, resolveCommand(program, ['dom', 'query']));
+ * console.log(help.path); // 'bdg dom query'
  * ```
  */
-export function generateSubcommandHelp(program, commandPath) {
-    const targetCommand = findSubcommand(program, commandPath);
-    if (!targetCommand) {
-        return generateMachineReadableHelp(program);
-    }
+export function generateCommandHelp(program, command) {
     return {
         name: program.name(),
         version: program.version() ?? 'unknown',
         description: program.description(),
-        command: convertCommand(targetCommand),
+        path: commandPath(command),
+        command: {
+            ...convertCommand(command),
+            subcommands: command.commands.map(convertCompactCommand),
+        },
         exitCodes: [...EXIT_CODE_DOCS],
-        taskMappings: getAllTaskMappings(),
-        runtimeState: generateRuntimeState(),
-        decisionTrees: getAllDecisionTrees(),
-        capabilities: generateCapabilities(),
     };
 }
 //# sourceMappingURL=helpJson.js.map

package/dist/commands/helpTopic.d.ts

@@ -1,7 +1,7 @@
 /**
  * `bdg help <command...>` topics and Commander usage-error hints.
  */
-import type { Command } from 'commander';
+import type { Command, CommanderError } from 'commander';
 /**
  * The command path of `bdg help <path...>`: the words before the first option.
  *
@@ -29,4 +29,19 @@ export declare function splitCommanderHint(text: string): {
     message: string;
     suggestion?: string;
 };
+/**
+ * Message and suggestion for a Commander usage error: a did-you-mean for an
+ * unknown option or command, otherwise a pointer to the command's `--help`.
+ * A word typed after a single dash (`-josn`) is matched against the long
+ * options.
+ *
+ * @param error - Commander error (not a help or version display)
+ * @param command - Command the error came from (see resolveCommand)
+ * @param argv - Process arguments (to name an option as typed)
+ * @returns Message and suggestion
+ */
+export declare function usageErrorDetails(error: CommanderError, command: Command, argv?: string[]): {
+    message: string;
+    suggestion: string;
+};
 //# sourceMappingURL=helpTopic.d.ts.map

package/dist/commands/helpTopic.js

@@ -1,8 +1,9 @@
 /**
  * `bdg help <command...>` topics and Commander usage-error hints.
  */
+import { commandPath } from './helpJson.js';
 import { CommandError } from '../errors/index.js';
-import { unknownHelpTopicError } from '../errors/messages.js';
+import { missingSubcommandMessage, unknownHelpTopicError, usageHelpSuggestion, } from '../errors/messages.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { findSimilar } from '../utils/suggestions.js';
 /** Commander's typo hint on its own line, e.g. "(Did you mean query?)" */
@@ -55,4 +56,61 @@ export function splitCommanderHint(text) {
         return { message };
     return { message: message.slice(0, hint.index).trim(), suggestion: `Did you mean: ${hint[1]}?` };
 }
+/** The option named in Commander's "unknown option '--x'" message, without an `=value` */
+const UNKNOWN_OPTION = /unknown option '([^'=]+)/;
+/**
+ * The long option of a command closest to a mistyped one, hidden global
+ * options (`--session`, `--quiet`) included. Up to one edit per three letters
+ * of the name counts as a typo, so `--frob` does not suggest `--json`.
+ *
+ * @param flag - Option as typed, e.g. "--sesion"
+ * @param command - Command it was given to
+ * @returns Closest long option, if any is similar
+ */
+function closestOption(flag, command) {
+    const longs = command.options.flatMap((option) => (option.long ? [option.long] : []));
+    const maxDistance = Math.ceil(flag.replace(/^-+/, '').length / 3);
+    return findSimilar(flag, longs, { maxDistance })[0];
+}
+/**
+ * The option as typed, for one Commander split: it reads `-josn` as `-j`
+ * (`--json`) followed by `-osn`, and reports `-osn` as unknown.
+ *
+ * @param flag - Option Commander reported, e.g. "-osn"
+ * @param argv - Process arguments
+ * @returns The argument it came from, e.g. "-josn", else the option itself
+ */
+function typedOption(flag, argv) {
+    if (flag.startsWith('--'))
+        return flag;
+    const rest = flag.slice(1);
+    return (argv.find((arg) => /^-[^-]/.test(arg) && arg.length > flag.length && arg.endsWith(rest)) ?? flag);
+}
+/**
+ * Message and suggestion for a Commander usage error: a did-you-mean for an
+ * unknown option or command, otherwise a pointer to the command's `--help`.
+ * A word typed after a single dash (`-josn`) is matched against the long
+ * options.
+ *
+ * @param error - Commander error (not a help or version display)
+ * @param command - Command the error came from (see resolveCommand)
+ * @param argv - Process arguments (to name an option as typed)
+ * @returns Message and suggestion
+ */
+export function usageErrorDetails(error, command, argv = process.argv) {
+    const help = usageHelpSuggestion(commandPath(command));
+    if (error.code === 'commander.help') {
+        return { message: missingSubcommandMessage(), suggestion: help };
+    }
+    const { message, suggestion } = splitCommanderHint(error.message);
+    const flag = error.code === 'commander.unknownOption' && UNKNOWN_OPTION.exec(message)?.[1];
+    if (!flag)
+        return { message, suggestion: suggestion ?? help };
+    const typed = typedOption(flag, argv);
+    const closest = closestOption(/^-[^-]../.test(typed) ? `-${typed}` : typed, command);
+    return {
+        message: message.replace(`'${flag}'`, `'${typed}'`),
+        suggestion: closest ? `Did you mean: ${closest}?` : help,
+    };
+}
 //# sourceMappingURL=helpTopic.js.map

package/dist/commands/installSkill.d.ts

@@ -1,16 +1,26 @@
 import type { Command } from 'commander';
+import { CommandError } from '../errors/index.js';
 import type { InstalledSkill, SkillTarget } from '../types.js';
+/** What installing the skill did, and why it failed for a target, if it did */
+export interface SkillInstallResult {
+    /** Targets the skill was installed for (or left unchanged) */
+    skills: InstalledSkill[];
+    /** Error (82) for the targets that could not be written */
+    failure?: CommandError;
+}
 /**
- * Copy the bdg skill into each target's skill directory, overwriting an
- * older copy.
+ * Copy the bdg skill into each target's skill directory. A copy that differs
+ * (an older version, or one the user edited) is kept as `SKILL.md.bak`
+ * before it is overwritten. A target that cannot be written does not stop
+ * the others.
  *
  * @param targets - Agents to install for
  * @param home - Home directory the skill roots are relative to
  * @param source - SKILL.md to copy
- * @returns One entry per target, in the given order
- * @throws CommandError when the source is missing (83) or a write fails (82)
+ * @returns The targets written, in the given order, and the failure if any
+ * @throws CommandError when the source is missing (83)
  */
-export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): InstalledSkill[];
+export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): SkillInstallResult;
 /**
  * Register the install-skill command.
  *

package/dist/commands/installSkill.js

@@ -1,14 +1,17 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, join } from 'path';
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
 import { CommandError } from '../errors/index.js';
 import { skillSourceMissingError, skillWriteFailedError } from '../errors/messages.js';
-import { formatInstalledSkills } from '../ui/formatters/installSkill.js';
+import { formatInstalledSkills, formatSkillTargets } from '../ui/formatters/installSkill.js';
+import { createLogger } from '../ui/logging/index.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+import { safeRemoveFile } from '../utils/file.js';
 import { PACKAGE_ROOT } from '../utils/packageRoot.js';
+const log = createLogger('bdg');
 /** The skill shipped with the package (also used by agents working in this repo). */
 const SKILL_SOURCE_PATH = join(PACKAGE_ROOT, '.claude', 'skills', 'bdg', 'SKILL.md');
 /** Skill roots, relative to the home directory, of the agents the skill is installed for. */
@@ -17,14 +20,16 @@ const SKILL_ROOTS = {
     agents: join('.agents', 'skills'),
 };
 /**
- * Copy the bdg skill into each target's skill directory, overwriting an
- * older copy.
+ * Copy the bdg skill into each target's skill directory. A copy that differs
+ * (an older version, or one the user edited) is kept as `SKILL.md.bak`
+ * before it is overwritten. A target that cannot be written does not stop
+ * the others.
  *
  * @param targets - Agents to install for
  * @param home - Home directory the skill roots are relative to
  * @param source - SKILL.md to copy
- * @returns One entry per target, in the given order
- * @throws CommandError when the source is missing (83) or a write fails (82)
+ * @returns The targets written, in the given order, and the failure if any
+ * @throws CommandError when the source is missing (83)
  */
 export function installSkill(targets, home = homedir(), source = SKILL_SOURCE_PATH) {
     if (!existsSync(source)) {
@@ -32,31 +37,76 @@ export function installSkill(targets, home = homedir(), source = SKILL_SOURCE_PA
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
     const content = readFileSync(source, 'utf-8');
-    return targets.map((target) => writeSkill(target, join(home, SKILL_ROOTS[target], 'bdg', 'SKILL.md'), content));
+    const skills = [];
+    const failures = [];
+    for (const target of targets) {
+        const result = writeSkill(target, join(home, SKILL_ROOTS[target], 'bdg', 'SKILL.md'), content);
+        if ('error' in result)
+            failures.push(result);
+        else
+            skills.push(result);
+    }
+    if (failures.length === 0)
+        return { skills };
+    return { skills, failure: skillFailureError(failures, targets) };
+}
+/**
+ * The error for targets the skill could not be written for. When only one of
+ * several targets failed, it suggests installing for the other only. Each
+ * distinct suggestion is kept, so every failure cause gets its fix.
+ *
+ * @param failures - Targets that failed (at least one)
+ * @param targets - Targets picked
+ * @returns Command error (82)
+ */
+function skillFailureError(failures, targets) {
+    const other = failures.length === 1 ? targets.find((t) => t !== failures[0]?.target) : undefined;
+    const errors = failures.map(({ path, error }) => {
+        const code = error.code;
+        return skillWriteFailedError(path, getErrorMessage(error), code === 'ENOTDIR' || code === 'EEXIST', other && `--${other}`);
+    });
+    return new CommandError(errors.map((err) => err.message).join('\n'), { suggestion: [...new Set(errors.map((err) => err.suggestion))].join('\n') }, EXIT_CODES.PERMISSION_DENIED);
 }
 /**
- * Write the skill to one path unless it already holds the same content.
+ * Write the skill to one path unless it already holds the same content; a
+ * different copy is first kept next to it as `SKILL.md.bak` (replacing an
+ * earlier backup), so edits to it are not lost. The new text is written to a
+ * temporary file first, so a failed write leaves both the copy and the
+ * backup as they were; the backup gets the default file mode, whatever the
+ * copy's was.
  *
  * @param target - Agent the path belongs to
  * @param path - Destination SKILL.md
  * @param content - Skill text
- * @returns What happened to the file
- * @throws CommandError (82) when the directory or file cannot be written
+ * @returns What happened to the file, with the backup path when one was made,
+ *   or the file that could not be written and why
  */
 function writeSkill(target, path, content) {
     const existing = existsSync(path) ? readFileSync(path, 'utf-8') : undefined;
     if (existing === content) {
         return { target, path, status: 'unchanged' };
     }
+    const backup = existing === undefined ? undefined : `${path}.bak`;
+    const temporary = `${path}.tmp`;
+    let writing = path;
     try {
         mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, content);
+        writeFileSync(temporary, content);
+        if (backup !== undefined) {
+            writing = backup;
+            rmSync(backup, { force: true });
+            writeFileSync(backup, existing ?? '');
+        }
+        writing = path;
+        renameSync(temporary, path);
     }
-    catch (caught) {
-        const err = skillWriteFailedError(path, getErrorMessage(caught));
-        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.PERMISSION_DENIED);
+    catch (error) {
+        safeRemoveFile(temporary, 'temporary skill copy', log);
+        return { target, path: writing, error };
     }
-    return { target, path, status: existing === undefined ? 'installed' : 'updated' };
+    if (backup === undefined)
+        return { target, path, status: 'installed' };
+    return { target, path, status: 'updated', backup };
 }
 /**
  * Targets picked by the flags; no flag means every agent.
@@ -68,6 +118,26 @@ function selectedTargets(options) {
     const picked = Object.keys(SKILL_ROOTS).filter((target) => options[target]);
     return picked.length > 0 ? picked : Object.keys(SKILL_ROOTS);
 }
+/**
+ * Install the skill for the picked targets. When a target fails, the error
+ * still lists the targets that were written (and their backups): JSON
+ * `skills`, or the same lines as a successful install.
+ *
+ * @param options - Parsed command options
+ * @returns Command result
+ */
+function installSkillResult(options) {
+    const { skills, failure } = installSkill(selectedTargets(options));
+    if (!failure)
+        return { success: true, data: { skills } };
+    const written = skills.length === 0 ? {} : options.json ? { skills } : { written: formatSkillTargets(skills) };
+    return {
+        success: false,
+        error: failure.message,
+        exitCode: failure.exitCode,
+        errorContext: { ...written, ...failure.metadata },
+    };
+}
 /**
  * Register the install-skill command.
  *
@@ -81,7 +151,7 @@ export function registerInstallSkillCommand(program) {
         .option('--agents', 'Only ~/.agents/skills (Codex, Gemini CLI and other agents)')
         .addOption(jsonOption())
         .action(async (options) => {
-        await runCommand((opts) => Promise.resolve({ success: true, data: { skills: installSkill(selectedTargets(opts)) } }), options, formatInstalledSkills);
+        await runCommand((opts) => Promise.resolve(installSkillResult(opts)), options, formatInstalledSkills);
     });
 }
 //# sourceMappingURL=installSkill.js.map