{
  "$schema": "https://raw.githubusercontent.com/machanism-org/machai/refs/heads/main/bindex-core/src/main/resources/schema/bindex-schema-v2.json",
  "id": "org.machanism.machai:ghostwriter:1.2.0-SNAPSHOT",
  "name": "org.machanism.machai:ghostwriter",
  "version": "1.2.0-SNAPSHOT",
  "location": {
    "repositoryType": "Maven",
    "repositoryUrl": "https://repo.maven.apache.org/maven2",
    "coordinates": {
      "group": "org.machanism.machai",
      "artifactId": "ghostwriter",
      "version": "1.2.0-SNAPSHOT",
      "extension": "jar"
    }
  },
  "description": "Ghostwriter is an advanced documentation engine that automatically scans, analyzes, and assembles project documentation using embedded guidance tags and AI-powered synthesis. It is a filesystem-oriented documentation and prompt-execution tool for repositories that embed author instructions inside project files. It discovers @guidance directives, gathers project layout metadata, builds repository-aware prompts, and applies generated output back to matching files. Ghostwriter supports source code, documentation, project site content, and other repository files, enabling documentation-oriented and workflow-oriented updates directly from the filesystem. It also supports reusable Act templates that define structured prompt workflows for repeated maintenance, review, and content-generation tasks. The runtime is organized around processor, reviewer, and tool packages. Command-line orchestration selects scan targets, traverses detected project layout, delegates file inspection to format-aware reviewers, composes prompts, and executes them through a configured org.machanism.machai.ai.provider.Genai provider. Optional function tools extend prompt execution with controlled access to project files, command execution, web access, REST access, Act lifecycle operations, and project-scoped context variables.",
  "authors": [
    {
      "name": "Viktor Tovstyi",
      "website": "https://machai.machanism.org/ghostwriter"
    }
  ],
  "license": "Apache License, Version 2.0",
  "classification": {
    "type": "library",
    "domains": [
      "Documentation generation",
      "Prompt execution",
      "AI-assisted repository maintenance",
      "Filesystem-oriented workflow automation"
    ],
    "languages": [
      {
        "name": "Java",
        "version": "11"
      }
    ],
    "layers": [
      "Adapters",
      "Infrastructure",
      "Utils"
    ],
    "usageContext": [
      "Command-line orchestration for repository scans",
      "Guidance-driven documentation and maintenance workflows",
      "Act-based structured prompt workflows",
      "Host-integrated function tools for AI provider execution"
    ],
    "targetEnvironment": [
      "Java"
    ]
  },
  "constructors": [
    {
      "package": "org.machanism.machai.gw.processor",
      "signature": "org.machanism.machai.gw.processor.Ghostwriter",
      "description": "Ghostwriter is the command-line entry point that parses arguments, loads configuration, selects the processing mode, and starts scans for guidance-driven or Act-based workflows.",
      "examples": [
        {
          "snippet": "java -jar gw.jar src/main [options]",
          "description": "Starts the Ghostwriter CLI entry point and provides a repository-relative scan directory. The Javadoc describes typical invocation as java -jar gw.jar <paths> [options], where matching targets can be repository-relative paths such as src/main or matcher expressions supported by java.nio.file.FileSystems#getPathMatcher(java.lang.String)."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.processor",
      "signature": "org.machanism.machai.gw.processor.GuidanceProcessor",
      "description": "GuidanceProcessor scans a project tree, extracts per-file @guidance directives through Reviewers, and dispatches the resulting prompts to a configured Genai provider.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.processor.GuidanceProcessor processor;\n// Configure runtime settings such as model selection, instructions, excludes, interactive mode, and scan targets, then scan one or more project-relative paths or path patterns.",
          "description": "The package documentation states that a Ghostwriter invocation constructs either a GuidanceProcessor or an ActProcessor, applies runtime settings such as model selection, instructions, excludes, interactive mode, and scan targets, and then scans project-relative paths or path patterns."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.processor",
      "signature": "org.machanism.machai.gw.processor.ActProcessor",
      "description": "ActProcessor loads TOML-defined acts, resolves inheritance and external act locations, and executes prompt episodes against matching files or directories.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.processor.ActProcessor processor;\n// Configure an Act workflow and scan targets so TOML-defined episodes can execute against matching files or directories.",
          "description": "Use ActProcessor when the workflow is driven by reusable Act templates rather than only embedded @guidance directives. The Javadoc identifies ActProcessor as the processor that runs Ghostwriter in Act mode."
        }
      ]
    }
  ],
  "features": [
    {
      "package": "org.machanism.machai.gw.processor",
      "name": "Process embedded guidance",
      "signature": "org.machanism.machai.gw.processor.GuidanceProcessor",
      "description": "Scans a project tree, extracts per-file @guidance directives through Reviewers, and dispatches the resulting prompts to a configured Genai. Guidance-driven execution discovers @guidance directives, gathers project layout metadata, builds repository-aware prompts, and applies generated output back to matching files.",
      "examples": [
        {
          "snippet": "java -jar gw.jar src/main [options]",
          "description": "Run Ghostwriter against a repository-relative path such as src/main so reviewer-supported files can be inspected for embedded @guidance directives and converted into prompts for AI-backed processing."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.processor",
      "name": "Execute Act workflows",
      "signature": "org.machanism.machai.gw.processor.ActProcessor",
      "description": "Runs Ghostwriter in Act mode. ActProcessor loads TOML-defined acts, resolves inheritance and external act locations, and executes prompt episodes against matching files or directories. Reusable Act templates define structured prompt workflows for repeated maintenance, review, and content-generation tasks.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.processor.ActProcessor processor;\n// Select a TOML-defined Act and execute its episodes against project-relative matching files or directories.",
          "description": "Use Act mode when a repeated maintenance, review, or content-generation task is defined as a structured Act template with episodes."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.reviewer",
      "name": "Review files for @guidance directives",
      "signature": "java.lang.String org.machanism.machai.gw.reviewer.Reviewer.perform(java.io.File projectDir, java.io.File file) throws java.io.IOException",
      "description": "Reviews a file and returns a formatted fragment, often including file content and/or extracted guidance, for use by the Ghostwriter pipeline. The package defines reviewer implementations for Java source, Markdown, HTML/XML, TypeScript, Python, PlantUML, and dedicated text guidance files. Implementations return null when no relevant guidance is present.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.reviewer.Reviewer reviewer;\njava.io.File projectDir;\njava.io.File file;\njava.lang.String promptFragment = reviewer.perform(projectDir, file);",
          "description": "Call the Reviewer SPI with the project root and candidate file. The returned prompt fragment can be forwarded to the Ghostwriter pipeline; a null return means the file does not contain actionable guidance."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.reviewer",
      "name": "Get supported reviewer extensions",
      "signature": "java.lang.String[] org.machanism.machai.gw.reviewer.Reviewer.getSupportedFileExtensions()",
      "description": "Returns the file extensions, without the dot, that a reviewer can process. Reviewer implementations cover Java, Markdown, HTML/XML, TypeScript, Python, PlantUML, and generic guidance text files.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.reviewer.Reviewer reviewer;\njava.lang.String[] extensions = reviewer.getSupportedFileExtensions();",
          "description": "Use the supported extensions to select which reviewer can process a candidate project artifact before attempting to extract @guidance directives."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.tools",
      "name": "Expose host-integrated function tools",
      "signature": "org.machanism.machai.gw.tools.FileFunctionTools, org.machanism.machai.gw.tools.CommandFunctionTools, org.machanism.machai.gw.tools.WebFunctionTools, org.machanism.machai.gw.tools.ActFunctionTools, org.machanism.machai.gw.tools.ProjectContextFunctionTools",
      "description": "Provides host-integrated function tool implementations used by Ghostwriter to expose local file-system, command-line, web, act-management, and project-context capabilities to AI providers. Tool infrastructure supports reading, writing, patching, and listing files; executing validated commands with bounded output and deny-list checks; retrieving web content and invoking REST endpoints; loading and triggering acts; maintaining project-scoped context variables; and signaling workflow transitions.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.tools.FileFunctionTools fileTools;\norg.machanism.machai.gw.tools.CommandFunctionTools commandTools;\norg.machanism.machai.gw.tools.WebFunctionTools webTools;\n// Register host-controlled tools with a configured Genai instance before prompt execution.",
          "description": "Use the tool registrars in a host-controlled execution model where working directories, configuration, security constraints, and network policies are supplied by the surrounding application."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.tools",
      "name": "Apply unified diff patches",
      "signature": "org.machanism.machai.gw.tools.PatchApplier",
      "description": "Utility to apply unified diff patches to text files. The tools package includes patch application support as part of controlled file-system access exposed during prompt execution.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.tools.PatchApplier patchApplier;\n// Apply a unified diff patch to a text file through the host-integrated file tool workflow.",
          "description": "Use patch application support when a generated workflow needs to update only selected parts of a text file while operating under the host-controlled file-system tool model."
        }
      ]
    }
  ],
  "customizations": [
    {
      "name": "org.machanism.machai.gw.reviewer.Reviewer",
      "package": "org.machanism.machai.gw.reviewer",
      "description": "Service-provider interface for components that scan project files and extract @guidance instructions for downstream processing. Implementations typically target a specific file format, understand that format's comment conventions, and produce a normalized prompt fragment that includes path context.",
      "type": "interface",
      "examples": [
        {
          "snippet": "public final class CustomReviewer implements org.machanism.machai.gw.reviewer.Reviewer {\n  public java.lang.String perform(java.io.File projectDir, java.io.File file) throws java.io.IOException { return null; }\n  public java.lang.String[] getSupportedFileExtensions() { return new java.lang.String[] { \"custom\" }; }\n}",
          "description": "Implement the Reviewer SPI to add support for a file format with its own guidance marker conventions. The perform method returns a formatted prompt fragment or null when no actionable guidance is present."
        }
      ]
    }
  ],
  "studs": [
    {
      "name": "org.machanism.machai.gw.reviewer.Reviewer",
      "package": "org.machanism.machai.gw.reviewer",
      "type": "interface",
      "description": "Service-provider interface for components that scan project files and extract @guidance instructions for downstream processing. Known implementing classes include HtmlReviewer, JavaReviewer, MarkdownReviewer, PumlReviewer, PythonReviewer, TextReviewer, and TypeScriptReviewer.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.reviewer.Reviewer reviewer;\njava.lang.String[] supported = reviewer.getSupportedFileExtensions();\njava.lang.String fragment = reviewer.perform(new java.io.File(\".\"), new java.io.File(\"README.md\"));",
          "description": "Use a Reviewer implementation to identify supported extensions and extract a Ghostwriter prompt fragment from a project file."
        }
      ],
      "implement": "org.machanism.machai.gw.reviewer.HtmlReviewer, org.machanism.machai.gw.reviewer.JavaReviewer, org.machanism.machai.gw.reviewer.MarkdownReviewer, org.machanism.machai.gw.reviewer.PumlReviewer, org.machanism.machai.gw.reviewer.PythonReviewer, org.machanism.machai.gw.reviewer.TextReviewer, org.machanism.machai.gw.reviewer.TypeScriptReviewer"
    }
  ],
  "examples": [
    {
      "title": "Run Ghostwriter against a repository path",
      "steps": [
        "Install or obtain the Ghostwriter executable JAR for org.machanism.machai:ghostwriter:1.2.0-SNAPSHOT from a Maven repository or project build output.",
        "Choose a project-relative scan target such as src/main, src/test, a documentation directory, or a matcher expression supported by java.nio.file.FileSystems#getPathMatcher(java.lang.String).",
        "Run java -jar gw.jar <paths> [options] from the repository working directory."
      ],
      "snippet": "java -jar gw.jar src/main [options]",
      "description": "The Javadoc usage notes describe a typical invocation that starts the CLI entry point and provides a scan directory or matcher expression. Ghostwriter operates directly on repository content rather than compiled project models."
    },
    {
      "title": "Use Reviewer SPI to extract guidance from a file",
      "snippet": "org.machanism.machai.gw.reviewer.Reviewer reviewer;\njava.io.File projectDir = new java.io.File(\".\");\njava.io.File file = new java.io.File(\"README.md\");\njava.lang.String promptFragment = reviewer.perform(projectDir, file);",
      "description": "A Reviewer accepts a project root directory and a candidate file, then returns a formatted prompt fragment or null when the file does not contain actionable guidance. Reviewer implementations are format-oriented and support Java source, Markdown, HTML/XML, TypeScript, Python, PlantUML, and dedicated text guidance files."
    },
    {
      "title": "Execute a reusable Act workflow",
      "snippet": "org.machanism.machai.gw.processor.ActProcessor processor;\n// Configure runtime settings, select a TOML-defined Act, and execute prompt episodes against matching files or directories.",
      "description": "ActProcessor resolves and executes TOML-defined Acts and their episodes. Use this scenario for repeated maintenance, review, and content-generation tasks represented as reusable Act templates."
    }
  ],
  "dependencies": [
    "org.machanism.machai:project-layout:1.2.0-SNAPSHOT",
    "org.machanism.machai:genai-client:1.2.0-SNAPSHOT",
    "commons-cli:commons-cli:1.11.0",
    "org.apache.commons:commons-lang3:3.20.0",
    "org.apache.maven.shared:maven-shared-utils:3.4.2",
    "org.jsoup:jsoup:1.22.1",
    "net.htmlparser.jericho:jericho-html:3.4",
    "org.apache.commons:commons-text:1.15.0",
    "org.apache.maven:maven-model:3.8.1",
    "org.slf4j:slf4j-api:2.0.17"
  ]
}