ReProm (Repository into Prompts)

reprom is a command-line tool (CLI) that compiles a specified directory structure and file contents into a single Markdown file.
It helps you share code with AI tools like ChatGPT more efficiently, without manually copying and pasting multiple files.

Main Features

• Directory Tree Generation: Displays folder structures in a tree-like format (similar to the tree command).
• Collecting File Contents: Gathers the contents of specified files into one Markdown output.
• Flexible Pre-/Post-Text: Insert any text (e.g., instructions for AI, or general messages) at the beginning or end of the output.
• Multiple Configuration Sets: Define various configurations in a single YAML file and switch between them easily.
• Character Usage Statistics: Outputs the total character count of the generated Markdown.
• Clipboard or File Output: Choose to copy the Markdown directly to your clipboard or save it to a .md file.

Installation

npm install --save-dev reprom

Or, using Yarn:

yarn add --dev reprom

Usage

1. Prepare a YAML Configuration File

First, create a YAML file (e.g., reprom.config.yaml) in your project root (or any directory).
Below is a sample with multiple configuration sets under configs:

configs:
  - name: "sample"
    preText: |
      This output is generated by the sample configuration. Below is the project structure.
    postText: |
      That concludes the output for the sample configuration.
      Let me know if you have any questions.
    targets:
      include:
        - "packages/core"
        - "packages/utils"
      exclude:
        - "**/node_modules"
      filePatterns:
        - "**/*.ts"
        - "**/*.js"
    tree:
      maxDepth: 5
      directoriesOnly: false
    output: "file"

  - name: "review"
    preText: |
      This output is generated by the review configuration. Please review the code in the directories below.
    postText: |
      Thank you for your review!
    targets:
      include:
        - "apps/www"
      exclude:
        - "**/node_modules"
      filePatterns:
        - "**/*.vue"
        - "**/*.js"
        - "**/*.ts"
    tree:
      maxDepth: 10
      directoriesOnly: false
    output: "clipboard"

Key Fields

• name: Identifier used when calling the configuration.
• preText / postText: Custom text to insert at the beginning or end of your final Markdown.
• targets:
  • include: Paths or directories to include.
  • exclude: Paths or directories to exclude.
  • filePatterns: File matching patterns (e.g., **/*.ts). Supports fast-glob style.
• tree:
  • maxDepth: Limit the directory tree display depth.
  • directoriesOnly: If true, displays directories only (no files).
• output: "file" writes the Markdown to a file; "clipboard" copies the Markdown to your clipboard.

2. Run the CLI

npx reprom --config=reprom.config.yaml --name=sample

• --config: Path to the YAML file (default: reprom.config.yaml).
• --name: The name of the configuration to use (matching configs[].name in the YAML).

If output: "file" is specified, a file (e.g., reprom-sample.md) will be generated.
If output: "clipboard" is specified, the Markdown is copied directly to your clipboard (no file is created).

3. Optional: Register a Script in package.json

Instead of typing the CLI flags every time, you can add scripts to your package.json:

{
  "scripts": {
    "export:sample": "reprom --config=reprom.config.yaml --name=sample",
    "export:review": "reprom --config=reprom.config.yaml --name=review"
  }
}

Then simply run:

npm run export:sample

(or yarn export:sample) to generate or copy the Markdown as configured.

---

Example Outputs

Below are several example outputs showing what reprom can produce in different scenarios. Each example highlights different configurations or usage patterns.

---

Example 1: Basic Configuration (Output to File)

npx reprom --config=reprom.config.yaml --name=sample

Result: A Markdown file (e.g., reprom-sample.md) containing:

This output is generated by the sample configuration. Below is the project structure.

# Directory Structure

packages
├── core
│ ├── index.ts
│ └── ...
└── utils
└── ...

# File Contents

## packages/core/index.ts

(Contents of index.ts)

## packages/core/anotherFile.js

(Contents of anotherFile.js)

(... repeats for each file matched by filePatterns ...)

That concludes the output for the sample configuration.
Let me know if you have any questions.

The console might show:

Total characters: 8342
Exported to reprom-sample.md for configuration "sample"

---

Example 2: Review Configuration (Output to Clipboard)

npx reprom --config=reprom.config.yaml --name=review

Result: No file is generated. Instead, the Markdown is copied to your clipboard.
You might see something like:

Total characters: 12567
Markdown has been copied to your clipboard for configuration "review".

When you paste it (e.g., into ChatGPT), you get:

This output is generated by the review configuration. Please review the code in the directories below.

# Directory Structure

apps
└── www
├── App.vue
├── main.js
└── ...

# File Contents

## apps/www/App.vue

<template>
  <div>Hello Vue!</div>
</template>

<script>
export default {
  name: "App"
};
</script>

(... repeats for each file ...)

Thank you for your review!

This is ready to be reviewed by an AI assistant or shared in any chat platform.

---

Example 3: Directories-Only Configuration

Suppose you have another config:

- name: "dirs-only"
  preText: "Below is the directory structure, showing only folders:"
  targets:
    include:
      - "src"
      - "tests"
    exclude:
      - "**/node_modules"
      - "**/*.md"
    filePatterns:
      - "**/*"
  tree:
    maxDepth: 3
    directoriesOnly: true
  output: "file"

Running:

npx reprom --config=reprom.config.yaml --name=dirs-only

Result: A file like reprom-dirs-only.md with a tree that omits files entirely, up to 3 levels deep:

Below is the directory structure, showing only folders:

# Directory Structure

src
├── components
│ └── ...
└── utils
└── ...
tests
└── unit
└── ...

# File Contents

(No files matched because `directoriesOnly` was set to true, so only folders are shown)

Here, the “File Contents” section may be empty (or very minimal) because we’re excluding actual files from the tree display.

---

Example 4: Large Project, Mixed File Types

Imagine a large project that includes .ts, .js, .json, and .yaml files. Your config might look like:

- name: "full-archive"
  preText: "Archiving all source files, including JSON/YAML configs."
  postText: "Please review the entire project above."
  targets:
    include:
      - "server"
      - "client"
      - "configs"
    exclude:
      - "**/node_modules"
      - "dist"
      - "**/*.log"
  filePatterns:
    - "**/*.ts"
    - "**/*.js"
    - "**/*.json"
    - "**/*.yaml"
  tree:
    maxDepth: 5
    directoriesOnly: false
  output: "file"

Running:

npx reprom --config=reprom.config.yaml --name=full-archive

Result: Potentially a very large Markdown file (e.g., reprom-full-archive.md) with multi-layer directory trees and numerous file contents. For instance:

Archiving all source files, including JSON/YAML configs.

# Directory Structure

server
├── src
│ ├── app.ts
│ └── routes
│ ├── index.ts
│ └── userRoutes.ts
└── package.json
client
├── src
│ ├── main.js
│ ├── components
│ └── ...
└── package.json
configs
├── app-settings.yaml
└── dev.settings.json

# File Contents

## server/src/app.ts

import express from 'express';
const app = express();
// ...

## server/src/routes/index.ts

export \* from './userRoutes';

## server/src/routes/userRoutes.ts

import { Router } from 'express';
const userRouter = Router();
// ...

## server/package.json

{
"name": "server",
"version": "1.0.0",
...
}

## configs/app-settings.yaml

database:
host: localhost
port: 5432
user: admin

# ...

## configs/dev.settings.json

{
"debug": true,
"logLevel": "verbose"
}

(... more files here ...)

Please review the entire project above.

This kind of output is ideal when you need a comprehensive snapshot of the entire repository.

---

Sharing with AI Tools (e.g., ChatGPT)

1. Run the appropriate reprom command (e.g., npx reprom --config=reprom.config.yaml --name=review)
2. If it’s set to clipboard, simply paste it into ChatGPT (or your chosen AI tool).
3. Provide any instructions, such as “Could you review the above code for potential issues?”

You can now share an entire codebase (or any subset) in one go.

---

When It’s Useful

• For Code Review Requests to AI Tired of copying multiple files for an AI assistant? Let reprom handle it in a single command.

• Sharing Project Structure with Teammates Combine a tree-like directory overview with the contents of crucial source files for clarity.

• Creating Onboarding or Handover Docs Effortlessly define which subdirectories or file types to include, producing a single, comprehensive reference document.

---

Author

Keisuke Nagakawa (永川 圭介) GitHub: KeisukeNagakawa

License

This library uses the MIT License.

Contributing

• Feel free to submit issues if you discover bugs or have feature requests.
• Pull Requests are welcome. Let’s discuss any substantial changes beforehand!

---

reprom: Simplify your code-sharing workflow with a single command. Enjoy!