@forge-ts/gen 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -11,6 +11,13 @@ interface DocPage {
     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.
@@ -25,6 +32,10 @@ interface SiteGeneratorOptions {
     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.
@@ -48,8 +59,12 @@ declare function groupSymbolsByPackage(symbols: ForgeSymbol[], rootDir: string):
 /**
  * Generates a full multi-page documentation site from symbols grouped by package.
  *
- * Produces an index page, a getting-started page, and per-package pages for
- * the API reference, types, functions, and examples.
+ * 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}.
@@ -80,6 +95,13 @@ interface GeneratedFile {
     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.
@@ -135,6 +157,22 @@ interface AdapterContext {
     /** 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.
@@ -204,6 +242,21 @@ interface SSGAdapter {
      * ```
      */
     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.
@@ -357,6 +410,57 @@ interface ReadmeSyncOptions {
  */
 declare function syncReadme(readmePath: string, symbols: ForgeSymbol[], options?: ReadmeSyncOptions): Promise<boolean>;
 
+/**
+ * A generated skill package following the agentskills.io directory structure.
+ * Contains SKILL.md plus optional references and scripts files.
+ *
+ * @public
+ */
+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;
+    }>;
+}
+/**
+ * Generates an agentskills.io-compliant skill package for ANY TypeScript project.
+ *
+ * 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 symbols from the project.
+ * @param config - The resolved forge-ts config.
+ * @returns A {@link SkillPackage} describing the directory and its files.
+ * @example
+ * ```typescript
+ * 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 generateSkillPackage(symbols: ForgeSymbol[], config: ForgeConfig): SkillPackage;
+/**
+ * Generates a SKILL.md string following the Agent Skills specification.
+ * Generic for any TypeScript project — content derived from symbols.
+ *
+ * @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 { generateSkillMd } from "@forge-ts/gen";
+ * const skill = generateSkillMd(symbols, config);
+ * ```
+ * @public
+ */
+declare function generateSkillMd(symbols: ForgeSymbol[], config: ForgeConfig): string;
+
 /**
  * A single generated SSG configuration file.
  * @public
@@ -397,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
@@ -411,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 AdapterContext, DEFAULT_TARGET, type DocPage, type GeneratedFile, type MarkdownOptions, type ReadmeSyncOptions, type SSGAdapter, type SSGConfigFile, type SSGStyleGuide, type SSGTarget, type ScaffoldManifest, type SiteGeneratorOptions, generate, generateDocSite, generateLlmsFullTxt, generateLlmsTxt, generateMarkdown, generateSSGConfigs, getAdapter, getAvailableTargets, groupSymbolsByPackage, registerAdapter, 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 };