okf-cli 0.1.0__py3-none-any.whl

okf/cli.py

@@ -0,0 +1,226 @@
+"""okf enrich — Plain markdown to OKF bundle converter."""
+
+import json
+import os
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(
+    name="okf",
+    help="Open Knowledge Format tooling",
+    no_args_is_help=True,
+)
+
+RESERVED = frozenset({"index.md", "log.md", "readme.md"})
+
+
+def _yaml_val(v: str) -> str:
+    """Format a string value as valid YAML via JSON encoding."""
+    return json.dumps(v, ensure_ascii=True)
+
+
+def _build_frontmatter(type_: str, title: str, description: str, timestamp: str) -> str:
+    parts = [
+        "---",
+        f"type: {_yaml_val(type_)}",
+        f"title: {_yaml_val(title)}",
+        f"description: {_yaml_val(description)}",
+    ]
+    if timestamp:
+        parts.append(f"timestamp: {_yaml_val(timestamp)}")
+    parts.append("---")
+    return "\n".join(parts)
+
+
+def _parse_md(text: str) -> tuple[str, str, str]:
+    """Parse title, description, body from plain markdown.
+
+    Returns (title, description, body).
+    Raises ValueError on format violation.
+    """
+    lines = text.splitlines(keepends=True)
+
+    if not lines or not lines[0].startswith("# "):
+        raise ValueError("Line 1 must be '# Title'")
+
+    title = lines[0][2:].strip()
+    if not title:
+        raise ValueError("Title cannot be empty")
+
+    # Find first non-blank after title line
+    i = 1
+    while i < len(lines) and not lines[i].strip():
+        i += 1
+
+    # Collect consecutive > lines
+    desc_lines = []
+    while i < len(lines) and lines[i].startswith(">"):
+        # Handle both "> text" and ">text"
+        content = lines[i][1:].strip()
+        desc_lines.append(content)
+        i += 1
+
+    if not desc_lines:
+        raise ValueError("Must have a '> description' block after title")
+
+    description = " ".join(desc_lines).strip()
+
+    # Skip blank lines between description and body
+    while i < len(lines) and not lines[i].strip():
+        i += 1
+
+    body = "".join(lines[i:])
+
+    return title, description, body
+
+
+@app.command()
+def enrich(
+    input_dir: str = typer.Argument(
+        ..., help="Source directory of plain markdown files"
+    ),
+    output_dir: str = typer.Argument(
+        "bundled", help="Output directory for the OKF bundle (default: bundled)"
+    ),
+    default_type: str = typer.Option(
+        None, help="Type for root-level files (skip root files if omitted)"
+    ),
+) -> None:
+    """Convert plain markdown into an OKF-conformant knowledge bundle.
+
+    Each .md file must start with '# Title' followed by a '>' description block.
+    Directory name determines the concept 'type'. Root-level files need --default-type.
+    If output-dir is omitted, defaults to 'bundled'.
+    """
+    src = Path(input_dir)
+    dst = Path(output_dir)
+
+    if not src.is_dir():
+        typer.echo(f"Error: input directory '{input_dir}' not found", err=True)
+        raise typer.Exit(code=1)
+
+    if dst.exists():
+        shutil.rmtree(dst)
+        typer.echo(f"Removed existing '{output_dir}'", err=True)
+
+    # Collect all .md files (skip reserved names, warn for reserved)
+    md_files = []
+    for f in sorted(src.rglob("*.md")):
+        lower = f.name.lower()
+        if lower in RESERVED:
+            if lower == "log.md":
+                typer.echo(
+                    f"Warning: Skipping {f.relative_to(src)} — reserved filename '{f.name}' (not a concept)",
+                    err=True,
+                )
+            continue
+        md_files.append(f)
+    if not md_files:
+        typer.echo("No markdown files found (excluding index.md, log.md)", err=True)
+        raise typer.Exit(code=1)
+
+    # Process each file, storing metadata for index generation
+    processed: list[tuple[Path, dict]] = []  # (relative_output_path, metadata)
+
+    for f in md_files:
+        rel = f.relative_to(src)
+        out_file = dst / rel
+        out_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Determine type
+        if rel.parent == Path("."):
+            if default_type is None:
+                typer.echo(
+                    f"Warning: Skipping {rel} — root-level file needs --default-type",
+                    err=True,
+                )
+                continue
+            type_name = default_type
+        else:
+            type_name = rel.parent.name
+
+        # Parse
+        try:
+            text = f.read_text(encoding="utf-8")
+            title, description, body = _parse_md(text)
+        except ValueError as e:
+            typer.echo(f"Error: {rel}: {e}", err=True)
+            raise typer.Exit(code=1)
+
+        # Timestamp from file mtime
+        mtime = os.path.getmtime(f)
+        ts = datetime.fromtimestamp(mtime, tz=timezone.utc).isoformat()
+
+        # Build and write
+        frontmatter = _build_frontmatter(type_name, title, description, ts)
+
+        # Validate frontmatter structure
+        if not (frontmatter.startswith("---\n") and frontmatter.endswith("\n---")):
+            typer.echo(f"Error: {rel}: generated invalid frontmatter", err=True)
+            raise typer.Exit(code=1)
+
+        # Preserve original line endings? Keep as-is from input.
+        out_file.write_text(f"{frontmatter}\n\n{body}", encoding="utf-8")
+
+        processed.append(
+            (rel, {"title": title, "description": description, "type": type_name})
+        )
+
+    # Collect per-directory files and subdirectories
+    dir_files: dict[Path, list[dict]] = {}
+    dir_subdirs: dict[Path, set[str]] = {}
+
+    for rel, meta in processed:
+        parent = rel.parent
+        dir_files.setdefault(parent, []).append(
+            {
+                "title": meta["title"],
+                "description": meta["description"],
+                "path": rel.name,
+            }
+        )
+        # Record subdirectory relationships at every level
+        for i in range(len(rel.parts) - 1):
+            grandparent = Path(*rel.parts[:i]) if i > 0 else Path(".")
+            child_dir = rel.parts[i]
+            dir_subdirs.setdefault(grandparent, set()).add(child_dir)
+
+    # Generate index.md for every directory with files or subdirs
+    for dir_path in sorted(set(dir_files.keys()) | set(dir_subdirs.keys())):
+        index_path = dst / dir_path / "index.md"
+        if index_path.exists():
+            continue
+
+        lines = []
+        entries = dir_files.get(dir_path, [])
+        subdirs = sorted(dir_subdirs.get(dir_path, set()))
+
+        if entries:
+            lines.append("# Contents")
+            lines.append("")
+            for e in entries:
+                desc = f" - {e['description']}" if e.get("description") else ""
+                lines.append(f"* [{e['title']}]({e['path']}){desc}")
+            lines.append("")
+
+        if subdirs:
+            lines.append("# Directories")
+            lines.append("")
+            for d in subdirs:
+                lines.append(f"* [{d}]({d}/)")
+            lines.append("")
+
+        if lines:
+            index_path.parent.mkdir(parents=True, exist_ok=True)
+            index_path.write_text("\n".join(lines), encoding="utf-8")
+
+    # Summary
+    n = len(processed)
+    typer.echo(f"Done. Converted {n} file{'s' if n != 1 else ''} → {dst}")
+
+
+if __name__ == "__main__":
+    app()

okf_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: okf-cli
+Version: 0.1.0
+Summary: Open Knowledge Format tooling
+License: MIT License
+        
+        Copyright (c) 2026 Dheerapat Tookkane
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# okf-cli — Open Knowledge Format tooling
+
+Converts plain markdown into [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)-conformant knowledge bundles. Domain experts write `# Title` then `> description` — `okf enrich` generates frontmatter, type, timestamps, and index files.
+
+## Quickstart
+
+```bash
+uv sync
+uv run okf example              # output → bundled/
+cat bundled/index.md
+cat bundled/tables/orders.md
+```
+
+## Usage
+
+```
+okf <input-dir> [output-dir] [--default-type <name>]
+```
+
+| Argument | Description |
+|---|---|
+| `input-dir` | Directory of plain `.md` files |
+| `output-dir` | Target directory (default: `bundled`) |
+| `--default-type` | Type for root-level files (skip root files if omitted) |
+
+## Writing input files
+
+Every `.md` file must start with:
+
+```markdown
+# Title
+
+> Description
+> Second optional description line.
+```
+
+Everything after the description block is free-form — preserved unchanged.
+
+**Rules:**
+
+| Rule | Why |
+|---|---|
+| First line must be `# Title` | Tool reads title here |
+| Followed by `> Description` | Tool reads description here |
+| Folder name = concept type | `tables/orders.md` → `type: "tables"` |
+| Only `.md` files processed | Non-`.md` files ignored |
+| Reserved names skipped: `index.md`, `log.md`, `README.md` | OKF spec reserves these |
+
+**Violations:**
+
+| Condition | Behavior |
+|---|---|
+| Line 1 not `# Title` | Error, stop |
+| Empty title | Error, stop |
+| No `> description` block | Error, stop |
+| Root-level file without `--default-type` | Skip file, warn, continue |
+
+Root files need `--default-type`. Otherwise put files in named folders.
+
+See the [`example/`](example/) directory for a sample of how to structure files.
+
+## How it works
+
+1. Walk `input-dir` for `.md` files (skip reserved names)
+2. Extract `title` from `#`, `description` from `>`
+3. Set `type` from parent dir name, `timestamp` from file mtime
+4. Write concept files with YAML frontmatter
+5. Generate `index.md` per directory — `# Contents` for files, `# Directories` for subdirs (recursive)
+
+## Output
+
+Each concept becomes a markdown file with YAML frontmatter:
+
+```yaml
+---
+type: "tables"
+title: "Customer Orders"
+description: "One row per completed customer order across all channels."
+timestamp: "2026-07-04T15:06:51+00:00"
+---
+
+Original body preserved as-is.
+```
+
+Every directory gets its own `index.md`:
+
+```markdown
+# Contents
+
+* [Customer Orders](orders.md) - One row per completed customer order across all channels.
+
+# Directories
+
+* [partitions](partitions/)
+```
+
+## OKF Conformance
+
+Generated bundles conform to [OKF v0.1](OKF_SPEC.md) (§9):
+
+- Every non-reserved `.md` has parseable YAML frontmatter with non-empty `type` ✓
+- Reserved filenames follow spec structure ✓
+- Consumers MUST tolerate missing optional fields, unknown types, broken links ✓
+
+## Project layout
+
+```
+okf-cli
+├── OKF_SPEC.md           # OKF specification
+├── pyproject.toml        # uv-managed Python project
+├── src/okf/cli.py        # Single-file CLI
+├── tests/test_cli.py     # Tests
+└── example/              # Sample input markdown
+```

okf_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+okf/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+okf/cli.py,sha256=5AHdKBCcbc9g1d7M85hLq7QyErZubJZ_B_I1nC8zpW8,7158
+okf_cli-0.1.0.dist-info/METADATA,sha256=m9szofWSVyHBsjzXONxWHtzmzPoNPvnFwGVFHPOt4_I,4595
+okf_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+okf_cli-0.1.0.dist-info/entry_points.txt,sha256=-FFFP-_REkdgRZ0-8urVv26KWHk-pTVbm3KRLjHTdV0,36
+okf_cli-0.1.0.dist-info/licenses/LICENSE,sha256=K7prhl8CGtmtTAoVj_Pcvmq-Z2RzJ9AYvbmdgfLQH3Y,1075
+okf_cli-0.1.0.dist-info/RECORD,,

okf_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

okf_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+okf = okf.cli:app

okf_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dheerapat Tookkane
+
+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.