okf-cli 0.4.1__tar.gz → 0.4.3__tar.gz

{okf_cli-0.4.1 → okf_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: okf-cli
-Version: 0.4.1
+Version: 0.4.3
 Summary: Open Knowledge Format tooling
 License: MIT License
         

{okf_cli-0.4.1 → okf_cli-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "okf-cli"
-version = "0.4.1"
+version = "0.4.3"
 description = "Open Knowledge Format tooling"
 readme = "README.md"
 license = { file = "LICENSE" }

okf_cli-0.4.3/skills/writing-knowledge-base/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: writing-knowledge-base
+description: Turn user provided content on any topic into a plain Markdown knowledge base. Invoked as /writing-knowledge-base with content to convert.
+license: MIT
+---
+
+# Knowledge Base Construction
+
+Convert the user's content directly into a structured Markdown knowledge base. Don't ask clarifying questions unless the content is genuinely unusable (e.g. empty or unintelligible) — infer structure, terminology, and grouping from what's given, and note any gaps inline rather than blocking on them.
+
+## Workflow
+
+1. Read the content and split it into coherent concepts (one idea per file — prefer several small linked files over one large one).
+1. Create new directory with a name relative to the content user provide (e.g. `italian-food`, `turbocharge`, `formula-one`, etc. ).
+1. Group concepts into type directories that fit the material's own structure. Let the content dictate the categories — e.g. `recipes/`, `policies/`, `species/`, `procedures/`, `terms/`, `people/`, `events/` — whatever natural groupings emerge. Don't force a data/tech taxonomy onto non-technical content.
+1. Write each file using the format below, preserving the user's own terminology and facts. Never invent details, numbers, names, or steps that weren't given.
+1. Add relative Markdown links between related concepts.
+1. Save all files under an input directory your just created.
+
+## Example file tree
+
+```
+cooking/
+  recipes/
+    italian/
+      lasagna.md
+      carbonara.md
+    japanese/
+      ramen.md
+      sushi.md
+  techniques/
+    knife-skills.md
+    emulsion.md
+  ingredients/
+    eggs.md
+    flour-types.md
+  faq.md
+  common-mistake.md
+```
+
+- Root files (e.g. `faq.md`) are allowed
+- File can be nested as deep as necessary and semantically sound.
+
+## File format
+
+```markdown
+# Clear Concept Title
+
+> One-sentence factual summary.
+
+Body: context, details, steps, examples, caveats — whatever fits the concept.
+```
+
+- First line `# Title`, then a `>` description, then body detail.
+- Use headings, lists, tables, or code blocks as they help retrieval — not all concepts need all of these.
+- One concept per file. Directory name per type (e.g. `recipes/lasagna.md` → type `recipes`).
+- Lowercase, stable filenames, no spaces.
+- No `index.md`, `log.md`, `README.md` as concepts — bundler reserves these.
+- No YAML frontmatter in source files
+
+Do not fabricate any information on your own, use only what user provided to you.

{okf_cli-0.4.1 → okf_cli-0.4.3}/src/okf/commands/bundle.py

@@ -106,6 +106,13 @@ def bundle(
         typer.echo(f"Error: input directory '{input_dir}' not found", err=True)
         raise typer.Exit(code=1)
 
+    if src.resolve() == dst.resolve():
+        typer.echo(
+            "Error: input and output directories must be different",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
     if dst.exists():
         if not force:
             typer.echo(
@@ -297,11 +304,14 @@ def bundle(
         f"# Knowledge Base: {dst.name}\n\n"
         f"You are in an OKF knowledge base called **{dst.name}**.\n\n"
         "## Getting Started\n\n"
-        "Read [index.md](index.md) first — it lists all concepts and subdirectories.\n\n"
+        "Read [index.md](index.md) first — it lists all concepts "
+        "and subdirectories.\n\n"
         "## Navigation\n\n"
         "- Follow markdown links between concepts.\n"
-        "- Each `.md` file has YAML frontmatter with `type`, `title`, `description`.\n"
+        "- Each `.md` file has YAML frontmatter with `type`, `title`, "
+        "`description`.\n"
         "- Subdirectories group related concepts by topic.\n"
-        "- Cross-links (e.g. `[Customers](/tables/customers.md)`) express relationships.\n",
+        "- Cross-links (e.g. `[Customers](/tables/customers.md)`) "
+        "express relationships.\n",
         encoding="utf-8",
     )

{okf_cli-0.4.1 → okf_cli-0.4.3}/tests/cli/test_bundle.py

@@ -178,6 +178,16 @@ def test_bundle_refuses_overwrite_without_force(tmp_path: Path):
     assert "--force" in result.output
 
 
+def test_bundle_refuses_same_input_and_output_dir(tmp_path: Path):
+    src = tmp_path / "notes"
+    src.mkdir()
+    _write_fixture(src, {"tables/a.md": "# A\n\n> Desc.\n"})
+
+    result = runner.invoke(app, ["bundle", str(src), str(src), "--force"])
+    assert result.exit_code == 1, result.output
+    assert "must be different" in result.output
+
+
 def test_bundle_no_md_files(tmp_path: Path):
     src = tmp_path / "notes"
     dst = tmp_path / "bundle"
@@ -342,7 +352,9 @@ def test_bundle_warns_broken_local_markdown_link(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](customers.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](customers.md)."
+            ),
         },
     )
 
@@ -358,8 +370,12 @@ def test_bundle_accepts_valid_relative_and_absolute_local_links(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](./customers.md).",
-            "tables/customers.md": "# Customers\n\n> All customers.\n\nSee [Orders](/tables/orders.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](./customers.md)."
+            ),
+            "tables/customers.md": (
+                "# Customers\n\n> All customers.\n\nSee [Orders](/tables/orders.md)."
+            ),
         },
     )
 
@@ -397,7 +413,9 @@ def test_bundle_warns_markdown_link_outside_bundle(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Secret](../../secret.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Secret](../../secret.md)."
+            ),
         },
     )
 
@@ -413,7 +431,9 @@ def test_bundle_strict_links_fails_on_broken_local_link(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](customers.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](customers.md)."
+            ),
         },
     )
 
@@ -429,8 +449,12 @@ def test_bundle_strict_links_passes_with_valid_local_links(tmp_path: Path):
     _write_fixture(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](./customers.md).",
-            "tables/customers.md": "# Customers\n\n> All customers.\n\nBody.",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](./customers.md)."
+            ),
+            "tables/customers.md": (
+                "# Customers\n\n> All customers.\n\nBody."
+            ),
         },
     )
 

{okf_cli-0.4.1 → okf_cli-0.4.3}/tests/e2e/test_e2e.py

@@ -248,7 +248,9 @@ def test_bundle_warns_broken_link(tmp_path: Path):
     _write(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](customers.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](customers.md)."
+            ),
         },
     )
 
@@ -264,7 +266,9 @@ def test_bundle_accepts_valid_links(tmp_path: Path):
     _write(
         src,
         {
-            "tables/orders.md": "# Orders\n\n> One row.\n\nSee [Customers](./customers.md).",
+            "tables/orders.md": (
+                "# Orders\n\n> One row.\n\nSee [Customers](./customers.md)."
+            ),
             "tables/customers.md": "# Customers\n\n> All.\n\nBody.",
         },
     )
@@ -740,7 +744,10 @@ def test_show_valid_concept(tmp_path: Path):
 
 
 def test_show_with_md_extension_appended(tmp_path: Path):
-    """show always appends .md — passing tables/orders.md looks for tables/orders.md.md."""
+    """show always appends .md.
+
+    Passing tables/orders.md looks for tables/orders.md.md.
+    """
     d = tmp_path / "bundle"
     d.mkdir()
     _write(d, {"tables/orders.md": "---\ntype: tables\n---\n\nBody."})

okf_cli-0.4.1/skills/writing-knowledge-base/SKILL.md

@@ -1,127 +0,0 @@
----
-name: writing-knowledge-base
-description: Help a domain expert turn their knowledge into a plain Markdown knowledge base that can be bundled into OKF with `okf bundle`. Use reference/knowledge-base.md for content guidance and reference/example/ for structure and writing style.
-license: MIT
----
-
-# Knowledge Base Construction
-
-Help a domain expert turn their knowledge into a plain Markdown knowledge base that can be bundled into OKF with `okf bundle`. Use `reference/knowledge-base.md` for content guidance and `reference/example/` for structure and writing style.
-
-## Role
-
-Act as facilitator and editor, not an authority on the domain.
-
-- Ask focused questions when facts, scope, ownership, terminology, or relationships are unclear.
-- Never invent domain facts, metrics, schemas, URLs, SLAs, or procedures.
-- Preserve the expert's terminology and meaning; improve structure and clarity only.
-- Prefer several small, linked concepts over one large document.
-
-## Workflow
-
-1. Learn the domain, audience, and intended use of the knowledge base.
-
-1. Identify concepts and group them into directories such as `datasets/`, `tables/`, `playbooks/`, or other domain-appropriate types.
-
-1. Propose a file tree before writing many files. Get expert agreement on names and grouping.
-
-1. Draft or update one concept at a time. Show the draft and ask for corrections.
-
-1. Add links between related concepts using relative Markdown links.
-
-1. Review for missing context, contradictions, stale-looking operational details, and unsupported assumptions.
-
-1. Keep source files under a chosen input directory, following `reference/example/`.
-
-1. When ready, explain how to bundle and validate:
-
-   ```bash
-   okf bundle <input-dir> <output-dir> --default-type reference
-   okf validate <output-dir>
-   ```
-
-   Use `--default-type` only when root-level files exist. Prefer placing concepts in named directories.
-
-## References
-
-Read these files before drafting when more detail is needed:
-
-- `reference/knowledge-base.md` — what a good knowledge base and concept file look like.
-- `reference/example/` — complete example input structure copied from this project.
-
-## File format
-
-Every concept should normally use this format:
-
-```markdown
-# Clear Concept Title
-
-> One-sentence summary of this concept.
-
-Body content with useful context, structure, examples, procedures, or schema.
-```
-
-Rules:
-
-- First line: `# Title`.
-- Follow with a `>` description block. Keep it concise and factual.
-- Put detailed knowledge in the body after the description.
-- Use headings, lists, tables, and code blocks where they help retrieval.
-- Use one file per concept.
-- Directory name becomes OKF `type`: `tables/orders.md` becomes type `tables`.
-- Use lowercase, stable, descriptive filenames. Avoid spaces when possible.
-- Do not create `index.md`, `log.md`, or `README.md` as concepts in source input; bundling reserves them.
-- Do not add frontmatter to source files. `okf bundle` generates it.
-
-## Concept guidance
-
-For data assets, capture:
-
-- What asset contains and why it exists.
-- Grain or unit of each record.
-- Ownership and consumers, if known.
-- Schema with field name, type, and meaning.
-- Keys, joins, partitions, freshness, quality limits, and known caveats.
-
-For processes and playbooks, capture:
-
-- Trigger and scope.
-- Ordered steps.
-- Decision points and expected outcomes.
-- Owners, escalation paths, tools, and safety constraints.
-- Links to related assets and procedures.
-
-For domain concepts, capture:
-
-- Definition and boundaries.
-- Synonyms and terms that should not be confused.
-- Examples and counterexamples.
-- Related concepts and source evidence.
-
-## Questions to ask
-
-Ask only questions that unblock useful writing. Examples:
-
-- Who uses this knowledge and what decision should it support?
-- What is the smallest useful concept here?
-- What does each term mean in this domain?
-- What is the source of truth?
-- What is the record grain, owner, freshness, or SLA?
-- What concepts does this depend on or relate to?
-- What should a reader do when this process fails?
-- Which details are confirmed, approximate, deprecated, or unknown?
-
-## Quality check
-
-Before declaring the knowledge base ready, check:
-
-- Every concept has a title and one-sentence description.
-- Each file contains one coherent concept.
-- Directory grouping reflects meaningful concept types.
-- Links point to the correct relative files.
-- No facts were added without expert confirmation.
-- Procedures include ownership and failure handling where relevant.
-- Tables include field meaning, not only field names and types.
-- Unknown or disputed details are visible.
-- Source remains readable as plain Markdown.
-- Generated output passes `okf validate <output-dir>`.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/README.md

@@ -1,12 +0,0 @@
-# OKF Example
-
-This directory contains plain markdown files written by domain experts.
-Run `okf bundle` to convert them into an OKF-conformant knowledge bundle.
-
-```bash
-# From repo root:
-uv run okf bundle example output-bundle
-
-# With a default type for root-level files (if any):
-uv run okf bundle example output-bundle --default-type reference
-```

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/datasets/sales.md

@@ -1,7 +0,0 @@
-# Sales Dataset
-
-> All sales-related tables for the retail business.
-
-Contains transactional data from both online and in-store channels.
-
-Key tables include [orders](../tables/orders.md) and [customers](../tables/customers.md).

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/domain.md

@@ -1,6 +0,0 @@
-# Our Domain
-
-> What is our domain of interest
-
-Our domain of interest is to allow domain expert to easily shared their
-knowledge with OKF bundle.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/loose/deep/no-heading.md

@@ -1,4 +0,0 @@
-I am a file deep in a subdirectory with no heading at all.
-
-Type comes from the directory name, title is omitted, and description is
-derived from this body text.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/loose/no-desc.md

@@ -1,6 +0,0 @@
-# Has Title But No Desc
-
-This file has a proper `# Title` but no `>` blockquote description.
-
-It should still be bundled: title extracted normally, description taken
-from the first 80 characters of the body as a fallback.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/loose/no-title.md

@@ -1,5 +0,0 @@
-No heading at all — this file has no `# Title` line and no `>` description block.
-
-It should still be bundled: title omitted from frontmatter, description
-derived from the first 80 characters of this body text verbatim, with
-newlines collapsed to spaces.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/playbooks/incident-response.md

@@ -1,14 +0,0 @@
-# Data Freshness Incident
-
-> Steps to triage a freshness alert on the orders pipeline.
-
-## Trigger
-
-A freshness alert fires when the [orders](../tables/orders.md) table lags more than 30 minutes behind its expected SLA.
-
-## Steps
-
-1. Check the ingestion job dashboard.
-1. Verify upstream source connectivity.
-1. Inspect the [Sales Dataset](../datasets/sales.md) for recent changes.
-1. Notify the data engineering team if the issue persists.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/playbooks/oncall-guide.md

@@ -1,13 +0,0 @@
-# On-call Guide
-
-> Quick reference for on-call data engineers.
-
-## Channels
-
-- **Critical alerts**: PagerDuty
-- **Team chat**: #data-eng on Slack
-- **Escalation**: Contact the data engineering lead
-
-## Common Issues
-
-See [Incident Response](incident-response.md) for data freshness issues.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/tables/customers.md

@@ -1,16 +0,0 @@
-# Customers
-
-> One row per registered customer.
-
-## Schema
-
-| Column      | Type      | Description                |
-| ----------- | --------- | -------------------------- |
-| customer_id | STRING    | Unique customer identifier |
-| name        | STRING    | Customer display name      |
-| email       | STRING    | Customer email address     |
-| created_at  | TIMESTAMP | Account creation date      |
-
-## Notes
-
-Referenced by [orders](orders.md) via `customer_id`.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/tables/orders.md

@@ -1,16 +0,0 @@
-# Customer Orders
-
-> One row per completed customer order across all channels.
-
-## Schema
-
-| Column      | Type      | Description               |
-| ----------- | --------- | ------------------------- |
-| order_id    | STRING    | Unique order identifier   |
-| customer_id | STRING    | Foreign key to customers  |
-| total_usd   | NUMERIC   | Order total in USD        |
-| placed_at   | TIMESTAMP | When the order was placed |
-
-## Notes
-
-Part of the [Sales Dataset](../datasets/sales.md). Joined with [customers](customers.md) on `customer_id`.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/tables/partitions/2026/q1/jan/january.md

@@ -1,5 +0,0 @@
-# January 2026
-
-> Orders placed in January 2026.
-
-Monthly slice of the [daily](../../../daily.md) partition.

okf_cli-0.4.1/skills/writing-knowledge-base/reference/example/tables/partitions/daily.md

@@ -1,12 +0,0 @@
-# Daily Partition
-
-> One partition per day for the orders table.
-
-Part of the [orders](../../tables/orders.md) table's partitioning scheme.
-
-## Schema
-
-| Column         | Type  | Description                     |
-| -------------- | ----- | ------------------------------- |
-| partition_date | DATE  | The date of this partition      |
-| row_count      | INT64 | Number of rows in the partition |

okf_cli-0.4.1/skills/writing-knowledge-base/reference/knowledge-base.md

@@ -1,65 +0,0 @@
-# Knowledge Base Reference
-
-Knowledge base is plain Markdown organized as small, linked concepts.
-Domain expert supplies facts. Agent supplies structure, questions, and editing.
-
-## Basic concept
-
-```markdown
-# Customer Orders
-
-> One row per completed customer order across all channels.
-
-## Schema
-
-| Column | Type | Description |
-|--------|------|-------------|
-| order_id | STRING | Unique order identifier |
-| customer_id | STRING | Foreign key to customers |
-| total_usd | NUMERIC | Order total in USD |
-
-## Notes
-
-Part of the [Sales Dataset](../datasets/sales.md).
-```
-
-## Source structure
-
-```text
-knowledge-base/
-├── domain.md                    # Optional root-level domain overview
-├── datasets/                    # Dataset concepts
-│   └── sales.md
-├── tables/                      # Table concepts
-│   ├── customers.md
-│   ├── orders.md
-│   └── partitions/
-│       └── daily.md
-└── playbooks/                   # Operational procedure concepts
-    ├── incident-response.md
-    └── oncall-guide.md
-```
-
-Directory names become OKF concept types when bundled. For example,
-`tables/orders.md` becomes a concept with type `tables` and ID
-`tables/orders`.
-
-## Writing rules
-
-- Use one coherent concept per file.
-- Start with `# Title`.
-- Follow title with a concise `>` description.
-- Put detail in the body.
-- Link related concepts with relative Markdown links.
-- Use lowercase, stable filenames.
-- Do not add YAML frontmatter to source files; bundler generates it.
-
-## Data concept checklist
-
-Capture what asset contains, record grain, owner, consumers, schema, keys,
-joins, partitions, freshness, quality limits, and caveats when known.
-
-## Playbook checklist
-
-Capture trigger, scope, ordered steps, decisions, expected outcomes, owners,
-escalation, tools, and failure handling when known.