@forge-ts/gen 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,5 +1,325 @@
 import { ForgeSymbol, ForgeConfig, ForgeResult } from '@forge-ts/core';
 
+/**
+ * A single generated documentation page.
+ * @public
+ */
+interface DocPage {
+    /** Relative path from outDir (e.g., "packages/core/index.md") */
+    path: string;
+    /** Page content (Markdown or MDX) */
+    content: string;
+    /** Frontmatter fields */
+    frontmatter: Record<string, string | number | boolean>;
+    /**
+     * When true, this page is scaffolding intended for human/agent editing.
+     * Stub pages are created only on the first build and never overwritten,
+     * preserving manual edits across subsequent `forge-ts build` runs.
+     * Auto-generated pages (stub=false) are always regenerated from source.
+     */
+    stub?: boolean;
+}
+/**
+ * Options controlling the doc site generator.
+ * @public
+ */
+interface SiteGeneratorOptions {
+    /** Output format */
+    format: "markdown" | "mdx";
+    /** SSG target for frontmatter */
+    ssgTarget?: "docusaurus" | "mintlify" | "nextra" | "vitepress";
+    /** Project name */
+    projectName: string;
+    /** Project description */
+    projectDescription?: string;
+    /** Repository URL (auto-detected from package.json). */
+    repositoryUrl?: string;
+    /** npm package name for install commands. */
+    packageName?: string;
+}
+/**
+ * Groups symbols by their package based on file path.
+ *
+ * For monorepos (symbols under `packages/<name>/`) the package name is
+ * derived from the directory segment immediately after `packages/`.
+ * For non-monorepo projects all symbols fall under the project name.
+ *
+ * @param symbols - All extracted symbols.
+ * @param rootDir - Absolute path to the project root.
+ * @returns A map from package name to symbol list.
+ * @example
+ * ```typescript
+ * import { groupSymbolsByPackage } from "@forge-ts/gen";
+ * const grouped = groupSymbolsByPackage(symbols, "/path/to/project");
+ * console.log(grouped.has("core")); // true for monorepo
+ * ```
+ * @public
+ */
+declare function groupSymbolsByPackage(symbols: ForgeSymbol[], rootDir: string): Map<string, ForgeSymbol[]>;
+/**
+ * Generates a full multi-page documentation site from symbols grouped by package.
+ *
+ * Follows a 5-stage information architecture:
+ * 1. ORIENT — Landing page, Getting Started
+ * 2. LEARN — Concepts (stub)
+ * 3. BUILD — Guides (stub)
+ * 4. REFERENCE — API Reference, Types, Configuration, Changelog
+ * 5. COMMUNITY — FAQ, Contributing (stubs)
+ *
+ * @param symbolsByPackage - Symbols grouped by package name.
+ * @param config - The resolved {@link ForgeConfig}.
+ * @param options - Site generation options.
+ * @returns An array of {@link DocPage} objects ready to be written to disk.
+ * @example
+ * ```typescript
+ * import { generateDocSite, groupSymbolsByPackage } from "@forge-ts/gen";
+ * const grouped = groupSymbolsByPackage(symbols, config.rootDir);
+ * const pages = generateDocSite(grouped, config, { format: "markdown", projectName: "my-project" });
+ * console.log(pages.length > 0); // true
+ * ```
+ * @public
+ */
+declare function generateDocSite(symbolsByPackage: Map<string, ForgeSymbol[]>, config: ForgeConfig, options: SiteGeneratorOptions): DocPage[];
+
+/**
+ * Supported SSG target identifiers.
+ * @public
+ */
+type SSGTarget = "mintlify" | "docusaurus" | "nextra" | "vitepress";
+/**
+ * A file to write to disk during scaffolding or generation.
+ * @public
+ */
+interface GeneratedFile {
+    /** Relative path from the docs output directory. */
+    path: string;
+    /** File content (string for text). */
+    content: string;
+    /**
+     * When true, this file is scaffolding intended for human/agent editing.
+     * Stub files are created only on the first build and never overwritten,
+     * preserving manual edits across subsequent `forge-ts build` runs.
+     * Callers should check this flag and skip writing if the file exists.
+     */
+    stub?: boolean;
+}
+/**
+ * Style guide configuration for the SSG target.
+ * @public
+ */
+interface SSGStyleGuide {
+    /** File extension for doc pages. */
+    pageExtension: "md" | "mdx";
+    /** Whether the target supports MDX components. */
+    supportsMdx: boolean;
+    /** Whether frontmatter is required on every page. */
+    requiresFrontmatter: boolean;
+    /** Maximum recommended heading depth. */
+    maxHeadingDepth: number;
+    /** Component imports to add at top of MDX files (if supportsMdx). */
+    defaultImports: string[];
+    /** Code block language for TypeScript examples. */
+    codeBlockLanguage: "typescript" | "ts" | "tsx";
+}
+/**
+ * Scaffold manifest describing what `init docs` creates.
+ * @public
+ */
+interface ScaffoldManifest {
+    /** The SSG target this manifest is for. */
+    target: SSGTarget;
+    /** Files that will be created. */
+    files: GeneratedFile[];
+    /** npm dependencies to install. */
+    dependencies: Record<string, string>;
+    /** npm devDependencies to install. */
+    devDependencies: Record<string, string>;
+    /** Scripts to add to package.json. */
+    scripts: Record<string, string>;
+    /** Post-scaffold instructions for the user. */
+    instructions: string[];
+}
+/**
+ * Context passed to adapter methods.
+ * @public
+ */
+interface AdapterContext {
+    /** Resolved forge-ts configuration. */
+    config: ForgeConfig;
+    /** Project name (from package.json or directory). */
+    projectName: string;
+    /** Project description. */
+    projectDescription?: string;
+    /** The generated doc pages (from site-generator). */
+    pages: DocPage[];
+    /** All symbols extracted from the project. */
+    symbols: ForgeSymbol[];
+    /** Output directory for generated docs. */
+    outDir: string;
+}
+/**
+ * Command to start a local dev server for doc preview.
+ * @public
+ */
+interface DevServerCommand {
+    /** The binary to execute (e.g., "npx", "node"). */
+    bin: string;
+    /** Arguments to pass to the binary. */
+    args: string[];
+    /** Working directory to run from. */
+    cwd: string;
+    /** Human-readable label for the command. */
+    label: string;
+    /** The URL the dev server will be available at. */
+    url: string;
+}
+/**
+ * The central SSG adapter interface.
+ * Every doc platform provider implements this contract.
+ * One file per provider. No shared mutable state.
+ *
+ * @example
+ * ```typescript
+ * import { getAdapter } from "@forge-ts/gen";
+ * const adapter = getAdapter("mintlify");
+ * const files = adapter.transformPages(pages, context);
+ * ```
+ * @public
+ */
+interface SSGAdapter {
+    /** Unique target identifier. */
+    readonly target: SSGTarget;
+    /** Human-readable display name. */
+    readonly displayName: string;
+    /** Style guide for this platform. */
+    readonly styleGuide: SSGStyleGuide;
+    /**
+     * Generate the complete scaffold for a new doc site.
+     * Called by `forge-ts init docs --target <name>`.
+     * Returns all files, dependencies, and scripts needed.
+     *
+     * @param context - The adapter context for the current project.
+     * @returns A {@link ScaffoldManifest} with files, deps, and instructions.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("mintlify");
+     * const manifest = adapter.scaffold(context);
+     * console.log(manifest.files.length);
+     * ```
+     */
+    scaffold(context: AdapterContext): ScaffoldManifest;
+    /**
+     * Transform generic DocPages into platform-specific pages.
+     * Adds correct frontmatter, component imports, file extensions.
+     * Called during `forge-ts build`.
+     *
+     * @param pages - The generic doc pages to transform.
+     * @param context - The adapter context for the current project.
+     * @returns An array of {@link GeneratedFile} objects ready to write.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("docusaurus");
+     * const files = adapter.transformPages(pages, context);
+     * console.log(files[0].path.endsWith(".mdx")); // true
+     * ```
+     */
+    transformPages(pages: DocPage[], context: AdapterContext): GeneratedFile[];
+    /**
+     * Generate platform-specific configuration files.
+     * e.g., mint.json, sidebars.js, _meta.json, .vitepress/config.ts
+     * Called during `forge-ts build`.
+     *
+     * @param context - The adapter context for the current project.
+     * @returns An array of {@link GeneratedFile} objects ready to write.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("vitepress");
+     * const configs = adapter.generateConfig(context);
+     * console.log(configs[0].path); // ".vitepress/sidebar.json"
+     * ```
+     */
+    generateConfig(context: AdapterContext): GeneratedFile[];
+    /**
+     * Get the command to start the local dev server for this platform.
+     * Called by `forge-ts docs dev`.
+     *
+     * @param outDir - The docs output directory.
+     * @returns The shell command and args to spawn, plus a display label.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("mintlify");
+     * const cmd = adapter.getDevCommand("./docs");
+     * // { bin: "npx", args: ["@mintlify/cli", "dev"], cwd: "./docs" }
+     * ```
+     */
+    getDevCommand(outDir: string): DevServerCommand;
+    /**
+     * Check if a scaffold already exists in the output directory.
+     * Used for safety checks before init or target change.
+     *
+     * @param outDir - The output directory to inspect.
+     * @returns `true` if a scaffold marker file already exists.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("mintlify");
+     * const exists = await adapter.detectExisting("./docs");
+     * if (exists) console.log("Scaffold already present");
+     * ```
+     */
+    detectExisting(outDir: string): Promise<boolean>;
+}
+
+/**
+ * Register an SSG adapter.
+ * Called once per provider at module load time.
+ *
+ * @param adapter - The adapter to register.
+ * @example
+ * ```typescript
+ * import { registerAdapter } from "@forge-ts/gen";
+ * registerAdapter(mintlifyAdapter);
+ * ```
+ * @public
+ */
+declare function registerAdapter(adapter: SSGAdapter): void;
+/**
+ * Get a registered adapter by target name.
+ * Throws if the target is not registered.
+ *
+ * @param target - The SSG target identifier.
+ * @returns The registered {@link SSGAdapter} for the given target.
+ * @throws `Error` if the target is not registered.
+ * @example
+ * ```typescript
+ * import { getAdapter } from "@forge-ts/gen";
+ * const adapter = getAdapter("mintlify");
+ * ```
+ * @public
+ */
+declare function getAdapter(target: SSGTarget): SSGAdapter;
+/**
+ * Get all registered adapter targets.
+ *
+ * @returns An array of all registered {@link SSGTarget} identifiers.
+ * @example
+ * ```typescript
+ * import { getAvailableTargets } from "@forge-ts/gen";
+ * const targets = getAvailableTargets(); // ["mintlify", "docusaurus", ...]
+ * ```
+ * @public
+ */
+declare function getAvailableTargets(): SSGTarget[];
+/**
+ * The default SSG target when none is specified.
+ * @public
+ */
+declare const DEFAULT_TARGET: SSGTarget;
+
 /**
  * Generates an `llms.txt` routing manifest from the extracted symbols.
  *
@@ -91,70 +411,55 @@ interface ReadmeSyncOptions {
 declare function syncReadme(readmePath: string, symbols: ForgeSymbol[], options?: ReadmeSyncOptions): Promise<boolean>;
 
 /**
- * A single generated documentation page.
- * @public
- */
-interface DocPage {
-    /** Relative path from outDir (e.g., "packages/core/index.md") */
-    path: string;
-    /** Page content (Markdown or MDX) */
-    content: string;
-    /** Frontmatter fields */
-    frontmatter: Record<string, string | number | boolean>;
-}
-/**
- * Options controlling the doc site generator.
+ * A generated skill package following the agentskills.io directory structure.
+ * Contains SKILL.md plus optional references and scripts files.
+ *
  * @public
  */
-interface SiteGeneratorOptions {
-    /** Output format */
-    format: "markdown" | "mdx";
-    /** SSG target for frontmatter */
-    ssgTarget?: "docusaurus" | "mintlify" | "nextra" | "vitepress";
-    /** Project name */
-    projectName: string;
-    /** Project description */
-    projectDescription?: string;
+interface SkillPackage {
+    /** The skill directory name (lowercase, hyphens only, max 64 chars). */
+    directoryName: string;
+    /** Files to write inside the skill directory. */
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
 }
 /**
- * Groups symbols by their package based on file path.
+ * Generates an agentskills.io-compliant skill package for ANY TypeScript project.
  *
- * For monorepos (symbols under `packages/<name>/`) the package name is
- * derived from the directory segment immediately after `packages/`.
- * For non-monorepo projects all symbols fall under the project name.
+ * All content is derived from the project's exported symbols and metadata.
+ * No hardcoded project-specific content. Works for any project that forge-ts analyzes.
  *
- * @param symbols - All extracted symbols.
- * @param rootDir - Absolute path to the project root.
- * @returns A map from package name to symbol list.
+ * @param symbols - All symbols from the project.
+ * @param config - The resolved forge-ts config.
+ * @returns A {@link SkillPackage} describing the directory and its files.
  * @example
  * ```typescript
- * import { groupSymbolsByPackage } from "@forge-ts/gen";
- * const grouped = groupSymbolsByPackage(symbols, "/path/to/project");
- * console.log(grouped.has("core")); // true for monorepo
+ * import { generateSkillPackage } from "@forge-ts/gen";
+ * const pkg = generateSkillPackage(symbols, config);
+ * console.log(pkg.directoryName); // "my-lib"
+ * console.log(pkg.files.map(f => f.path));
+ * // ["SKILL.md", "references/API-REFERENCE.md", ...]
  * ```
  * @public
  */
-declare function groupSymbolsByPackage(symbols: ForgeSymbol[], rootDir: string): Map<string, ForgeSymbol[]>;
+declare function generateSkillPackage(symbols: ForgeSymbol[], config: ForgeConfig): SkillPackage;
 /**
- * Generates a full multi-page documentation site from symbols grouped by package.
+ * Generates a SKILL.md string following the Agent Skills specification.
+ * Generic for any TypeScript project — content derived from symbols.
  *
- * Produces an index page, a getting-started page, and per-package pages for
- * the API reference, types, functions, and examples.
- *
- * @param symbolsByPackage - Symbols grouped by package name.
- * @param config - The resolved {@link ForgeConfig}.
- * @param options - Site generation options.
- * @returns An array of {@link DocPage} objects ready to be written to disk.
+ * @param symbols - All symbols from the project.
+ * @param config - The resolved forge-ts config.
+ * @returns The SKILL.md content as a string.
  * @example
  * ```typescript
- * import { generateDocSite, groupSymbolsByPackage } from "@forge-ts/gen";
- * const grouped = groupSymbolsByPackage(symbols, config.rootDir);
- * const pages = generateDocSite(grouped, config, { format: "markdown", projectName: "my-project" });
- * console.log(pages.length > 0); // true
+ * import { generateSkillMd } from "@forge-ts/gen";
+ * const skill = generateSkillMd(symbols, config);
  * ```
  * @public
  */
-declare function generateDocSite(symbolsByPackage: Map<string, ForgeSymbol[]>, config: ForgeConfig, options: SiteGeneratorOptions): DocPage[];
+declare function generateSkillMd(symbols: ForgeSymbol[], config: ForgeConfig): string;
 
 /**
  * A single generated SSG configuration file.
@@ -196,10 +501,35 @@ declare function generateSSGConfigs(pages: DocPage[], target: "docusaurus" | "mi
  * @public
  */
 
+/**
+ * Options for the generation pipeline.
+ *
+ * @public
+ */
+interface GenerateOptions {
+    /**
+     * When true, overwrite stub pages even if they already exist on disk.
+     * Normally stub pages (concepts, guides, faq, contributing, changelog)
+     * are only created on the first build to preserve manual edits.
+     * Use this to reset stubs to their scaffolding state.
+     *
+     * @example
+     * ```typescript
+     * await generate(config, { forceStubs: true });
+     * ```
+     */
+    forceStubs?: boolean;
+}
 /**
  * Runs the full generation pipeline: walk → render → write.
  *
+ * Auto-generated pages are always regenerated from source code.
+ * Stub pages (scaffolding for human/agent editing) are only created
+ * if they don't already exist, preserving manual edits across builds.
+ * Pass `{ forceStubs: true }` to overwrite stubs.
+ *
  * @param config - The resolved {@link ForgeConfig} for the project.
+ * @param options - Optional generation flags (e.g., forceStubs).
  * @returns A {@link ForgeResult} describing the outcome.
  * @example
  * ```typescript
@@ -210,6 +540,6 @@ declare function generateSSGConfigs(pages: DocPage[], target: "docusaurus" | "mi
  * @public
  * @packageDocumentation
  */
-declare function generate(config: ForgeConfig): Promise<ForgeResult>;
+declare function generate(config: ForgeConfig, options?: GenerateOptions): Promise<ForgeResult>;
 
-export { type DocPage, type MarkdownOptions, type ReadmeSyncOptions, type SSGConfigFile, type SiteGeneratorOptions, generate, generateDocSite, generateLlmsFullTxt, generateLlmsTxt, generateMarkdown, generateSSGConfigs, groupSymbolsByPackage, syncReadme };
+export { type AdapterContext, DEFAULT_TARGET, type DevServerCommand, type DocPage, type GenerateOptions, type GeneratedFile, type MarkdownOptions, type ReadmeSyncOptions, type SSGAdapter, type SSGConfigFile, type SSGStyleGuide, type SSGTarget, type ScaffoldManifest, type SiteGeneratorOptions, type SkillPackage, generate, generateDocSite, generateLlmsFullTxt, generateLlmsTxt, generateMarkdown, generateSSGConfigs, generateSkillMd, generateSkillPackage, getAdapter, getAvailableTargets, groupSymbolsByPackage, registerAdapter, syncReadme };