docforagents 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,648 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import path3 from "path";
+import chalk2 from "chalk";
+import prompts2 from "prompts";
+
+// src/core/detector.ts
+import path from "path";
+import fs2 from "fs/promises";
+
+// src/utils/files.ts
+import fs from "fs/promises";
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJson(filePath) {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+async function readText(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+async function getTopLevelDirectories(targetPath, ignoredDirs = ["node_modules", ".git", "dist", "build", "target", "venv", ".venv", "__pycache__", ".docforagents", "knowledge"]) {
+  try {
+    const items = await fs.readdir(targetPath, { withFileTypes: true });
+    return items.filter((item) => item.isDirectory() && !ignoredDirs.includes(item.name)).map((item) => item.name);
+  } catch {
+    return [];
+  }
+}
+
+// src/core/detector.ts
+async function detectProject(targetPath) {
+  const absolutePath = path.resolve(targetPath);
+  let projectName = path.basename(absolutePath);
+  const packageJson = await readJson(path.join(absolutePath, "package.json"));
+  if (packageJson && packageJson.name) {
+    projectName = packageJson.name;
+  } else {
+    const cargoToml = await readText(path.join(absolutePath, "Cargo.toml"));
+    if (cargoToml) {
+      const match = cargoToml.match(/name\s*=\s*"([^"]+)"/);
+      if (match && match[1]) {
+        projectName = match[1];
+      }
+    }
+  }
+  const languages = [];
+  if (await exists(path.join(absolutePath, "package.json"))) {
+    const tsconfigExists = await exists(path.join(absolutePath, "tsconfig.json"));
+    if (tsconfigExists) {
+      languages.push("TypeScript", "JavaScript");
+    } else {
+      languages.push("JavaScript");
+    }
+  }
+  if (await exists(path.join(absolutePath, "requirements.txt")) || await exists(path.join(absolutePath, "pyproject.toml")) || await exists(path.join(absolutePath, "Pipfile")) || await exists(path.join(absolutePath, "setup.py"))) {
+    languages.push("Python");
+  }
+  if (await exists(path.join(absolutePath, "go.mod"))) {
+    languages.push("Go");
+  }
+  if (await exists(path.join(absolutePath, "Cargo.toml"))) {
+    languages.push("Rust");
+  }
+  if (await exists(path.join(absolutePath, "pom.xml")) || await exists(path.join(absolutePath, "build.gradle"))) {
+    languages.push("Java");
+  }
+  try {
+    const files = await fs2.readdir(absolutePath);
+    if (files.some((f) => f.endsWith(".csproj") || f.endsWith(".sln"))) {
+      languages.push("C#");
+    }
+  } catch {
+  }
+  const frameworks = [];
+  if (packageJson) {
+    const deps = {
+      ...packageJson.dependencies || {},
+      ...packageJson.devDependencies || {}
+    };
+    if (deps["next"]) frameworks.push("Next.js");
+    else if (deps["react-native"]) frameworks.push("React Native");
+    else if (deps["react"]) frameworks.push("React");
+    if (deps["nuxt"]) frameworks.push("Nuxt");
+    else if (deps["vue"]) frameworks.push("Vue");
+    if (deps["@angular/core"]) frameworks.push("Angular");
+    if (deps["svelte"] || deps["@sveltejs/kit"]) frameworks.push("Svelte");
+    if (deps["express"]) frameworks.push("Express");
+    if (deps["@nestjs/core"]) frameworks.push("NestJS");
+    if (deps["koa"]) frameworks.push("Koa");
+    if (deps["fastify"]) frameworks.push("Fastify");
+    if (deps["tailwindcss"]) frameworks.push("Tailwind CSS");
+  }
+  const pyprojectToml = await readText(path.join(absolutePath, "pyproject.toml"));
+  const reqsTxt = await readText(path.join(absolutePath, "requirements.txt"));
+  const pythonDeps = `${pyprojectToml || ""} ${reqsTxt || ""}`;
+  if (pythonDeps.includes("fastapi")) frameworks.push("FastAPI");
+  if (pythonDeps.includes("django")) frameworks.push("Django");
+  if (pythonDeps.includes("flask")) frameworks.push("Flask");
+  if (pythonDeps.includes("streamlit")) frameworks.push("Streamlit");
+  const goMod = await readText(path.join(absolutePath, "go.mod"));
+  if (goMod) {
+    if (goMod.includes("github.com/gin-gonic/gin")) frameworks.push("Gin");
+    if (goMod.includes("github.com/labstack/echo")) frameworks.push("Echo");
+    if (goMod.includes("github.com/gofiber/fiber")) frameworks.push("Fiber");
+  }
+  const cargoTomlStr = await readText(path.join(absolutePath, "Cargo.toml"));
+  if (cargoTomlStr) {
+    if (cargoTomlStr.includes("tokio")) frameworks.push("Tokio");
+    if (cargoTomlStr.includes("actix-web")) frameworks.push("Actix-Web");
+    if (cargoTomlStr.includes("axum")) frameworks.push("Axum");
+    if (cargoTomlStr.includes("rocket")) frameworks.push("Rocket");
+  }
+  const tools = [];
+  if (await exists(path.join(absolutePath, "Dockerfile")) || await exists(path.join(absolutePath, "docker-compose.yml"))) {
+    tools.push("Docker");
+  }
+  if (await exists(path.join(absolutePath, ".github/workflows"))) {
+    tools.push("GitHub Actions");
+  }
+  if (await exists(path.join(absolutePath, ".gitlab-ci.yml"))) {
+    tools.push("GitLab CI");
+  }
+  if (packageJson) {
+    const deps = { ...packageJson.dependencies || {}, ...packageJson.devDependencies || {} };
+    if (deps["prisma"]) tools.push("Prisma ORM");
+    if (deps["mongoose"]) tools.push("Mongoose (MongoDB)");
+    if (deps["sequelize"]) tools.push("Sequelize");
+    if (deps["typeorm"]) tools.push("TypeORM");
+    if (deps["pg"]) tools.push("PostgreSQL Client");
+    if (deps["sqlite3"]) tools.push("SQLite3 Client");
+  }
+  if (pythonDeps.includes("sqlalchemy")) tools.push("SQLAlchemy ORM");
+  if (pythonDeps.includes("tortoise-orm")) tools.push("Tortoise ORM");
+  const directories = await getTopLevelDirectories(absolutePath);
+  return {
+    projectName,
+    languages: Array.from(new Set(languages)),
+    frameworks: Array.from(new Set(frameworks)),
+    tools: Array.from(new Set(tools)),
+    directories
+  };
+}
+
+// src/core/generator.ts
+import fs3 from "fs/promises";
+import path2 from "path";
+
+// src/core/templates.ts
+function generateConfigJson(metadata) {
+  const config = {
+    $schema: "https://docforagents.org/schemas/v1/config.json",
+    version: "1.0.0",
+    project: {
+      name: metadata.projectName,
+      languages: metadata.languages,
+      frameworks: metadata.frameworks,
+      tools: metadata.tools
+    },
+    knowledgeDir: "knowledge",
+    exclude: [
+      "node_modules",
+      ".git",
+      "dist",
+      "build",
+      "target",
+      "venv",
+      ".venv",
+      "__pycache__",
+      ".docforagents/cache"
+    ],
+    rules: {
+      requireAdrForMajorChanges: false,
+      requireAgentsUpdateOnApiChange: true
+    }
+  };
+  return JSON.stringify(config, null, 2);
+}
+function generateRootAgentsMd(metadata) {
+  const languagesList = metadata.languages.map((l) => `- ${l}`).join("\n") || "- (None detected)";
+  const frameworksList = metadata.frameworks.map((f) => `- ${f}`).join("\n") || "- (None detected)";
+  const toolsList = metadata.tools.map((t) => `- ${t}`).join("\n") || "- (None detected)";
+  const directoryList = metadata.directories.map((dir) => `- [${dir}/](file://./${dir}/) \u2014 *Add responsibilities of this directory* (see [${dir}/AGENTS.md](file://./${dir}/AGENTS.md) for local rules)`).join("\n") || "- (No directories detected)";
+  return `# AGENTS.md \u2014 AI Agent Context Entry Point
+
+> [!NOTE]
+> **To AI Coding Agents:** This file serves as your primary landing page for understanding the architecture, rules, and entry points of the **${metadata.projectName}** project. Before executing tasks or modifications, review this page and follow the links to specific files.
+
+## Project Overview
+*Briefly describe what this project does, its goals, and its business context.*
+
+## Core Stack & Environment
+### Languages
+${languagesList}
+
+### Frameworks & Libraries
+${frameworksList}
+
+### Infrastructure & Tools
+${toolsList}
+
+---
+
+## Repository Map
+
+### Core Knowledge Base
+All architectural and domain-specific knowledge resides in the \`knowledge/\` directory:
+- [Architecture Overview](file://./knowledge/architecture/overview.md) \u2014 System components, data flow, design patterns.
+- [API Documentation](file://./knowledge/api/overview.md) \u2014 Endpoints, schemas, payloads.
+- [Architecture Decisions (ADRs)](file://./knowledge/decisions/README.md) \u2014 Why the project was built this way.
+- [Glossary of Terms](file://./knowledge/glossary/terms.md) \u2014 Domain vocabulary and definitions.
+- [Testing Guidelines](file://./knowledge/testing/overview.md) \u2014 Test setup, commands, and strategies.
+
+### Directory Structure
+${directoryList}
+
+---
+
+## Agent Guidelines & Conventions
+
+### 1. Read Before Write
+- Check the relevant local \`AGENTS.md\` inside directories you are editing.
+- Look at the [Architecture Decisions](file://./knowledge/decisions/README.md) to understand existing patterns (e.g. repository pattern, clean architecture).
+
+### 2. Standardized Changes
+- **API changes** MUST update [API Overview](file://./knowledge/api/overview.md) and local \`AGENTS.md\` interfaces.
+- **Architectural changes** require an Architecture Decision Record (ADR) under [Decisions](file://./knowledge/decisions/README.md).
+
+### 3. Verification
+- Always execute tests according to [Testing Guidelines](file://./knowledge/testing/overview.md) before declaring a task complete.
+`;
+}
+function generateFolderAgentsMd(folderName) {
+  return `# AGENTS.md \u2014 Local Directory Rules for \`${folderName}/\`
+
+> [!NOTE]
+> **To AI Coding Agents:** This file defines the responsibilities, entry points, and coding conventions specific to the \`${folderName}/\` directory. Adhere strictly to these guidelines when making modifications here.
+
+## Purpose & Responsibility
+*Describe the single responsibility of this directory (e.g. "Handles authentication endpoints and JWT verification").*
+
+## Core Entry Points
+- [\`index.ts\` or entry file](file://./index.ts) \u2014 *Describe what imports/exports this file exposes.*
+
+## Internal Dependencies & Imports
+- **Imports from other modules:** *Specify which parent modules this directory is allowed to import from.*
+- **Outward dependencies:** *What external npm/pip packages or databases does this folder communicate with?*
+
+## Conventions & Implementation Rules
+1. **Design Patterns**: *e.g., Use controllers for route handling, delegate business logic to services.*
+2. **Naming Conventions**: *e.g., Suffix all services with \`Service\` (e.g., \`AuthService\`).*
+3. **Error Handling**: *e.g., Do not throw raw errors; wrap in \`AppError\` with status codes.*
+4. **Security**: *e.g., Ensure JWT middleware is applied to all new route configurations.*
+`;
+}
+function generateArchitectureOverviewMd(projectName) {
+  return `# Architecture Overview \u2014 ${projectName}
+
+## System Overview
+*Provide a high-level description of how this system is put together. Mention if it is a monolith, microservices, SPA, Serverless, etc.*
+
+## Core Components
+*List the primary components/modules of the application and their relationships.*
+
+\`\`\`mermaid
+graph TD
+    Client[Client / Frontend] --> API[API Gateway / Backend]
+    API --> DB[(Database)]
+    API --> Cache[(Cache / Redis)]
+\`\`\`
+
+## Core Design Patterns
+*Outline the engineering patterns used in this codebase (e.g., Clean Architecture, MVC, CQRS, Repository Pattern, Dependency Injection).*
+
+- **Pattern A**: *Description of how it is applied.*
+- **Pattern B**: *Description of how it is applied.*
+
+## Data Flows
+1. **Request Flow**: *Trace a typical request from the frontend to database and back.*
+2. **Background Processes**: *Describe queues, cron jobs, event-driven pipelines if applicable.*
+`;
+}
+function generateApiOverviewMd(projectName) {
+  return `# API Reference \u2014 ${projectName}
+
+## Authentication & Authorization
+*Describe how clients authenticate to the APIs (e.g. Bearer tokens, cookies, API keys).*
+
+\`\`\`http
+Authorization: Bearer <token>
+\`\`\`
+
+## Base URLs
+- Development: \`http://localhost:3000/api\`
+- Staging: \`https://staging.api.example.com/v1\`
+- Production: \`https://api.example.com/v1\`
+
+## Main Endpoints
+
+### 1. Health check
+- **Method / Path**: \`GET /health\`
+- **Description**: Returns the system status.
+- **Response**:
+  \`\`\`json
+  {
+    "status": "healthy",
+    "timestamp": "2026-07-27T18:00:00Z"
+  }
+  \`\`\`
+
+### 2. [Endpoint Name]
+- **Method / Path**: \`POST /resource\`
+- **Headers**: \`Content-Type: application/json\`
+- **Request Body**:
+  \`\`\`json
+  {
+    "name": "example"
+  }
+  \`\`\`
+- **Response (201 Created)**:
+  \`\`\`json
+  {
+    "id": "uuid-1234",
+    "name": "example"
+  }
+  \`\`\`
+`;
+}
+function generateDecisionsReadmeMd(projectName) {
+  return `# Architectural Decision Records (ADR)
+
+This folder contains the history of major design and architectural choices made in the **${projectName}** repository.
+
+## What is an ADR?
+An Architectural Decision Record (ADR) is a document that captures an important architectural decision, including the context in which the decision was made, the consequences of the decision, and its current status (Proposed, Accepted, Superceded).
+
+## ADR Index
+
+| ADR # | Title | Status | Date |
+|-------|-------|--------|------|
+| [ADR-001](file://./001-initial-architecture.md) | Initial Architecture Scaffolding | Accepted | 2026-07-27 |
+
+*To create a new ADR, copy the template format and name it sequentially (e.g. \`002-use-redis-caching.md\`).*
+`;
+}
+function generateGlossaryMd() {
+  return `# Domain Glossary
+
+Define the core business terms and domain models used in this repository. This reduces ambiguity for AI agents and onboarding engineers.
+
+| Term | Definition | Context / Usage |
+|------|------------|-----------------|
+| **ADR** | Architecture Decision Record. | Engineering workflow documentation |
+| **Agent** | An autonomous AI agent performing operations on code. | AI Coding context |
+| **Knowledge Layer** | The directory containing machine-readable code specification and guidelines. | Standard repo structure |
+`;
+}
+function generateTestingOverviewMd(metadata) {
+  return `# Testing Guidelines
+
+## Running Tests
+*Provide the exact commands required to execute the test suite.*
+
+\`\`\`bash
+# Run unit tests
+npm run test
+# Run integration / e2e tests
+npm run test:e2e
+\`\`\`
+
+## Testing Philosophy
+- **Unit Tests**: Describe where unit tests are placed (e.g., next to the file as \`*.test.ts\` or in a \`test/\` directory).
+- **Integration Tests**: Describe how to test integrations with mock services/databases.
+- **Coverage**: Target code coverage expectations.
+
+## Creating New Tests
+- Use the standard test framework configurations.
+- Mock external network calls using MSW, nock, or custom mock suites.
+`;
+}
+
+// src/core/generator.ts
+async function generateKnowledgeBase(targetPath, metadata, options = {}) {
+  const absolutePath = path2.resolve(targetPath);
+  const filesCreated = [];
+  const filesSkipped = [];
+  const writeFileSafely = async (filePath, content) => {
+    const relativePath = path2.relative(absolutePath, filePath);
+    const fileExists = await exists(filePath);
+    if (fileExists && !options.forceOverwrite) {
+      filesSkipped.push(relativePath);
+      return;
+    }
+    await fs3.mkdir(path2.dirname(filePath), { recursive: true });
+    await fs3.writeFile(filePath, content, "utf-8");
+    filesCreated.push(relativePath);
+  };
+  const configPath = path2.join(absolutePath, ".docforagents", "config.json");
+  await writeFileSafely(configPath, generateConfigJson(metadata));
+  const rootAgentsPath = path2.join(absolutePath, "AGENTS.md");
+  await writeFileSafely(rootAgentsPath, generateRootAgentsMd(metadata));
+  const knowledgeDir = path2.join(absolutePath, "knowledge");
+  await writeFileSafely(
+    path2.join(knowledgeDir, "architecture", "overview.md"),
+    generateArchitectureOverviewMd(metadata.projectName)
+  );
+  await writeFileSafely(
+    path2.join(knowledgeDir, "api", "overview.md"),
+    generateApiOverviewMd(metadata.projectName)
+  );
+  await writeFileSafely(
+    path2.join(knowledgeDir, "decisions", "README.md"),
+    generateDecisionsReadmeMd(metadata.projectName)
+  );
+  await writeFileSafely(
+    path2.join(knowledgeDir, "glossary", "terms.md"),
+    generateGlossaryMd()
+  );
+  await writeFileSafely(
+    path2.join(knowledgeDir, "testing", "overview.md"),
+    generateTestingOverviewMd(metadata)
+  );
+  const foldersToGenerate = options.folderAgents !== void 0 ? options.folderAgents : options.skipFolderAgents ? [] : metadata.directories;
+  for (const dir of foldersToGenerate) {
+    if (dir.startsWith(".")) {
+      continue;
+    }
+    const folderAgentsPath = path2.join(absolutePath, dir, "AGENTS.md");
+    await writeFileSafely(folderAgentsPath, generateFolderAgentsMd(dir));
+  }
+  return {
+    filesCreated,
+    filesSkipped
+  };
+}
+
+// src/utils/prompts.ts
+import chalk from "chalk";
+import prompts from "prompts";
+function printFolderRecommendation(projectName, directories) {
+  if (directories.length === 0) return;
+  console.log(chalk.bold(`
+\u{1F4C1} ${projectName}`));
+  const maxToShow = 5;
+  const dirsToShow = directories.slice(0, maxToShow);
+  const remaining = directories.length - maxToShow;
+  dirsToShow.forEach((dir, idx) => {
+    const isLast = idx === dirsToShow.length - 1 && remaining <= 0;
+    const branch = isLast ? "\u2514\u2500\u2500" : "\u251C\u2500\u2500";
+    console.log(`  ${branch} \u{1F4C1} ${dir}/`);
+    console.log(`  ${isLast ? "   " : "\u2502  "}  \u2514\u2500\u2500 \u{1F4DD} ${chalk.green("AGENTS.md")} ${chalk.gray("(recommended)")}`);
+  });
+  if (remaining > 0) {
+    console.log(`  \u2514\u2500\u2500 ${chalk.gray(`... and ${remaining} more folders`)}`);
+  }
+  console.log();
+}
+async function configureFolderAgentsCreation(projectName, directories) {
+  const filteredDirs = directories.filter((dir) => !dir.startsWith("."));
+  if (filteredDirs.length === 0) {
+    return [];
+  }
+  printFolderRecommendation(projectName, filteredDirs);
+  const isLargeProject = filteredDirs.length > 5;
+  if (isLargeProject) {
+    console.log(
+      chalk.yellow(
+        `\u26A0\uFE0F  This is a large project with ${filteredDirs.length} folders recommended for AGENTS.md creation.`
+      )
+    );
+    console.log(
+      chalk.gray(
+        `   Auto-creating rules via LLM for all folders may consume a significant amount of time and tokens.
+`
+      )
+    );
+  }
+  const response = await prompts(
+    {
+      type: "select",
+      name: "action",
+      message: "Configure folder-level AGENTS.md creation:",
+      choices: [
+        {
+          title: `Auto-create in all recommended folders (${filteredDirs.length} folders)`,
+          value: "all"
+        },
+        {
+          title: "Manual control (select specific folders)",
+          value: "manual"
+        },
+        {
+          title: "Skip folder-level AGENTS.md entirely",
+          value: "skip"
+        }
+      ],
+      initial: 0
+    },
+    {
+      onCancel: () => {
+        console.log(chalk.yellow("\nOperation cancelled."));
+        process.exit(0);
+      }
+    }
+  );
+  if (response.action === "all") {
+    return filteredDirs;
+  }
+  if (response.action === "skip") {
+    return [];
+  }
+  if (response.action === "manual") {
+    const manualResponse = await prompts(
+      {
+        type: "multiselect",
+        name: "folders",
+        message: "Select subdirectories to create AGENTS.md in:",
+        choices: filteredDirs.map((dir) => ({
+          title: `${dir}/`,
+          value: dir,
+          selected: true
+        })),
+        hint: "- Space to select/deselect, Enter to confirm",
+        min: 0
+      },
+      {
+        onCancel: () => {
+          console.log(chalk.yellow("\nOperation cancelled."));
+          process.exit(0);
+        }
+      }
+    );
+    return manualResponse.folders || [];
+  }
+  return [];
+}
+
+// src/commands/init.ts
+async function handleInit(targetDir = ".", options = {}) {
+  const resolvedPath = path3.resolve(targetDir);
+  console.log(chalk2.bold.cyan("\n\u{1F50D} Scanning repository for docforagents initialization..."));
+  console.log(chalk2.gray(`Path: ${resolvedPath}
+`));
+  let metadata;
+  try {
+    metadata = await detectProject(resolvedPath);
+  } catch (error) {
+    console.error(chalk2.red("Error scanning project:"), error);
+    process.exit(1);
+  }
+  console.log(chalk2.bold("Detected stack:"));
+  console.log(`  Project Name: ${chalk2.green(metadata.projectName)}`);
+  console.log(`  Languages:    ${chalk2.blue(metadata.languages.join(", ") || "None detected")}`);
+  console.log(`  Frameworks:   ${chalk2.blue(metadata.frameworks.join(", ") || "None detected")}`);
+  console.log(`  Tools/Infra:  ${chalk2.blue(metadata.tools.join(", ") || "None detected")}`);
+  console.log(`  Directories:  ${chalk2.blue(metadata.directories.join(", ") || "None detected")}
+`);
+  let projectName = metadata.projectName;
+  let selectedFolders = metadata.directories.filter((dir) => !dir.startsWith("."));
+  let proceed = true;
+  if (!options.yes) {
+    const nameResponse = await prompts2(
+      {
+        type: "text",
+        name: "projectName",
+        message: "Customize project name:",
+        initial: projectName
+      },
+      {
+        onCancel: () => {
+          console.log(chalk2.yellow("\nInitialization cancelled."));
+          process.exit(0);
+        }
+      }
+    );
+    projectName = nameResponse.projectName ?? projectName;
+    selectedFolders = await configureFolderAgentsCreation(projectName, metadata.directories);
+    const proceedResponse = await prompts2(
+      {
+        type: "confirm",
+        name: "proceed",
+        message: "Proceed to write standard knowledge layer?",
+        initial: true
+      },
+      {
+        onCancel: () => {
+          console.log(chalk2.yellow("\nInitialization cancelled."));
+          process.exit(0);
+        }
+      }
+    );
+    proceed = proceedResponse.proceed ?? proceed;
+  }
+  if (!proceed) {
+    console.log(chalk2.yellow("\nInitialization aborted."));
+    return;
+  }
+  metadata.projectName = projectName;
+  console.log(chalk2.cyan("\n\u270D\uFE0F  Writing knowledge base..."));
+  try {
+    const result = await generateKnowledgeBase(resolvedPath, metadata, {
+      forceOverwrite: options.force,
+      folderAgents: selectedFolders
+    });
+    if (result.filesCreated.length > 0) {
+      console.log(chalk2.bold.green(`
+Successfully created ${result.filesCreated.length} files:`));
+      result.filesCreated.forEach((f) => console.log(`  ${chalk2.green("\u2713")} ${f}`));
+    }
+    if (result.filesSkipped.length > 0) {
+      console.log(chalk2.bold.yellow(`
+Skipped ${result.filesSkipped.length} existing files (use --force or -f to overwrite):`));
+      result.filesSkipped.forEach((f) => console.log(`  ${chalk2.yellow("-")} ${f}`));
+    }
+    console.log(chalk2.bold.cyan("\n\u{1F389} Knowledge Layer Scaffolded successfully!"));
+    console.log("Your repository is now machine-readable for AI agents. Open root " + chalk2.bold.green("AGENTS.md") + " to get started.\n");
+  } catch (error) {
+    console.error(chalk2.red("\nError generating files:"), error);
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("docforagents").description("Open-source AI-native knowledge specification and tooling for software repositories").version("0.1.0");
+program.command("init").description("Scaffold the AI-native knowledge specification in a repository").argument("[path]", "Path to the project directory", ".").option("-y, --yes", "Skip interactive prompts and use detected defaults").option("-f, --force", "Overwrite existing knowledge specification files if they exist").action(async (targetDir, options) => {
+  await handleInit(targetDir, options);
+});
+program.parse(process.argv);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/commands/init.ts","../src/core/detector.ts","../src/utils/files.ts","../src/core/generator.ts","../src/core/templates.ts","../src/utils/prompts.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { handleInit } from \"./commands/init\";\n// import { handleAnalyze } from \"./commands/analyze\";\n\nconst program = new Command();\n\nprogram\n  .name(\"docforagents\")\n  .description(\"Open-source AI-native knowledge specification and tooling for software repositories\")\n  .version(\"0.1.0\");\n\nprogram\n  .command(\"init\")\n  .description(\"Scaffold the AI-native knowledge specification in a repository\")\n  .argument(\"[path]\", \"Path to the project directory\", \".\")\n  .option(\"-y, --yes\", \"Skip interactive prompts and use detected defaults\")\n  .option(\"-f, --force\", \"Overwrite existing knowledge specification files if they exist\")\n  .action(async (targetDir, options) => {\n    await handleInit(targetDir, options);\n  });\n\n// program\n//   .command(\"analyze\")\n//   .description(\"Scan the repository codebase and generate AI documentation files\")\n//   .argument(\"[path]\", \"Path to the project directory\", \".\")\n//   .option(\"-y, --yes\", \"Skip interactive prompts and generate for all recommended folders\")\n//   .option(\"--skip-folders\", \"Skip generating folder-level AGENTS.md rule files\")\n//   .action(async (targetDir, options) => {\n//     await handleAnalyze(targetDir, options);\n//   });\n\nprogram.parse(process.argv);\n","import path from \"path\";\nimport chalk from \"chalk\";\nimport prompts from \"prompts\";\nimport { detectProject } from \"../core/detector\";\nimport { generateKnowledgeBase } from \"../core/generator\";\nimport { configureFolderAgentsCreation } from \"../utils/prompts\";\n\nexport interface InitOptions {\n  yes?: boolean;\n  force?: boolean;\n}\n\n/**\n * Handle the 'init' command.\n */\nexport async function handleInit(targetDir: string = \".\", options: InitOptions = {}): Promise<void> {\n  const resolvedPath = path.resolve(targetDir);\n  \n  console.log(chalk.bold.cyan(\"\\n🔍 Scanning repository for docforagents initialization...\"));\n  console.log(chalk.gray(`Path: ${resolvedPath}\\n`));\n\n  // 1. Detect project details\n  let metadata;\n  try {\n    metadata = await detectProject(resolvedPath);\n  } catch (error) {\n    console.error(chalk.red(\"Error scanning project:\"), error);\n    process.exit(1);\n  }\n\n  // Log detected items\n  console.log(chalk.bold(\"Detected stack:\"));\n  console.log(`  Project Name: ${chalk.green(metadata.projectName)}`);\n  console.log(`  Languages:    ${chalk.blue(metadata.languages.join(\", \") || \"None detected\")}`);\n  console.log(`  Frameworks:   ${chalk.blue(metadata.frameworks.join(\", \") || \"None detected\")}`);\n  console.log(`  Tools/Infra:  ${chalk.blue(metadata.tools.join(\", \") || \"None detected\")}`);\n  console.log(`  Directories:  ${chalk.blue(metadata.directories.join(\", \") || \"None detected\")}\\n`);\n\n  let projectName = metadata.projectName;\n  let selectedFolders: string[] = metadata.directories.filter(dir => !dir.startsWith(\".\"));\n  let proceed = true;\n\n  // 2. Interactive Prompts (unless --yes flag is passed)\n  if (!options.yes) {\n    const nameResponse = await prompts(\n      {\n        type: \"text\",\n        name: \"projectName\",\n        message: \"Customize project name:\",\n        initial: projectName,\n      },\n      {\n        onCancel: () => {\n          console.log(chalk.yellow(\"\\nInitialization cancelled.\"));\n          process.exit(0);\n        }\n      }\n    );\n\n    projectName = nameResponse.projectName ?? projectName;\n\n    // Use interactive folder config helper\n    selectedFolders = await configureFolderAgentsCreation(projectName, metadata.directories);\n\n    const proceedResponse = await prompts(\n      {\n        type: \"confirm\",\n        name: \"proceed\",\n        message: \"Proceed to write standard knowledge layer?\",\n        initial: true,\n      },\n      {\n        onCancel: () => {\n          console.log(chalk.yellow(\"\\nInitialization cancelled.\"));\n          process.exit(0);\n        }\n      }\n    );\n\n    proceed = proceedResponse.proceed ?? proceed;\n  }\n\n  if (!proceed) {\n    console.log(chalk.yellow(\"\\nInitialization aborted.\"));\n    return;\n  }\n\n  // Update metadata with customized project name\n  metadata.projectName = projectName;\n\n  // 3. Generate files\n  console.log(chalk.cyan(\"\\n✍️  Writing knowledge base...\"));\n  \n  try {\n    const result = await generateKnowledgeBase(resolvedPath, metadata, {\n      forceOverwrite: options.force,\n      folderAgents: selectedFolders,\n    });\n\n    // 4. Summarize results\n    if (result.filesCreated.length > 0) {\n      console.log(chalk.bold.green(`\\nSuccessfully created ${result.filesCreated.length} files:`));\n      result.filesCreated.forEach(f => console.log(`  ${chalk.green(\"✓\")} ${f}`));\n    }\n\n    if (result.filesSkipped.length > 0) {\n      console.log(chalk.bold.yellow(`\\nSkipped ${result.filesSkipped.length} existing files (use --force or -f to overwrite):`));\n      result.filesSkipped.forEach(f => console.log(`  ${chalk.yellow(\"-\")} ${f}`));\n    }\n\n    console.log(chalk.bold.cyan(\"\\n🎉 Knowledge Layer Scaffolded successfully!\"));\n    console.log(\"Your repository is now machine-readable for AI agents. Open root \" + chalk.bold.green(\"AGENTS.md\") + \" to get started.\\n\");\n\n  } catch (error) {\n    console.error(chalk.red(\"\\nError generating files:\"), error);\n    process.exit(1);\n  }\n}\n","import path from \"path\";\nimport fs from \"fs/promises\";\nimport { exists, readJson, readText, getTopLevelDirectories } from \"../utils/files\";\n\nexport interface ProjectMetadata {\n  projectName: string;\n  languages: string[];\n  frameworks: string[];\n  tools: string[];\n  directories: string[];\n}\n\n/**\n * Scan a repository path to detect project configurations.\n */\nexport async function detectProject(targetPath: string): Promise<ProjectMetadata> {\n  const absolutePath = path.resolve(targetPath);\n  \n  // 1. Resolve Project Name\n  let projectName = path.basename(absolutePath);\n  const packageJson = await readJson(path.join(absolutePath, \"package.json\"));\n  if (packageJson && packageJson.name) {\n    projectName = packageJson.name;\n  } else {\n    // Try to get Cargo.toml project name\n    const cargoToml = await readText(path.join(absolutePath, \"Cargo.toml\"));\n    if (cargoToml) {\n      const match = cargoToml.match(/name\\s*=\\s*\"([^\"]+)\"/);\n      if (match && match[1]) {\n        projectName = match[1];\n      }\n    }\n  }\n\n  // 2. Detect Languages\n  const languages: string[] = [];\n  \n  if (await exists(path.join(absolutePath, \"package.json\"))) {\n    // Determine if it is TS or JS\n    const tsconfigExists = await exists(path.join(absolutePath, \"tsconfig.json\"));\n    if (tsconfigExists) {\n      languages.push(\"TypeScript\", \"JavaScript\");\n    } else {\n      languages.push(\"JavaScript\");\n    }\n  }\n  \n  if (\n    (await exists(path.join(absolutePath, \"requirements.txt\"))) ||\n    (await exists(path.join(absolutePath, \"pyproject.toml\"))) ||\n    (await exists(path.join(absolutePath, \"Pipfile\"))) ||\n    (await exists(path.join(absolutePath, \"setup.py\")))\n  ) {\n    languages.push(\"Python\");\n  }\n\n  if (await exists(path.join(absolutePath, \"go.mod\"))) {\n    languages.push(\"Go\");\n  }\n\n  if (await exists(path.join(absolutePath, \"Cargo.toml\"))) {\n    languages.push(\"Rust\");\n  }\n\n  if (\n    (await exists(path.join(absolutePath, \"pom.xml\"))) ||\n    (await exists(path.join(absolutePath, \"build.gradle\")))\n  ) {\n    languages.push(\"Java\");\n  }\n\n  // Scan root for csproj files\n  try {\n    const files = await fs.readdir(absolutePath);\n    if (files.some(f => f.endsWith(\".csproj\") || f.endsWith(\".sln\"))) {\n      languages.push(\"C#\");\n    }\n  } catch {\n    // Ignore read errors\n  }\n\n  // 3. Detect Frameworks\n  const frameworks: string[] = [];\n  \n  // JS/TS dependencies scan\n  if (packageJson) {\n    const deps = {\n      ...(packageJson.dependencies || {}),\n      ...(packageJson.devDependencies || {}),\n    };\n    \n    if (deps[\"next\"]) frameworks.push(\"Next.js\");\n    else if (deps[\"react-native\"]) frameworks.push(\"React Native\");\n    else if (deps[\"react\"]) frameworks.push(\"React\");\n    \n    if (deps[\"nuxt\"]) frameworks.push(\"Nuxt\");\n    else if (deps[\"vue\"]) frameworks.push(\"Vue\");\n    \n    if (deps[\"@angular/core\"]) frameworks.push(\"Angular\");\n    if (deps[\"svelte\"] || deps[\"@sveltejs/kit\"]) frameworks.push(\"Svelte\");\n    \n    if (deps[\"express\"]) frameworks.push(\"Express\");\n    if (deps[\"@nestjs/core\"]) frameworks.push(\"NestJS\");\n    if (deps[\"koa\"]) frameworks.push(\"Koa\");\n    if (deps[\"fastify\"]) frameworks.push(\"Fastify\");\n    if (deps[\"tailwindcss\"]) frameworks.push(\"Tailwind CSS\");\n  }\n\n  // Python dependencies scan\n  const pyprojectToml = await readText(path.join(absolutePath, \"pyproject.toml\"));\n  const reqsTxt = await readText(path.join(absolutePath, \"requirements.txt\"));\n  const pythonDeps = `${pyprojectToml || \"\"} ${reqsTxt || \"\"}`;\n  \n  if (pythonDeps.includes(\"fastapi\")) frameworks.push(\"FastAPI\");\n  if (pythonDeps.includes(\"django\")) frameworks.push(\"Django\");\n  if (pythonDeps.includes(\"flask\")) frameworks.push(\"Flask\");\n  if (pythonDeps.includes(\"streamlit\")) frameworks.push(\"Streamlit\");\n\n  // Go dependencies scan\n  const goMod = await readText(path.join(absolutePath, \"go.mod\"));\n  if (goMod) {\n    if (goMod.includes(\"github.com/gin-gonic/gin\")) frameworks.push(\"Gin\");\n    if (goMod.includes(\"github.com/labstack/echo\")) frameworks.push(\"Echo\");\n    if (goMod.includes(\"github.com/gofiber/fiber\")) frameworks.push(\"Fiber\");\n  }\n\n  // Rust dependencies scan\n  const cargoTomlStr = await readText(path.join(absolutePath, \"Cargo.toml\"));\n  if (cargoTomlStr) {\n    if (cargoTomlStr.includes(\"tokio\")) frameworks.push(\"Tokio\");\n    if (cargoTomlStr.includes(\"actix-web\")) frameworks.push(\"Actix-Web\");\n    if (cargoTomlStr.includes(\"axum\")) frameworks.push(\"Axum\");\n    if (cargoTomlStr.includes(\"rocket\")) frameworks.push(\"Rocket\");\n  }\n\n  // 4. Detect Tools & Infrastructure\n  const tools: string[] = [];\n  \n  if (await exists(path.join(absolutePath, \"Dockerfile\")) || await exists(path.join(absolutePath, \"docker-compose.yml\"))) {\n    tools.push(\"Docker\");\n  }\n  if (await exists(path.join(absolutePath, \".github/workflows\"))) {\n    tools.push(\"GitHub Actions\");\n  }\n  if (await exists(path.join(absolutePath, \".gitlab-ci.yml\"))) {\n    tools.push(\"GitLab CI\");\n  }\n\n  // Check common ORMs or DB libraries\n  if (packageJson) {\n    const deps = { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) };\n    if (deps[\"prisma\"]) tools.push(\"Prisma ORM\");\n    if (deps[\"mongoose\"]) tools.push(\"Mongoose (MongoDB)\");\n    if (deps[\"sequelize\"]) tools.push(\"Sequelize\");\n    if (deps[\"typeorm\"]) tools.push(\"TypeORM\");\n    if (deps[\"pg\"]) tools.push(\"PostgreSQL Client\");\n    if (deps[\"sqlite3\"]) tools.push(\"SQLite3 Client\");\n  }\n  if (pythonDeps.includes(\"sqlalchemy\")) tools.push(\"SQLAlchemy ORM\");\n  if (pythonDeps.includes(\"tortoise-orm\")) tools.push(\"Tortoise ORM\");\n\n  // 5. Scan directories for local AGENTS.md candidates\n  const directories = await getTopLevelDirectories(absolutePath);\n\n  return {\n    projectName,\n    languages: Array.from(new Set(languages)),\n    frameworks: Array.from(new Set(frameworks)),\n    tools: Array.from(new Set(tools)),\n    directories,\n  };\n}\n","import fs from \"fs/promises\";\nimport path from \"path\";\n\n/**\n * Check if a file or directory exists at the given path.\n */\nexport async function exists(targetPath: string): Promise<boolean> {\n  try {\n    await fs.access(targetPath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Read and parse JSON file safely. Returns null if error or file doesn't exist.\n */\nexport async function readJson<T = any>(filePath: string): Promise<T | null> {\n  try {\n    const content = await fs.readFile(filePath, \"utf-8\");\n    return JSON.parse(content) as T;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Read text file safely. Returns null if error or file doesn't exist.\n */\nexport async function readText(filePath: string): Promise<string | null> {\n  try {\n    return await fs.readFile(filePath, \"utf-8\");\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Get all top-level directories in targetPath, excluding common ignore paths.\n */\nexport async function getTopLevelDirectories(\n  targetPath: string,\n  ignoredDirs: string[] = [\"node_modules\", \".git\", \"dist\", \"build\", \"target\", \"venv\", \".venv\", \"__pycache__\", \".docforagents\", \"knowledge\"]\n): Promise<string[]> {\n  try {\n    const items = await fs.readdir(targetPath, { withFileTypes: true });\n    return items\n      .filter((item) => item.isDirectory() && !ignoredDirs.includes(item.name))\n      .map((item) => item.name);\n  } catch {\n    return [];\n  }\n}\n","import fs from \"fs/promises\";\nimport path from \"path\";\nimport { ProjectMetadata } from \"./detector\";\nimport { exists } from \"../utils/files\";\nimport {\n  generateConfigJson,\n  generateRootAgentsMd,\n  generateFolderAgentsMd,\n  generateArchitectureOverviewMd,\n  generateApiOverviewMd,\n  generateDecisionsReadmeMd,\n  generateGlossaryMd,\n  generateTestingOverviewMd,\n} from \"./templates\";\n\nexport interface GenerationResult {\n  filesCreated: string[];\n  filesSkipped: string[];\n}\n\n/**\n * Generate the standard docforagents layout in the target project path.\n */\nexport async function generateKnowledgeBase(\n  targetPath: string,\n  metadata: ProjectMetadata,\n  options: { forceOverwrite?: boolean; skipFolderAgents?: boolean; folderAgents?: string[] } = {}\n): Promise<GenerationResult> {\n  const absolutePath = path.resolve(targetPath);\n  const filesCreated: string[] = [];\n  const filesSkipped: string[] = [];\n\n  // Helper to safely write a file and track results\n  const writeFileSafely = async (filePath: string, content: string) => {\n    const relativePath = path.relative(absolutePath, filePath);\n    const fileExists = await exists(filePath);\n    \n    if (fileExists && !options.forceOverwrite) {\n      filesSkipped.push(relativePath);\n      return;\n    }\n\n    // Ensure parent directory exists\n    await fs.mkdir(path.dirname(filePath), { recursive: true });\n    await fs.writeFile(filePath, content, \"utf-8\");\n    filesCreated.push(relativePath);\n  };\n\n  // 1. Create root configurations & entry points\n  const configPath = path.join(absolutePath, \".docforagents\", \"config.json\");\n  await writeFileSafely(configPath, generateConfigJson(metadata));\n\n  const rootAgentsPath = path.join(absolutePath, \"AGENTS.md\");\n  await writeFileSafely(rootAgentsPath, generateRootAgentsMd(metadata));\n\n  // 2. Create knowledge base directory files\n  const knowledgeDir = path.join(absolutePath, \"knowledge\");\n  \n  await writeFileSafely(\n    path.join(knowledgeDir, \"architecture\", \"overview.md\"),\n    generateArchitectureOverviewMd(metadata.projectName)\n  );\n\n  await writeFileSafely(\n    path.join(knowledgeDir, \"api\", \"overview.md\"),\n    generateApiOverviewMd(metadata.projectName)\n  );\n\n  await writeFileSafely(\n    path.join(knowledgeDir, \"decisions\", \"README.md\"),\n    generateDecisionsReadmeMd(metadata.projectName)\n  );\n\n  await writeFileSafely(\n    path.join(knowledgeDir, \"glossary\", \"terms.md\"),\n    generateGlossaryMd()\n  );\n\n  await writeFileSafely(\n    path.join(knowledgeDir, \"testing\", \"overview.md\"),\n    generateTestingOverviewMd(metadata)\n  );\n\n  // 3. Create folder-level AGENTS.md files\n  const foldersToGenerate = options.folderAgents !== undefined\n    ? options.folderAgents\n    : (options.skipFolderAgents ? [] : metadata.directories);\n\n  for (const dir of foldersToGenerate) {\n    if (dir.startsWith(\".\")) {\n      continue;\n    }\n    const folderAgentsPath = path.join(absolutePath, dir, \"AGENTS.md\");\n    await writeFileSafely(folderAgentsPath, generateFolderAgentsMd(dir));\n  }\n\n  return {\n    filesCreated,\n    filesSkipped,\n  };\n}\n","import { ProjectMetadata } from \"./detector\";\n\n/**\n * Generate config.json content based on metadata.\n */\nexport function generateConfigJson(metadata: ProjectMetadata): string {\n  const config = {\n    $schema: \"https://docforagents.org/schemas/v1/config.json\",\n    version: \"1.0.0\",\n    project: {\n      name: metadata.projectName,\n      languages: metadata.languages,\n      frameworks: metadata.frameworks,\n      tools: metadata.tools,\n    },\n    knowledgeDir: \"knowledge\",\n    exclude: [\n      \"node_modules\",\n      \".git\",\n      \"dist\",\n      \"build\",\n      \"target\",\n      \"venv\",\n      \".venv\",\n      \"__pycache__\",\n      \".docforagents/cache\"\n    ],\n    rules: {\n      requireAdrForMajorChanges: false,\n      requireAgentsUpdateOnApiChange: true\n    }\n  };\n  return JSON.stringify(config, null, 2);\n}\n\n/**\n * Generate root AGENTS.md template.\n */\nexport function generateRootAgentsMd(metadata: ProjectMetadata): string {\n  const languagesList = metadata.languages.map(l => `- ${l}`).join(\"\\n\") || \"- (None detected)\";\n  const frameworksList = metadata.frameworks.map(f => `- ${f}`).join(\"\\n\") || \"- (None detected)\";\n  const toolsList = metadata.tools.map(t => `- ${t}`).join(\"\\n\") || \"- (None detected)\";\n  \n  const directoryList = metadata.directories\n    .map(dir => `- [${dir}/](file://./${dir}/) — *Add responsibilities of this directory* (see [${dir}/AGENTS.md](file://./${dir}/AGENTS.md) for local rules)`)\n    .join(\"\\n\") || \"- (No directories detected)\";\n\n  return `# AGENTS.md — AI Agent Context Entry Point\n\n> [!NOTE]\n> **To AI Coding Agents:** This file serves as your primary landing page for understanding the architecture, rules, and entry points of the **${metadata.projectName}** project. Before executing tasks or modifications, review this page and follow the links to specific files.\n\n## Project Overview\n*Briefly describe what this project does, its goals, and its business context.*\n\n## Core Stack & Environment\n### Languages\n${languagesList}\n\n### Frameworks & Libraries\n${frameworksList}\n\n### Infrastructure & Tools\n${toolsList}\n\n---\n\n## Repository Map\n\n### Core Knowledge Base\nAll architectural and domain-specific knowledge resides in the \\`knowledge/\\` directory:\n- [Architecture Overview](file://./knowledge/architecture/overview.md) — System components, data flow, design patterns.\n- [API Documentation](file://./knowledge/api/overview.md) — Endpoints, schemas, payloads.\n- [Architecture Decisions (ADRs)](file://./knowledge/decisions/README.md) — Why the project was built this way.\n- [Glossary of Terms](file://./knowledge/glossary/terms.md) — Domain vocabulary and definitions.\n- [Testing Guidelines](file://./knowledge/testing/overview.md) — Test setup, commands, and strategies.\n\n### Directory Structure\n${directoryList}\n\n---\n\n## Agent Guidelines & Conventions\n\n### 1. Read Before Write\n- Check the relevant local \\`AGENTS.md\\` inside directories you are editing.\n- Look at the [Architecture Decisions](file://./knowledge/decisions/README.md) to understand existing patterns (e.g. repository pattern, clean architecture).\n\n### 2. Standardized Changes\n- **API changes** MUST update [API Overview](file://./knowledge/api/overview.md) and local \\`AGENTS.md\\` interfaces.\n- **Architectural changes** require an Architecture Decision Record (ADR) under [Decisions](file://./knowledge/decisions/README.md).\n\n### 3. Verification\n- Always execute tests according to [Testing Guidelines](file://./knowledge/testing/overview.md) before declaring a task complete.\n`;\n}\n\n/**\n * Generate folder-level AGENTS.md template.\n */\nexport function generateFolderAgentsMd(folderName: string): string {\n  return `# AGENTS.md — Local Directory Rules for \\`${folderName}/\\`\n\n> [!NOTE]\n> **To AI Coding Agents:** This file defines the responsibilities, entry points, and coding conventions specific to the \\`${folderName}/\\` directory. Adhere strictly to these guidelines when making modifications here.\n\n## Purpose & Responsibility\n*Describe the single responsibility of this directory (e.g. \\\"Handles authentication endpoints and JWT verification\\\").*\n\n## Core Entry Points\n- [\\`index.ts\\` or entry file](file://./index.ts) — *Describe what imports/exports this file exposes.*\n\n## Internal Dependencies & Imports\n- **Imports from other modules:** *Specify which parent modules this directory is allowed to import from.*\n- **Outward dependencies:** *What external npm/pip packages or databases does this folder communicate with?*\n\n## Conventions & Implementation Rules\n1. **Design Patterns**: *e.g., Use controllers for route handling, delegate business logic to services.*\n2. **Naming Conventions**: *e.g., Suffix all services with \\`Service\\` (e.g., \\`AuthService\\`).*\n3. **Error Handling**: *e.g., Do not throw raw errors; wrap in \\`AppError\\` with status codes.*\n4. **Security**: *e.g., Ensure JWT middleware is applied to all new route configurations.*\n`;\n}\n\n/**\n * Template for knowledge/architecture/overview.md\n */\nexport function generateArchitectureOverviewMd(projectName: string): string {\n  return `# Architecture Overview — ${projectName}\n\n## System Overview\n*Provide a high-level description of how this system is put together. Mention if it is a monolith, microservices, SPA, Serverless, etc.*\n\n## Core Components\n*List the primary components/modules of the application and their relationships.*\n\n\\`\\`\\`mermaid\ngraph TD\n    Client[Client / Frontend] --> API[API Gateway / Backend]\n    API --> DB[(Database)]\n    API --> Cache[(Cache / Redis)]\n\\`\\`\\`\n\n## Core Design Patterns\n*Outline the engineering patterns used in this codebase (e.g., Clean Architecture, MVC, CQRS, Repository Pattern, Dependency Injection).*\n\n- **Pattern A**: *Description of how it is applied.*\n- **Pattern B**: *Description of how it is applied.*\n\n## Data Flows\n1. **Request Flow**: *Trace a typical request from the frontend to database and back.*\n2. **Background Processes**: *Describe queues, cron jobs, event-driven pipelines if applicable.*\n`;\n}\n\n/**\n * Template for knowledge/api/overview.md\n */\nexport function generateApiOverviewMd(projectName: string): string {\n  return `# API Reference — ${projectName}\n\n## Authentication & Authorization\n*Describe how clients authenticate to the APIs (e.g. Bearer tokens, cookies, API keys).*\n\n\\`\\`\\`http\nAuthorization: Bearer <token>\n\\`\\`\\`\n\n## Base URLs\n- Development: \\`http://localhost:3000/api\\`\n- Staging: \\`https://staging.api.example.com/v1\\`\n- Production: \\`https://api.example.com/v1\\`\n\n## Main Endpoints\n\n### 1. Health check\n- **Method / Path**: \\`GET /health\\`\n- **Description**: Returns the system status.\n- **Response**:\n  \\`\\`\\`json\n  {\n    \"status\": \"healthy\",\n    \"timestamp\": \"2026-07-27T18:00:00Z\"\n  }\n  \\`\\`\\`\n\n### 2. [Endpoint Name]\n- **Method / Path**: \\`POST /resource\\`\n- **Headers**: \\`Content-Type: application/json\\`\n- **Request Body**:\n  \\`\\`\\`json\n  {\n    \"name\": \"example\"\n  }\n  \\`\\`\\`\n- **Response (201 Created)**:\n  \\`\\`\\`json\n  {\n    \"id\": \"uuid-1234\",\n    \"name\": \"example\"\n  }\n  \\`\\`\\`\n`;\n}\n\n/**\n * Template for knowledge/decisions/README.md\n */\nexport function generateDecisionsReadmeMd(projectName: string): string {\n  return `# Architectural Decision Records (ADR)\n\nThis folder contains the history of major design and architectural choices made in the **${projectName}** repository.\n\n## What is an ADR?\nAn Architectural Decision Record (ADR) is a document that captures an important architectural decision, including the context in which the decision was made, the consequences of the decision, and its current status (Proposed, Accepted, Superceded).\n\n## ADR Index\n\n| ADR # | Title | Status | Date |\n|-------|-------|--------|------|\n| [ADR-001](file://./001-initial-architecture.md) | Initial Architecture Scaffolding | Accepted | 2026-07-27 |\n\n*To create a new ADR, copy the template format and name it sequentially (e.g. \\`002-use-redis-caching.md\\`).*\n`;\n}\n\n/**\n * Template for knowledge/glossary/terms.md\n */\nexport function generateGlossaryMd(): string {\n  return `# Domain Glossary\n\nDefine the core business terms and domain models used in this repository. This reduces ambiguity for AI agents and onboarding engineers.\n\n| Term | Definition | Context / Usage |\n|------|------------|-----------------|\n| **ADR** | Architecture Decision Record. | Engineering workflow documentation |\n| **Agent** | An autonomous AI agent performing operations on code. | AI Coding context |\n| **Knowledge Layer** | The directory containing machine-readable code specification and guidelines. | Standard repo structure |\n`;\n}\n\n/**\n * Template for knowledge/testing/overview.md\n */\nexport function generateTestingOverviewMd(metadata: ProjectMetadata): string {\n  return `# Testing Guidelines\n\n## Running Tests\n*Provide the exact commands required to execute the test suite.*\n\n\\`\\`\\`bash\n# Run unit tests\nnpm run test\n# Run integration / e2e tests\nnpm run test:e2e\n\\`\\`\\`\n\n## Testing Philosophy\n- **Unit Tests**: Describe where unit tests are placed (e.g., next to the file as \\`*.test.ts\\` or in a \\`test/\\` directory).\n- **Integration Tests**: Describe how to test integrations with mock services/databases.\n- **Coverage**: Target code coverage expectations.\n\n## Creating New Tests\n- Use the standard test framework configurations.\n- Mock external network calls using MSW, nock, or custom mock suites.\n`;\n}\n\n/**\n * Generate the prompt for folder-specific AGENTS.md generation.\n */\nexport function generateFolderAgentsPrompt(\n  folderName: string,\n  tree: string,\n  filesContext: string\n): string {\n  return `You are tasked with generating the customized folder-level AGENTS.md for the directory \\`${folderName}/\\`.\nBelow is the directory tree for this subdirectory:\n\\`\\`\\`\n${tree}\n\\`\\`\\`\n\nHere is the content of key files inside this directory:\n${filesContext}\n\nAnalyze the files to generate a highly detailed rules document for AI coding agents modifying this directory.\nInclude:\n1. **Purpose & Responsibility**: Describe the single responsibility of this directory (e.g. \"Handles authentication endpoints and JWT verification\").\n2. **Core Entry Points**: List the primary entry files and export signatures that other directories or external clients interact with.\n3. **Internal Dependencies & Imports**: Detail which other directories this folder imports from, and any critical packages it depends on.\n4. **Conventions & Implementation Rules**: Extract local conventions, design patterns (e.g., repository patterns, controller structures), naming schemes, and error/security constraints specific to this directory.\n\nFormat your output exactly as standard Markdown, using standard alert boxes (> [!NOTE]) for emphasis. Start directly with \\`# AGENTS.md — Local Directory Rules for \\`${folderName}/\\` \\`.`;\n}\n","import chalk from \"chalk\";\nimport prompts from \"prompts\";\n\n/**\n * Print a clean visual representation of the folders recommended for AGENTS.md creation.\n */\nexport function printFolderRecommendation(projectName: string, directories: string[]): void {\n  if (directories.length === 0) return;\n\n  console.log(chalk.bold(`\\n📁 ${projectName}`));\n  \n  // Show up to 5 directories. If more, show the rest as a summary.\n  const maxToShow = 5;\n  const dirsToShow = directories.slice(0, maxToShow);\n  const remaining = directories.length - maxToShow;\n\n  dirsToShow.forEach((dir, idx) => {\n    const isLast = idx === dirsToShow.length - 1 && remaining <= 0;\n    const branch = isLast ? \"└──\" : \"├──\";\n    console.log(`  ${branch} 📁 ${dir}/`);\n    console.log(`  ${isLast ? \"   \" : \"│  \"}  └── 📝 ${chalk.green(\"AGENTS.md\")} ${chalk.gray(\"(recommended)\")}`);\n  });\n\n  if (remaining > 0) {\n    console.log(`  └── ${chalk.gray(`... and ${remaining} more folders`)}`);\n  }\n  console.log();\n}\n\n/**\n * Interactively prompt the user to approve or select directories for AGENTS.md creation.\n * If the project is large (> 5 directories), we alert the user about potential token/time usage.\n */\nexport async function configureFolderAgentsCreation(\n  projectName: string,\n  directories: string[]\n): Promise<string[]> {\n  const filteredDirs = directories.filter(dir => !dir.startsWith(\".\"));\n  if (filteredDirs.length === 0) {\n    return [];\n  }\n\n  printFolderRecommendation(projectName, filteredDirs);\n\n  const isLargeProject = filteredDirs.length > 5;\n  if (isLargeProject) {\n    console.log(\n      chalk.yellow(\n        `⚠️  This is a large project with ${filteredDirs.length} folders recommended for AGENTS.md creation.`\n      )\n    );\n    console.log(\n      chalk.gray(\n        `   Auto-creating rules via LLM for all folders may consume a significant amount of time and tokens.\\n`\n      )\n    );\n  }\n\n  const response = await prompts(\n    {\n      type: \"select\",\n      name: \"action\",\n      message: \"Configure folder-level AGENTS.md creation:\",\n      choices: [\n        {\n          title: `Auto-create in all recommended folders (${filteredDirs.length} folders)`,\n          value: \"all\",\n        },\n        {\n          title: \"Manual control (select specific folders)\",\n          value: \"manual\",\n        },\n        {\n          title: \"Skip folder-level AGENTS.md entirely\",\n          value: \"skip\",\n        },\n      ],\n      initial: 0,\n    },\n    {\n      onCancel: () => {\n        console.log(chalk.yellow(\"\\nOperation cancelled.\"));\n        process.exit(0);\n      },\n    }\n  );\n\n  if (response.action === \"all\") {\n    return filteredDirs;\n  }\n\n  if (response.action === \"skip\") {\n    return [];\n  }\n\n  if (response.action === \"manual\") {\n    const manualResponse = await prompts(\n      {\n        type: \"multiselect\",\n        name: \"folders\",\n        message: \"Select subdirectories to create AGENTS.md in:\",\n        choices: filteredDirs.map((dir) => ({\n          title: `${dir}/`,\n          value: dir,\n          selected: true,\n        })),\n        hint: \"- Space to select/deselect, Enter to confirm\",\n        min: 0,\n      },\n      {\n        onCancel: () => {\n          console.log(chalk.yellow(\"\\nOperation cancelled.\"));\n          process.exit(0);\n        },\n      }\n    );\n\n    return manualResponse.folders || [];\n  }\n\n  return [];\n}\n"],"mappings":"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","names":["path","chalk","prompts","fs","fs","fs","path","path","fs","path","chalk","prompts"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "docforagents",
+  "version": "0.1.0",
+  "description": "Open-source AI-native knowledge specification and tooling for software repositories",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "docforagents": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "documentation",
+    "openapi",
+    "agents",
+    "knowledge",
+    "specification"
+  ],
+  "author": "",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.12",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.2.3",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.4"
+  }
+}