DocsRepoService

Kind: Service

Source: atloria-monorepo/apps/api/src/docs-repo/docs-repo.service.ts

DocsRepoService — the low-level git primitive for the per-project docs substrate.

One NON-BARE git repo per project lives at ${DOCS_REPO_ROOT}/<projectId> (default /work/docs-repos, overridable for tests). Every mutation goes through git so the repo IS the source of record for content history; Postgres remains the authority the repo is rebuildable from (see ReconcilerService).

ALL git invocation is via promisified execFile('git', [args], { cwd }) — an argv array, never a shell string — so a slug/path/message can never inject a shell command.

DocsRepoService manages the non-bare Git repository that backs each project's documentation content under ${DOCS_REPO_ROOT}/<projectId>. It safely initializes repositories, normalizes and writes document trees, and exposes Git-derived state such as tree hashes and normalizer versions; higher-level reconciliation can rebuild repository state from Postgres when needed.

Methods

Dependencies

• ConfigService
• NormalizeFn

Where it refuses work

• DocsRepoService stops the work with Error when !gitPath.startsWith('snippets/').
• DocsRepoService stops the work with Error when !gitPath.startsWith('.atloria/').
• DocsRepoService stops the work with Error when !seg || seg.includes('/') || seg.includes('\\') || seg === '.' || seg === '..'.
• DocsRepoService stops the work with Error when !p — “Empty file path”.
• DocsRepoService stops the work with Error when path.isAbsolute(rel) || rel.split(path.sep).some((s) => s === '..').
• DocsRepoService stops the work with an early return when !(await this.hasStagedChanges(cwd)), in 2 places.

When something fails

• DocsRepoService handles failure in 8 places: it turns it into a return value in 6, logs it and continues in 1, and lets it reach the caller in 1.

Diagram

mermaid
sequenceDiagram
  participant Caller as Reconciler / Docs Service
  participant Repo as DocsRepoService
  participant FS as Project Docs Repository
  participant Git as git (execFile)

  Caller->>Repo: ensureRepo(projectId)
  Repo->>FS: Check repository path
  alt Repository does not exist
    Repo->>Git: git init (argv array)
    Git-->>Repo: Repository initialized
  end
  Repo-->>Caller: Ready

  Caller->>Repo: writeTree(projectId, files)
  Repo->>Repo: normalizeContent(content)
  Repo->>Repo: repoRelPath(path)
  Repo->>FS: Write normalized files
  Repo->>Git: git add / write-tree
  Git-->>Repo: tree SHA
  Repo-->>Caller: tree SHA

Usage

ts
import { DocsRepoService } from './docs-repo.service';

// Typically injected by NestJS into a reconciler or document mutation service.
export class ProjectDocsWriter {
  constructor(private readonly docsRepoService: DocsRepoService) {}

  async writeProjectDocs(projectId: string) {
    await this.docsRepoService.ensureRepo(projectId);

    const treeSha = await this.docsRepoService.writeTree(projectId, [
      {
        path: 'README.md',
        content: '# Project Documentation\n\nWelcome to the project docs.\n',
      },
      {
        path: 'guides/getting-started.md',
        content: '# Getting Started\n\nInstall the application and configure it.\n',
      },
    ]);

    return { projectId, treeSha };
  }
}

AI Coding Instructions

• Route all repository mutations through DocsRepoService; do not write directly to project documentation repositories from callers.
• Preserve the execFile('git', args, { cwd }) pattern for every Git command. Never construct shell command strings from project IDs, paths, or commit messages.
• Validate and convert document paths with repoRelPath() before file operations to prevent writes outside the project repository.
• Normalize content with normalizeContent() before writing so generated trees are deterministic and compatible with normalizer-version checks.
• Treat Git as the content-history record, while using reconciliation integrations to rebuild repository content from Postgres when repository state is missing or stale.

Relationships

• DEPENDS_ON → configservice
• DEPENDS_ON → NormalizeFn

Referenced By

• DiffService (DEPENDS_ON)
• DocsRepoModule (MODULE_PROVIDES)
• DocsRepoModule (MODULE_EXPORTS)
• ReconcilerService (DEPENDS_ON)
• GitSyncMirrorService (DEPENDS_ON)
• PublicProjectController (DEPENDS_ON)