padrone 1.3.0 → 1.5.0

package/src/docs/index.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { commandSymbol } from '../command-utils.ts';
+import { getCommand } from '../command-utils.ts';
 import type { HelpArgumentInfo, HelpInfo, HelpPositionalInfo, HelpSubcommandInfo } from '../formatter.ts';
 import { getHelpInfo } from '../help.ts';
 import type { AnyPadroneCommand } from '../types.ts';
@@ -220,6 +220,18 @@ function generateMarkdownPage(info: HelpInfo, depth: number, frontmatterFn?: Doc
   lines.push('```');
   lines.push('');
 
+  // Examples
+  if (info.examples?.length) {
+    lines.push('## Examples');
+    lines.push('');
+    lines.push('```');
+    for (const ex of info.examples) {
+      lines.push(`$ ${ex}`);
+    }
+    lines.push('```');
+    lines.push('');
+  }
+
   // Subcommands
   if (info.subcommands?.length) {
     const visibleSubs = info.subcommands.filter((s) => !s.hidden);
@@ -307,6 +319,12 @@ function generateHtmlPage(info: HelpInfo, depth: number): string {
   sections.push('  <h2>Usage</h2>');
   sections.push(`  <pre><code>${escapeHtml(usageParts.join(' '))}</code></pre>`);
 
+  // Examples
+  if (info.examples?.length) {
+    sections.push('  <h2>Examples</h2>');
+    sections.push(`  <pre><code>${info.examples.map((ex) => `$ ${escapeHtml(ex)}`).join('\n')}</code></pre>`);
+  }
+
   // Subcommands
   if (info.subcommands?.length) {
     const visibleSubs = info.subcommands.filter((s) => !s.hidden);
@@ -381,7 +399,7 @@ function generateHtmlPage(info: HelpInfo, depth: number): string {
 }
 
 // ============================================================================
-// Man Page Generator
+// Man Page Generator (experimental)
 // ============================================================================
 
 function escapeMan(text: string): string {
@@ -418,6 +436,15 @@ function generateManPage(info: HelpInfo, _depth: number, programName: string): s
     lines.push(escapeMan(info.description));
   }
 
+  // EXAMPLES
+  if (info.examples?.length) {
+    lines.push('.SH EXAMPLES');
+    for (const ex of info.examples) {
+      lines.push('.PP');
+      lines.push(`.nf\n$ ${escapeMan(ex)}\n.fi`);
+    }
+  }
+
   // COMMANDS
   if (info.subcommands?.length) {
     const visibleSubs = info.subcommands.filter((s) => !s.hidden);
@@ -517,11 +544,6 @@ function generateMarkdownIndex(rootInfo: HelpInfo, allInfos: HelpInfo[]): string
 // Main Entry Point
 // ============================================================================
 
-function resolveCommand(programOrCommand: object): AnyPadroneCommand {
-  if (commandSymbol in programOrCommand) return (programOrCommand as any)[commandSymbol] as AnyPadroneCommand;
-  return programOrCommand as AnyPadroneCommand;
-}
-
 /**
  * Generate documentation for a Padrone CLI program or command tree.
  * Accepts either a PadroneProgram (from createPadrone()) or a raw AnyPadroneCommand.
@@ -529,7 +551,7 @@ function resolveCommand(programOrCommand: object): AnyPadroneCommand {
 export function generateDocs(program: object, options: DocsOptions = {}): DocsResult {
   const { format = 'markdown', output, includeHidden = false, frontmatter, overwrite = true, dryRun = false } = options;
 
-  const cmd = resolveCommand(program);
+  const cmd = getCommand(program);
   const allInfos = collectAllHelpInfo(cmd, includeHidden);
   const rootInfo = allInfos[0]!;
   const programName = cmd.name || 'program';
@@ -605,3 +627,95 @@ export function generateDocs(program: object, options: DocsOptions = {}): DocsRe
 
   return result;
 }
+
+// ============================================================================
+// Man Page Installation
+// ============================================================================
+
+export type SetupManPagesResult = {
+  /** Directory where man pages were written. */
+  dir: string;
+  /** Man page files that were written. */
+  written: string[];
+  /** Whether existing pages were overwritten (true) or newly created (false). */
+  updated: boolean;
+};
+
+/**
+ * Returns the local man page directory for the given section.
+ * Uses `~/.local/share/man/man<section>` (XDG convention).
+ */
+function getManPageDir(section = 1): string {
+  const { homedir } = require('node:os') as typeof import('node:os');
+  const { join: joinPath } = require('node:path') as typeof import('node:path');
+  return joinPath(process.env.XDG_DATA_HOME || joinPath(homedir(), '.local', 'share'), 'man', `man${section}`);
+}
+
+/**
+ * Converts a command name to a man page filename.
+ * "myapp" → "myapp.1", "myapp deploy" → "myapp-deploy.1"
+ */
+function manPageFilename(commandName: string, section = 1): string {
+  return `${commandName.replace(/\s+/g, '-')}.${section}`;
+}
+
+/**
+ * Installs man pages for a Padrone CLI program into the local man directory.
+ * Generates man pages for all commands and writes them to `~/.local/share/man/man1/`.
+ *
+ * After installation, `man <program>` and `man <program>-<subcommand>` should work
+ * (assuming `~/.local/share/man` is in `MANPATH` or `manpath` picks it up).
+ */
+export function setupManPages(program: object): SetupManPagesResult {
+  const cmd = getCommand(program);
+  const allInfos = collectAllHelpInfo(cmd, false);
+  const programName = cmd.name || 'program';
+  const manDir = getManPageDir(1);
+
+  mkdirSync(manDir, { recursive: true });
+
+  const written: string[] = [];
+  let updated = false;
+
+  for (let i = 0; i < allInfos.length; i++) {
+    const info = allInfos[i]!;
+    const depth = i === 0 ? 0 : info.name.split(/\s+/).length;
+    const commandName = info.name === '<root>' || !info.name ? programName : info.name;
+    const filename = manPageFilename(commandName);
+    const fullPath = join(manDir, filename);
+
+    if (existsSync(fullPath)) updated = true;
+
+    const content = generateManPage(info, depth, programName);
+    writeFileSync(fullPath, content, 'utf-8');
+    written.push(filename);
+  }
+
+  return { dir: manDir, written, updated };
+}
+
+/**
+ * Removes installed man pages for a Padrone CLI program.
+ */
+export function removeManPages(program: object): { dir: string; removed: string[] } {
+  const { unlinkSync } = require('node:fs') as typeof import('node:fs');
+  const cmd = getCommand(program);
+  const allInfos = collectAllHelpInfo(cmd, false);
+  const programName = cmd.name || 'program';
+  const manDir = getManPageDir(1);
+  const removed: string[] = [];
+
+  for (let i = 0; i < allInfos.length; i++) {
+    const info = allInfos[i]!;
+    const commandName = info.name === '<root>' || !info.name ? programName : info.name;
+    const filename = manPageFilename(commandName);
+    const fullPath = join(manDir, filename);
+
+    if (existsSync(fullPath)) {
+      unlinkSync(fullPath);
+      removed.push(filename);
+    }
+  }
+
+  return { dir: manDir, removed };
+}