diary-docs 0.1.0__tar.gz

diary_docs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bakhija senakmoiky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diary_docs-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: diary-docs
+Version: 0.1.0
+Summary: Scaffold DIARY documentation structure with MkDocs and Backstage support
+Author-email: bakhija senakmoiky <senakmoiky@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/bakhija/diary-docs
+Project-URL: Repository, https://github.com/bakhija/diary-docs
+Keywords: documentation,mkdocs,backstage,techdocs,scaffolder
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Requires-Dist: inquirerpy>=0.3.4
+Dynamic: license-file
+
+# diary-docs — DIARY Documentation Scaffolder
+
+A CLI tool that scaffolds a DIARY documentation structure with MkDocs and Backstage support, indexes your codebase for knowledge retrieval, and keeps docs in sync with code changes.
+
+## Installation
+
+```bash
+pip install diary-docs
+```
+
+For development:
+
+```bash
+pip install -e .
+```
+
+## Commands
+
+### `diary-docs init`
+
+Initialize a new DIARY documentation project in the current directory.
+
+```bash
+diary-docs init
+```
+
+The tool prompts for a project name, then creates:
+
+```
+docs/
+├── index.md
+├── objectives.md
+├── structure/
+│   └── index.md
+├── techdocs/
+│   ├── index.md
+│   ├── architecture.md
+│   ├── api-contracts.md
+│   ├── deployment.md
+│   ├── adr.md
+│   └── development-guide.md
+├── product/
+│   ├── index.md
+│   ├── user-guide.md
+│   └── modules.md
+├── ops-governance/
+│   ├── index.md
+│   ├── runbooks.md
+│   └── security.md
+└── knowledge-base/
+    ├── index.md
+    ├── faq.md
+    └── troubleshooting.md
+mkdocs.yml
+catalog-info.yaml
+```
+
+It also generates an AI agent skill file for content generation.
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-f`, `--force` | Overwrite existing files |
+| `--help` | Show help for this command |
+
+If files already exist, they are skipped (unless `--force` is used).
+
+---
+
+### `diary-docs index`
+
+Index the workspace codebase for knowledge retrieval. Extracts symbols, files, and relationships into a SQLite database.
+
+```bash
+diary-docs index
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-r`, `--report` | Generate a documentation coverage report after indexing |
+| `--db-path PATH` | Custom database path (default: `docs/.index/knowledge.db`) |
+| `--help` | Show help for this command |
+
+The index powers the `diary-docs generate-content` skill, allowing AI agents to query the codebase structure without manually scanning files.
+
+---
+
+### `diary-docs sync`
+
+Synchronize documentation with detected code changes. Compares the current workspace against git history to find outdated AIMB (AI-Managed) blocks in markdown files.
+
+```bash
+# Preview changes without applying
+diary-docs sync --dry-run
+
+# Apply all detected changes
+diary-docs sync --force
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-n`, `--dry-run` | Preview changes as JSON without applying |
+| `-b`, `--branch NAME` | Override branch detection |
+| `-f`, `--force` | Skip conflict warnings |
+| `-o`, `--output FILE` | Write JSON report to file |
+| `--help` | Show help for this command |
+
+**Dry-run output** is a JSON SyncReport showing code changes, affected docs, confidence scores, and any conflicts.
+
+---
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--version` | Show version |
+| `--help` | Show top-level help |
+
+## AI Agent Skills
+
+`diary-docs init` generates two slash commands for AI coding agents (Claude Code, OpenCode). The skill files are placed in `.claude/commands/` or `.opencode/commands/` (you choose during init).
+
+### `/diary-generate-content`
+
+Analyzes the workspace codebase via the pre-built index and generates enterprise-grade documentation content for every DIARY file.
+
+```bash
+# In Claude Code or OpenCode:
+/diary-generate-content
+```
+
+The skill follows a multi-step workflow:
+1. Reads existing docs structure
+2. Queries the knowledge index (`docs/.index/knowledge.db`)
+3. Asks clarifying questions for missing context
+4. Generates content with Mermaid diagrams, tables, and use cases
+5. Writes all `docs/` files with AIMB (AI-Managed Block) wrappers
+
+Output covers: architecture overview, API contracts, deployment flow, ADR log, user guide, runbooks, security compliance, FAQ, and troubleshooting.
+
+---
+
+### `/diary-sync`
+
+Synchronizes documentation with detected code changes. Compares the current git state against history to find outdated AIMB blocks.
+
+```bash
+# In Claude Code or OpenCode:
+/diary-sync
+```
+
+The skill follows a structured workflow:
+1. Verifies git state and runs `diary-docs sync --dry-run`
+2. Parses the SyncReport JSON for changes and conflicts
+3. Processes each high-confidence change by updating relevant AIMB blocks
+4. Flags conflicts for manual review (never auto-resolves)
+5. Finalizes with `diary-docs sync --force`
+6. Prints a summary of all processed files
+
+**Prerequisites:** All code changes must be committed to git before running `/diary-sync`.
+
+---
+
+## What It Generates
+
+| File/Folder | Description |
+|-------------|-------------|
+| `docs/` | Main documentation folder |
+| `docs/index.md` | Root documentation index |
+| `docs/objectives.md` | Project objectives and goals |
+| `docs/structure/index.md` | Writing guidelines and conventions |
+| `docs/techdocs/` | Technical documentation section |
+| `docs/techdocs/architecture.md` | System architecture overview |
+| `docs/techdocs/api-contracts.md` | API endpoint specifications |
+| `docs/techdocs/deployment.md` | Deployment flow and environments |
+| `docs/techdocs/adr.md` | Architecture Decision Records |
+| `docs/techdocs/development-guide.md` | Local development setup guide |
+| `docs/product/` | Product documentation section |
+| `docs/product/user-guide.md` | End-user guide with use cases |
+| `docs/product/modules.md` | Module/component reference |
+| `docs/ops-governance/` | Operations & governance section |
+| `docs/ops-governance/runbooks.md` | Operational runbooks |
+| `docs/ops-governance/security.md` | Security compliance docs |
+| `docs/knowledge-base/` | Knowledge base section |
+| `docs/knowledge-base/faq.md` | Frequently asked questions |
+| `docs/knowledge-base/troubleshooting.md` | Troubleshooting guide |
+| `mkdocs.yml` | MkDocs configuration with TechDocs Core plugin |
+| `catalog-info.yaml` | Backstage component registration file |
+
+## Development
+
+```bash
+pytest tests/ -v
+```

diary_docs-0.1.0/README.md

@@ -0,0 +1,199 @@
+# diary-docs — DIARY Documentation Scaffolder
+
+A CLI tool that scaffolds a DIARY documentation structure with MkDocs and Backstage support, indexes your codebase for knowledge retrieval, and keeps docs in sync with code changes.
+
+## Installation
+
+```bash
+pip install diary-docs
+```
+
+For development:
+
+```bash
+pip install -e .
+```
+
+## Commands
+
+### `diary-docs init`
+
+Initialize a new DIARY documentation project in the current directory.
+
+```bash
+diary-docs init
+```
+
+The tool prompts for a project name, then creates:
+
+```
+docs/
+├── index.md
+├── objectives.md
+├── structure/
+│   └── index.md
+├── techdocs/
+│   ├── index.md
+│   ├── architecture.md
+│   ├── api-contracts.md
+│   ├── deployment.md
+│   ├── adr.md
+│   └── development-guide.md
+├── product/
+│   ├── index.md
+│   ├── user-guide.md
+│   └── modules.md
+├── ops-governance/
+│   ├── index.md
+│   ├── runbooks.md
+│   └── security.md
+└── knowledge-base/
+    ├── index.md
+    ├── faq.md
+    └── troubleshooting.md
+mkdocs.yml
+catalog-info.yaml
+```
+
+It also generates an AI agent skill file for content generation.
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-f`, `--force` | Overwrite existing files |
+| `--help` | Show help for this command |
+
+If files already exist, they are skipped (unless `--force` is used).
+
+---
+
+### `diary-docs index`
+
+Index the workspace codebase for knowledge retrieval. Extracts symbols, files, and relationships into a SQLite database.
+
+```bash
+diary-docs index
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-r`, `--report` | Generate a documentation coverage report after indexing |
+| `--db-path PATH` | Custom database path (default: `docs/.index/knowledge.db`) |
+| `--help` | Show help for this command |
+
+The index powers the `diary-docs generate-content` skill, allowing AI agents to query the codebase structure without manually scanning files.
+
+---
+
+### `diary-docs sync`
+
+Synchronize documentation with detected code changes. Compares the current workspace against git history to find outdated AIMB (AI-Managed) blocks in markdown files.
+
+```bash
+# Preview changes without applying
+diary-docs sync --dry-run
+
+# Apply all detected changes
+diary-docs sync --force
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-n`, `--dry-run` | Preview changes as JSON without applying |
+| `-b`, `--branch NAME` | Override branch detection |
+| `-f`, `--force` | Skip conflict warnings |
+| `-o`, `--output FILE` | Write JSON report to file |
+| `--help` | Show help for this command |
+
+**Dry-run output** is a JSON SyncReport showing code changes, affected docs, confidence scores, and any conflicts.
+
+---
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--version` | Show version |
+| `--help` | Show top-level help |
+
+## AI Agent Skills
+
+`diary-docs init` generates two slash commands for AI coding agents (Claude Code, OpenCode). The skill files are placed in `.claude/commands/` or `.opencode/commands/` (you choose during init).
+
+### `/diary-generate-content`
+
+Analyzes the workspace codebase via the pre-built index and generates enterprise-grade documentation content for every DIARY file.
+
+```bash
+# In Claude Code or OpenCode:
+/diary-generate-content
+```
+
+The skill follows a multi-step workflow:
+1. Reads existing docs structure
+2. Queries the knowledge index (`docs/.index/knowledge.db`)
+3. Asks clarifying questions for missing context
+4. Generates content with Mermaid diagrams, tables, and use cases
+5. Writes all `docs/` files with AIMB (AI-Managed Block) wrappers
+
+Output covers: architecture overview, API contracts, deployment flow, ADR log, user guide, runbooks, security compliance, FAQ, and troubleshooting.
+
+---
+
+### `/diary-sync`
+
+Synchronizes documentation with detected code changes. Compares the current git state against history to find outdated AIMB blocks.
+
+```bash
+# In Claude Code or OpenCode:
+/diary-sync
+```
+
+The skill follows a structured workflow:
+1. Verifies git state and runs `diary-docs sync --dry-run`
+2. Parses the SyncReport JSON for changes and conflicts
+3. Processes each high-confidence change by updating relevant AIMB blocks
+4. Flags conflicts for manual review (never auto-resolves)
+5. Finalizes with `diary-docs sync --force`
+6. Prints a summary of all processed files
+
+**Prerequisites:** All code changes must be committed to git before running `/diary-sync`.
+
+---
+
+## What It Generates
+
+| File/Folder | Description |
+|-------------|-------------|
+| `docs/` | Main documentation folder |
+| `docs/index.md` | Root documentation index |
+| `docs/objectives.md` | Project objectives and goals |
+| `docs/structure/index.md` | Writing guidelines and conventions |
+| `docs/techdocs/` | Technical documentation section |
+| `docs/techdocs/architecture.md` | System architecture overview |
+| `docs/techdocs/api-contracts.md` | API endpoint specifications |
+| `docs/techdocs/deployment.md` | Deployment flow and environments |
+| `docs/techdocs/adr.md` | Architecture Decision Records |
+| `docs/techdocs/development-guide.md` | Local development setup guide |
+| `docs/product/` | Product documentation section |
+| `docs/product/user-guide.md` | End-user guide with use cases |
+| `docs/product/modules.md` | Module/component reference |
+| `docs/ops-governance/` | Operations & governance section |
+| `docs/ops-governance/runbooks.md` | Operational runbooks |
+| `docs/ops-governance/security.md` | Security compliance docs |
+| `docs/knowledge-base/` | Knowledge base section |
+| `docs/knowledge-base/faq.md` | Frequently asked questions |
+| `docs/knowledge-base/troubleshooting.md` | Troubleshooting guide |
+| `mkdocs.yml` | MkDocs configuration with TechDocs Core plugin |
+| `catalog-info.yaml` | Backstage component registration file |
+
+## Development
+
+```bash
+pytest tests/ -v
+```

diary_docs-0.1.0/diary/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

diary_docs-0.1.0/diary/__main__.py

@@ -0,0 +1,3 @@
+from diary.cli import main
+
+main()

diary_docs-0.1.0/diary/aimb/__init__.py

@@ -0,0 +1,48 @@
+"""AIMB — AI Managed Block parser, hasher, and merge for markdown files."""
+
+from .hasher import (
+    compute_block_hash,
+    verify_block_hash,
+    hash_all_blocks,
+    get_stored_hashes,
+    find_changed_blocks,
+)
+from .merge import (
+    ConflictInfo,
+    MergeDecision,
+    apply_replace,
+    decide_block_action,
+    format_conflict_report,
+    generate_block_diff,
+)
+from .parser import (
+    AIMBBlock,
+    parse_aimb_blocks,
+    parse_frontmatter,
+    extract_manual_blocks,
+    has_aimb_blocks,
+    get_block_by_id,
+)
+
+__all__ = [
+    # parser
+    "AIMBBlock",
+    "parse_aimb_blocks",
+    "parse_frontmatter",
+    "extract_manual_blocks",
+    "has_aimb_blocks",
+    "get_block_by_id",
+    # hasher
+    "compute_block_hash",
+    "verify_block_hash",
+    "hash_all_blocks",
+    "get_stored_hashes",
+    "find_changed_blocks",
+    # merge
+    "MergeDecision",
+    "ConflictInfo",
+    "decide_block_action",
+    "generate_block_diff",
+    "format_conflict_report",
+    "apply_replace",
+]

diary_docs-0.1.0/diary/aimb/hasher.py

@@ -0,0 +1,157 @@
+"""AIMB block hasher — SHA256 computation and integrity checking.
+
+Functions
+---------
+compute_block_hash
+    SHA256 hex digest of block content.
+verify_block_hash
+    Compare computed hash against an expected value.
+hash_all_blocks
+    Compute hashes for every AIMB block in markdown content.
+get_stored_hashes
+    Extract the hashes stored in AIMB metadata tags.
+find_changed_blocks
+    Detect blocks whose stored hash differs from the current computed hash.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from .parser import parse_aimb_blocks
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────
+
+
+def _sha256(content: str) -> str:
+    """Return hex-encoded SHA-256 digest of *content*."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+# ── Public API ───────────────────────────────────────────────────────────
+
+
+def compute_block_hash(content: str) -> str:
+    """Return the SHA-256 hex digest of *content*.
+
+    Parameters
+    ----------
+    content : str
+        The raw text content of an AIMB block (text between the opening
+        ``<!-- ai-managed ... -->`` and closing ``<!-- /ai-managed -->``
+        tags).
+
+    Returns
+    -------
+    str
+        64-character hex-encoded SHA-256 digest.
+
+    Examples
+    --------
+    >>> compute_block_hash("test")
+    "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+    """
+    return _sha256(content)
+
+
+def verify_block_hash(content: str, expected_hash: str) -> bool:
+    """Verify that *content* hashes to *expected_hash*.
+
+    Parameters
+    ----------
+    content : str
+        Raw block content to hash.
+    expected_hash : str
+        Previously recorded hash to compare against.
+
+    Returns
+    -------
+    bool
+        ``True`` if the computed hash matches *expected_hash*.
+    """
+    return compute_block_hash(content) == expected_hash
+
+
+def hash_all_blocks(content: str) -> dict[str, str]:
+    """Compute the hash for every AIMB block in *content*.
+
+    Hashes only the **content** between the opening and closing tags
+    (not the tags themselves).
+
+    Parameters
+    ----------
+    content : str
+        Full markdown content with AIMB blocks.
+
+    Returns
+    -------
+    dict[str, str]
+        Mapping of ``{block_id: hash}`` for every AIMB block found.
+        Empty dict if no AIMB blocks exist.
+    """
+    blocks = parse_aimb_blocks(content)
+    return {block.id: compute_block_hash(block.content) for block in blocks}
+
+
+def get_stored_hashes(content: str) -> dict[str, str]:
+    """Extract the hashes stored in AIMB block metadata tags.
+
+    These are the ``hash="..."`` values written into each
+    ``<!-- ai-managed ... -->`` opening tag.
+
+    Parameters
+    ----------
+    content : str
+        Full markdown content with AIMB blocks.
+
+    Returns
+    -------
+    dict[str, str]
+        Mapping of ``{block_id: stored_hash}``.
+        Empty dict if no AIMB blocks exist.
+    """
+    blocks = parse_aimb_blocks(content)
+    return {block.id: block.hash for block in blocks}
+
+
+def find_changed_blocks(old_content: str, new_content: str) -> list[dict[str, Any]]:
+    """Find AIMB blocks whose stored hash differs from their current computed hash.
+
+    For each AIMB block:
+    - The **stored hash** is read from the metadata in *old_content*.
+    - The **computed hash** is calculated from the block content in
+      *new_content*.
+
+    Parameters
+    ----------
+    old_content : str
+        Previous version of the markdown content (source of stored hashes).
+    new_content : str
+        Current version of the markdown content (source of block content to
+        hash).
+
+    Returns
+    -------
+    list[dict[str, Any]]
+        A list of dicts, one per changed block, with keys:
+        ``id``, ``old_hash``, ``new_hash``.  Empty list if no blocks
+        changed or no AIMB blocks exist.
+    """
+    stored = get_stored_hashes(old_content)
+    computed = hash_all_blocks(new_content)
+
+    changed: list[dict[str, Any]] = []
+    for block_id, old_hash in stored.items():
+        new_hash = computed.get(block_id)
+        if new_hash is not None and old_hash != new_hash:
+            changed.append(
+                {
+                    "id": block_id,
+                    "old_hash": old_hash,
+                    "new_hash": new_hash,
+                }
+            )
+
+    return changed