jidoseal 0.1.1__tar.gz

jidoseal-0.1.1/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: jidoseal
+Version: 0.1.1
+Summary: JidoSeal local scan runner — certify your knowledge base on your own machine. 100% local, zero content egress.
+Author-email: JidoSeal <support@jidoseal.com>
+License: Proprietary
+Keywords: okf,knowledge-base,governance,markdown,frontmatter,local-first
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+
+# JidoSeal CLI
+
+Run JidoSeal's Self-Check over a folder of markdown, from your terminal, on your own machine.
+
+```
+Exactly what leaves your machine: nothing — 100% local, zero content egress.
+Your files, their names, and their contents never leave your device.
+```
+
+That is not a slogan bolted onto the docs — it is the first thing the command prints, on every
+run, before it reads a single file. The rest of this page explains exactly what the tool does,
+and just as importantly what it does not do.
+
+---
+
+## Install
+
+**One-liner:**
+
+```bash
+pipx install jidoseal && jidoseal --root .
+```
+
+`pipx` is the recommended install because it puts JidoSeal in its own isolated environment, so
+it can neither shadow nor be shadowed by anything else on your system. If you would rather use
+pip, a virtual environment does the same job:
+
+```bash
+python3 -m venv ~/.venvs/jidoseal
+~/.venvs/jidoseal/bin/pip install jidoseal
+~/.venvs/jidoseal/bin/jidoseal --root /path/to/your/notes
+```
+
+**From a local wheel:**
+
+```bash
+python3 -m pip wheel . --no-deps -w dist-cli      # from a checkout of this repo
+pipx install ./dist-cli/jidoseal-0.1.1-py3-none-any.whl
+```
+
+**From a checkout, with no install at all:**
+
+```bash
+python3 engine/local_runner.py --root /path/to/your/notes
+```
+
+Requires Python 3.9 or newer. Developed and exercised on 3.14.
+
+---
+
+## Usage
+
+```bash
+jidoseal --root /path/to/your/notes
+```
+
+```
+Exactly what leaves your machine: nothing — 100% local, zero content egress.
+Your files, their names, and their contents never leave your device.
+
+scanned 747 files in 1.42s — $0 · 100% local · nothing left this machine
+  Bronze  coverage: 98.1%
+  Silver  coverage: 84.3%
+  Gold    coverage: 61.0%
+manifest: /path/to/your/notes/.jidoseal/manifest.json
+progress: /path/to/your/notes/.jidoseal/progress.ndjson (run scan-20260918-143012-a1b2c3)
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--root <dir>` | **Required.** The folder to scan. Every `*.md` beneath it, recursively. |
+| `--include-machine` | Ignore the machine/transient excludes your `.jidoseal/config.yaml` declares, and scan every `*.md` under `--root`. With no config file there is nothing to ignore, so the flag changes nothing. |
+| `--version` | Print the version and exit. |
+| `--help` | Print usage and exit. |
+
+`python3 -m jidoseal --root <dir>` is identical to `jidoseal --root <dir>` — same entry point,
+same output, same banner.
+
+### A caution about `--include-machine`
+
+**The certified path does not use it.** When you buy a certificate, JidoSeal scans with your
+configured machine excludes applied — that is the corpus definition a certificate is issued
+against. `--include-machine` is a diagnostic: useful for seeing your whole tree, but the coverage
+percentages it prints are **not** the percentages your certificate would be based on. For a
+number that matches, run without the flag.
+
+### What it writes
+
+Two files, both inside `<root>/.jidoseal/`, both on your machine:
+
+- **`manifest.json`** — per file: a content hash, its current tier, which governance fields are
+  present, and exactly what is missing for Silver and Gold. This is the same artifact, in the
+  same format, that the certified engine path produces.
+- **`progress.ndjson`** — an append-only progress log, one JSON object per line, flushed to disk
+  as each file is scanned. Append-only on purpose: a new run adds to it rather than erasing the
+  history of previous ones.
+
+Nothing else is written, and nothing in your corpus is modified. This command **reads only**.
+
+---
+
+## Telling JidoSeal about your corpus — `.jidoseal/config.yaml`
+
+**Out of the box, nothing is excluded and nothing is assumed.** Every `*.md` file under
+`--root` is scanned, apart from OKF v0.2's two reserved filenames (`index.md` and `log.md`),
+which the standard itself puts outside a concept corpus. No folder name is special, no owner is
+invented, and no document type is inferred from a directory JidoSeal has never seen.
+
+That is deliberate. A scanner that silently drops files because their path matched somebody
+else's folder convention is reporting coverage over a corpus you did not choose — and the
+number it shows you would be wrong in a way you cannot see.
+
+If your corpus *does* have conventions, tell JidoSeal about them in an optional
+`<root>/.jidoseal/config.yaml`. Every key is optional; leaving the file out is exactly the
+default above. The config file itself is never part of the corpus (JidoSeal only ever reads
+`*.md`), and it is read by the scan engine itself — so the CLI, the local UI and the
+certificate-issuing path all see the same corpus definition.
+
+```yaml
+# Paths excluded as machine-generated or synced mirrors. Python regexes, matched against the
+# path relative to --root. `--include-machine` ignores this list for one run.
+machine_extra_excludes:
+  - "^Scratch/"          # transient working notes
+  - "/_drive/"           # a sync mirror — remediating it just fights the sync
+  - "(?i)-autogen-"      # generated files, by filename
+
+# Who owns a file when its frontmatter does not say. First match wins.
+owner_map:
+  - pattern: "^Accounts/"
+    owner: "dept:finance"
+
+# The owner for everything no rule above claims. With no `default_owner`, JidoSeal will not
+# invent one — and an apply refuses rather than writing an audit line it cannot attribute.
+default_owner: "human:jane-doe"
+
+# Optional: the identity recorded on each audit-log line. Defaults to `default_owner`.
+authority: "self:jane-doe"
+
+# Extra `type` inference for your own folders, applied AFTER JidoSeal's built-in conventions
+# (so a more specific built-in rule always still wins). Suggested at MEDIUM confidence, and
+# never written without your explicit Apply.
+propose_type_rules:
+  - pattern: "^Accounts/"
+    type: "finance-reference"
+```
+
+A malformed config is an error, not a shrug: an unknown key or a bad regex stops the run with
+a message naming the file, rather than quietly scanning a different corpus than you described.
+
+### Your config is recorded with the scan — and on the certificate
+
+Every scan prints one more line:
+
+```
+config:   sha256:9f2c…c41d
+```
+
+That is a SHA-256 of your `.jidoseal/config.yaml`, exactly as `sha256sum` computes it — check it
+yourself:
+
+```bash
+sha256sum .jidoseal/config.yaml
+```
+
+With no config file, the line reads `config:   absent:no-config-file`: running on the shipped
+neutral defaults is recorded as such, rather than left blank.
+
+Why it exists: this file decides which documents are in your corpus at all, so it is part of what
+a tier means. A certificate is bound to a Merkle root of your files, which says WHICH files were
+certified but not which definition selected them — so the same digest travels onto the
+certificate, inside its signature. It records your corpus definition; it does not restrict it.
+Nothing here leaves your machine on the free path, and the digest is one-way: it carries no
+folder name, no path and no rule text.
+
+---
+
+## What the tiers mean
+
+Tiers are objective, deterministic and pass/fail. There is no judgement call and no model
+involved anywhere in this path — a file either has a populated field or it does not, and the
+same corpus scanned twice gives the same answer.
+
+| Tier | Requires |
+| --- | --- |
+| **Bronze** | `type` |
+| **Silver** | Bronze, plus `title`, `description`, `timestamp`, `owner` |
+| **Gold** | Silver, plus `status`, `review_policy`, `reviewed_at`, `next_review_at` |
+
+"Populated" means carrying real content. A bare `title:` with nothing after it earns nothing.
+
+A file whose frontmatter fence exists but whose YAML will not parse is reported with
+`frontmatter_ok: false`. Those gaps cannot be closed by adding fields — the block has to be
+fixed by hand first.
+
+---
+
+## Honest scope — what JidoSeal does and does not certify
+
+**It does:**
+
+- Certify **presence and integrity of governance fields** — that the metadata your documents are
+  supposed to carry is actually there and actually populated, measured the same way every time.
+- Provide **hash provenance** — every file's content is hashed, so the manifest is bound to the
+  exact bytes on disk at scan time, and a later change is detectable.
+
+**It does not:**
+
+- **Attribute which change broke a spec.** JidoSeal will tell you that a document's governance
+  state is what it is now, and that its content hash differs from before. It does not diff your
+  documents or identify which edit — by you, by an agent, by anything else — was responsible.
+- **Judge whether your content is any good.** Tiers measure governance-field presence, not
+  quality, accuracy or usefulness of what you wrote.
+- **Read your prose.** The scan reads frontmatter to determine fields, and hashes file bytes. No
+  content is sent anywhere, because nothing is sent anywhere at all.
+
+---
+
+## Exactly what leaves your machine
+
+Nothing.
+
+```
+Exactly what leaves your machine: nothing — 100% local, zero content egress.
+Your files, their names, and their contents never leave your device.
+```
+
+This is enforced structurally, not by policy:
+
+- **The installed package does not contain networking code.** The wheel ships seven Python
+  modules — the complete set the scan needs and nothing more. The engine's network-capable
+  modules are not merely unused by this command; they are not in the distribution. You can
+  confirm that yourself with `unzip -l` on the wheel, or by listing the installed files.
+- **Its one dependency is PyYAML**, a YAML parser, used to read frontmatter. It has no network
+  capability. See "Dependencies" below.
+- **Static analysis enforces it in the test suite** — the modules on this path are AST-inspected
+  for any import of `socket`, `ssl`, `http`, `urllib`, `requests`, `httpx`, `aiohttp` and
+  friends, and the check fails the build if one appears.
+- **A runtime guard proves it on a real scan** — a full scan is executed inside a harness that
+  raises on any outbound connection or DNS lookup to a non-loopback address. It does not raise.
+
+If you would rather trust your own eyes than our test suite: run it with a network monitor on.
+That is the point of a local tool.
+
+Buying a certificate is a separate step that happens on jidoseal.com, not through this command.
+This CLI has no purchase path, no account, no telemetry, and no way to send anything anywhere.
+
+---
+
+## Dependencies
+
+One: **PyYAML**.
+
+We would rather it were zero, and it is worth being precise about why it is not. JidoSeal's
+frontmatter parser has always used PyYAML — it is the engine's single hard requirement, and the
+certified engine path uses the very same parser. Replacing it would mean writing a second YAML
+implementation, and a second implementation is a second set of edge cases: the day it disagrees
+with the first about a quoted date or a multi-line string, the CLI and your certificate disagree
+about your corpus. A pure parser with no network capability is a much better trade than a parity
+risk in the thing being certified.
+
+Everything else on the path is the Python standard library.
+
+---
+
+## Same engine as the certificate
+
+This is the point of the CLI, so it is worth stating plainly: `jidoseal --root <dir>` runs the
+**same code** the certified issuance path runs. Both call `okf_manifest.build_manifest()`; both
+tier files through the same `tier_of()`; both hash content the same way. The CLI is not a
+preview, a re-implementation or an approximation of the certified scoring — it is that scoring,
+invoked locally.
+
+The practical consequence: the tiers you see in your terminal are the tiers a certificate would
+attest to, for the same corpus, scanned the same way (that is, without `--include-machine`).

jidoseal-0.1.1/docs/CLI.md

@@ -0,0 +1,274 @@
+# JidoSeal CLI
+
+Run JidoSeal's Self-Check over a folder of markdown, from your terminal, on your own machine.
+
+```
+Exactly what leaves your machine: nothing — 100% local, zero content egress.
+Your files, their names, and their contents never leave your device.
+```
+
+That is not a slogan bolted onto the docs — it is the first thing the command prints, on every
+run, before it reads a single file. The rest of this page explains exactly what the tool does,
+and just as importantly what it does not do.
+
+---
+
+## Install
+
+**One-liner:**
+
+```bash
+pipx install jidoseal && jidoseal --root .
+```
+
+`pipx` is the recommended install because it puts JidoSeal in its own isolated environment, so
+it can neither shadow nor be shadowed by anything else on your system. If you would rather use
+pip, a virtual environment does the same job:
+
+```bash
+python3 -m venv ~/.venvs/jidoseal
+~/.venvs/jidoseal/bin/pip install jidoseal
+~/.venvs/jidoseal/bin/jidoseal --root /path/to/your/notes
+```
+
+**From a local wheel:**
+
+```bash
+python3 -m pip wheel . --no-deps -w dist-cli      # from a checkout of this repo
+pipx install ./dist-cli/jidoseal-0.1.1-py3-none-any.whl
+```
+
+**From a checkout, with no install at all:**
+
+```bash
+python3 engine/local_runner.py --root /path/to/your/notes
+```
+
+Requires Python 3.9 or newer. Developed and exercised on 3.14.
+
+---
+
+## Usage
+
+```bash
+jidoseal --root /path/to/your/notes
+```
+
+```
+Exactly what leaves your machine: nothing — 100% local, zero content egress.
+Your files, their names, and their contents never leave your device.
+
+scanned 747 files in 1.42s — $0 · 100% local · nothing left this machine
+  Bronze  coverage: 98.1%
+  Silver  coverage: 84.3%
+  Gold    coverage: 61.0%
+manifest: /path/to/your/notes/.jidoseal/manifest.json
+progress: /path/to/your/notes/.jidoseal/progress.ndjson (run scan-20260918-143012-a1b2c3)
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--root <dir>` | **Required.** The folder to scan. Every `*.md` beneath it, recursively. |
+| `--include-machine` | Ignore the machine/transient excludes your `.jidoseal/config.yaml` declares, and scan every `*.md` under `--root`. With no config file there is nothing to ignore, so the flag changes nothing. |
+| `--version` | Print the version and exit. |
+| `--help` | Print usage and exit. |
+
+`python3 -m jidoseal --root <dir>` is identical to `jidoseal --root <dir>` — same entry point,
+same output, same banner.
+
+### A caution about `--include-machine`
+
+**The certified path does not use it.** When you buy a certificate, JidoSeal scans with your
+configured machine excludes applied — that is the corpus definition a certificate is issued
+against. `--include-machine` is a diagnostic: useful for seeing your whole tree, but the coverage
+percentages it prints are **not** the percentages your certificate would be based on. For a
+number that matches, run without the flag.
+
+### What it writes
+
+Two files, both inside `<root>/.jidoseal/`, both on your machine:
+
+- **`manifest.json`** — per file: a content hash, its current tier, which governance fields are
+  present, and exactly what is missing for Silver and Gold. This is the same artifact, in the
+  same format, that the certified engine path produces.
+- **`progress.ndjson`** — an append-only progress log, one JSON object per line, flushed to disk
+  as each file is scanned. Append-only on purpose: a new run adds to it rather than erasing the
+  history of previous ones.
+
+Nothing else is written, and nothing in your corpus is modified. This command **reads only**.
+
+---
+
+## Telling JidoSeal about your corpus — `.jidoseal/config.yaml`
+
+**Out of the box, nothing is excluded and nothing is assumed.** Every `*.md` file under
+`--root` is scanned, apart from OKF v0.2's two reserved filenames (`index.md` and `log.md`),
+which the standard itself puts outside a concept corpus. No folder name is special, no owner is
+invented, and no document type is inferred from a directory JidoSeal has never seen.
+
+That is deliberate. A scanner that silently drops files because their path matched somebody
+else's folder convention is reporting coverage over a corpus you did not choose — and the
+number it shows you would be wrong in a way you cannot see.
+
+If your corpus *does* have conventions, tell JidoSeal about them in an optional
+`<root>/.jidoseal/config.yaml`. Every key is optional; leaving the file out is exactly the
+default above. The config file itself is never part of the corpus (JidoSeal only ever reads
+`*.md`), and it is read by the scan engine itself — so the CLI, the local UI and the
+certificate-issuing path all see the same corpus definition.
+
+```yaml
+# Paths excluded as machine-generated or synced mirrors. Python regexes, matched against the
+# path relative to --root. `--include-machine` ignores this list for one run.
+machine_extra_excludes:
+  - "^Scratch/"          # transient working notes
+  - "/_drive/"           # a sync mirror — remediating it just fights the sync
+  - "(?i)-autogen-"      # generated files, by filename
+
+# Who owns a file when its frontmatter does not say. First match wins.
+owner_map:
+  - pattern: "^Accounts/"
+    owner: "dept:finance"
+
+# The owner for everything no rule above claims. With no `default_owner`, JidoSeal will not
+# invent one — and an apply refuses rather than writing an audit line it cannot attribute.
+default_owner: "human:jane-doe"
+
+# Optional: the identity recorded on each audit-log line. Defaults to `default_owner`.
+authority: "self:jane-doe"
+
+# Extra `type` inference for your own folders, applied AFTER JidoSeal's built-in conventions
+# (so a more specific built-in rule always still wins). Suggested at MEDIUM confidence, and
+# never written without your explicit Apply.
+propose_type_rules:
+  - pattern: "^Accounts/"
+    type: "finance-reference"
+```
+
+A malformed config is an error, not a shrug: an unknown key or a bad regex stops the run with
+a message naming the file, rather than quietly scanning a different corpus than you described.
+
+### Your config is recorded with the scan — and on the certificate
+
+Every scan prints one more line:
+
+```
+config:   sha256:9f2c…c41d
+```
+
+That is a SHA-256 of your `.jidoseal/config.yaml`, exactly as `sha256sum` computes it — check it
+yourself:
+
+```bash
+sha256sum .jidoseal/config.yaml
+```
+
+With no config file, the line reads `config:   absent:no-config-file`: running on the shipped
+neutral defaults is recorded as such, rather than left blank.
+
+Why it exists: this file decides which documents are in your corpus at all, so it is part of what
+a tier means. A certificate is bound to a Merkle root of your files, which says WHICH files were
+certified but not which definition selected them — so the same digest travels onto the
+certificate, inside its signature. It records your corpus definition; it does not restrict it.
+Nothing here leaves your machine on the free path, and the digest is one-way: it carries no
+folder name, no path and no rule text.
+
+---
+
+## What the tiers mean
+
+Tiers are objective, deterministic and pass/fail. There is no judgement call and no model
+involved anywhere in this path — a file either has a populated field or it does not, and the
+same corpus scanned twice gives the same answer.
+
+| Tier | Requires |
+| --- | --- |
+| **Bronze** | `type` |
+| **Silver** | Bronze, plus `title`, `description`, `timestamp`, `owner` |
+| **Gold** | Silver, plus `status`, `review_policy`, `reviewed_at`, `next_review_at` |
+
+"Populated" means carrying real content. A bare `title:` with nothing after it earns nothing.
+
+A file whose frontmatter fence exists but whose YAML will not parse is reported with
+`frontmatter_ok: false`. Those gaps cannot be closed by adding fields — the block has to be
+fixed by hand first.
+
+---
+
+## Honest scope — what JidoSeal does and does not certify
+
+**It does:**
+
+- Certify **presence and integrity of governance fields** — that the metadata your documents are
+  supposed to carry is actually there and actually populated, measured the same way every time.
+- Provide **hash provenance** — every file's content is hashed, so the manifest is bound to the
+  exact bytes on disk at scan time, and a later change is detectable.
+
+**It does not:**
+
+- **Attribute which change broke a spec.** JidoSeal will tell you that a document's governance
+  state is what it is now, and that its content hash differs from before. It does not diff your
+  documents or identify which edit — by you, by an agent, by anything else — was responsible.
+- **Judge whether your content is any good.** Tiers measure governance-field presence, not
+  quality, accuracy or usefulness of what you wrote.
+- **Read your prose.** The scan reads frontmatter to determine fields, and hashes file bytes. No
+  content is sent anywhere, because nothing is sent anywhere at all.
+
+---
+
+## Exactly what leaves your machine
+
+Nothing.
+
+```
+Exactly what leaves your machine: nothing — 100% local, zero content egress.
+Your files, their names, and their contents never leave your device.
+```
+
+This is enforced structurally, not by policy:
+
+- **The installed package does not contain networking code.** The wheel ships seven Python
+  modules — the complete set the scan needs and nothing more. The engine's network-capable
+  modules are not merely unused by this command; they are not in the distribution. You can
+  confirm that yourself with `unzip -l` on the wheel, or by listing the installed files.
+- **Its one dependency is PyYAML**, a YAML parser, used to read frontmatter. It has no network
+  capability. See "Dependencies" below.
+- **Static analysis enforces it in the test suite** — the modules on this path are AST-inspected
+  for any import of `socket`, `ssl`, `http`, `urllib`, `requests`, `httpx`, `aiohttp` and
+  friends, and the check fails the build if one appears.
+- **A runtime guard proves it on a real scan** — a full scan is executed inside a harness that
+  raises on any outbound connection or DNS lookup to a non-loopback address. It does not raise.
+
+If you would rather trust your own eyes than our test suite: run it with a network monitor on.
+That is the point of a local tool.
+
+Buying a certificate is a separate step that happens on jidoseal.com, not through this command.
+This CLI has no purchase path, no account, no telemetry, and no way to send anything anywhere.
+
+---
+
+## Dependencies
+
+One: **PyYAML**.
+
+We would rather it were zero, and it is worth being precise about why it is not. JidoSeal's
+frontmatter parser has always used PyYAML — it is the engine's single hard requirement, and the
+certified engine path uses the very same parser. Replacing it would mean writing a second YAML
+implementation, and a second implementation is a second set of edge cases: the day it disagrees
+with the first about a quoted date or a multi-line string, the CLI and your certificate disagree
+about your corpus. A pure parser with no network capability is a much better trade than a parity
+risk in the thing being certified.
+
+Everything else on the path is the Python standard library.
+
+---
+
+## Same engine as the certificate
+
+This is the point of the CLI, so it is worth stating plainly: `jidoseal --root <dir>` runs the
+**same code** the certified issuance path runs. Both call `okf_manifest.build_manifest()`; both
+tier files through the same `tier_of()`; both hash content the same way. The CLI is not a
+preview, a re-implementation or an approximation of the certified scoring — it is that scoring,
+invoked locally.
+
+The practical consequence: the tiers you see in your terminal are the tiers a certificate would
+attest to, for the same corpus, scanned the same way (that is, without `--include-machine`).