scriptoria 0.9.0__tar.gz → 0.10.0__tar.gz

{scriptoria-0.9.0 → scriptoria-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: scriptoria
-Version: 0.9.0
+Version: 0.10.0
 Summary: Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base
 Project-URL: Homepage, https://github.com/coredipper/scriptorium
 Project-URL: Changelog, https://github.com/coredipper/scriptorium/blob/main/CHANGELOG.md
@@ -51,6 +51,7 @@ uv run --project scrip scrip --help
 
 | Command | What it does |
 |---|---|
+| `scrip init [DIR]` | Create the root skeleton — `vault/{raw,facts,wiki}/` plus the `.kb/` cache and its manifest — in `DIR` (default: the current directory). Idempotent in an existing root; refuses to nest a new instance inside one. |
 | `scrip status` | Report `STALE` / `OK` / `UNCOMPILED` artifacts from the dependency graph. `--no-cache` recomputes from files; `--rebuild-manifest` regenerates the cache. |
 | `scrip verify` | Check every provenance anchor still resolves to text in its source; check referenced sources exist and `claim_id`s are unique. Fails on `BROKEN` and `AMBIGUOUS` by default; `--allow-ambiguous` downgrades `AMBIGUOUS` to a warning. |
 | `scrip query [claims\|entities\|edges\|contradictions\|reconciliations]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
@@ -67,7 +68,8 @@ uv run --project scrip scrip --help
 | `scrip pageindex search "<question>" [--source raw/<slug>]` | Search cached PageIndex sections, returning only snippets mapped back to canonical `vault/raw/` text. |
 | `scrip watch` / `scrip unlock` | Watch vault health in a poll loop; clear a stale advisory write lock. |
 
-Every command accepts `--root DIR` and `--json`.
+Every command accepts `--root DIR` and `--json` (`init` takes its target as a
+positional path instead of `--root`).
 
 The optional `scrip-harness` package adds the model-bearing commands, including
 `scrip-harness answer "<question>"`, which gathers evidence with these primitives

{scriptoria-0.9.0 → scriptoria-0.10.0}/README.md

@@ -20,6 +20,7 @@ uv run --project scrip scrip --help
 
 | Command | What it does |
 |---|---|
+| `scrip init [DIR]` | Create the root skeleton — `vault/{raw,facts,wiki}/` plus the `.kb/` cache and its manifest — in `DIR` (default: the current directory). Idempotent in an existing root; refuses to nest a new instance inside one. |
 | `scrip status` | Report `STALE` / `OK` / `UNCOMPILED` artifacts from the dependency graph. `--no-cache` recomputes from files; `--rebuild-manifest` regenerates the cache. |
 | `scrip verify` | Check every provenance anchor still resolves to text in its source; check referenced sources exist and `claim_id`s are unique. Fails on `BROKEN` and `AMBIGUOUS` by default; `--allow-ambiguous` downgrades `AMBIGUOUS` to a warning. |
 | `scrip query [claims\|entities\|edges\|contradictions\|reconciliations]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
@@ -36,7 +37,8 @@ uv run --project scrip scrip --help
 | `scrip pageindex search "<question>" [--source raw/<slug>]` | Search cached PageIndex sections, returning only snippets mapped back to canonical `vault/raw/` text. |
 | `scrip watch` / `scrip unlock` | Watch vault health in a poll loop; clear a stale advisory write lock. |
 
-Every command accepts `--root DIR` and `--json`.
+Every command accepts `--root DIR` and `--json` (`init` takes its target as a
+positional path instead of `--root`).
 
 The optional `scrip-harness` package adds the model-bearing commands, including
 `scrip-harness answer "<question>"`, which gathers evidence with these primitives

{scriptoria-0.9.0 → scriptoria-0.10.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name on PyPI is `scriptoria` (scrip/scriptorium were taken); the
 # CLI command and the import package both remain `scrip`.
 name = "scriptoria"
-version = "0.9.0"
+version = "0.10.0"
 description = "Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base"
 readme = "README.md"
 requires-python = ">=3.10"

{scriptoria-0.9.0 → scriptoria-0.10.0}/src/scrip/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 
 # --- canonical vault layout ------------------------------------------------
 # ``root`` is the repo/instance root: the directory containing ``vault/``.

{scriptoria-0.9.0 → scriptoria-0.10.0}/src/scrip/blocks.py

@@ -38,43 +38,45 @@ def split_blocks(text: str) -> list[dict]:
     # Use splitlines(keepends=True): its boundary set (form feed, NEL, U+2028/9,
     # …) is part of the deterministic segmentation contract — io.StringIO only
     # splits on \r/\n and would re-hash existing blocks that contain those chars.
-    ranges: list[list[int]] = []  # [start, end] per block
-    cur: list[int] | None = None
+    # Emit blocks in a single pass: a running [cur_start, cur_end] paragraph is
+    # flushed at each boundary, so no intermediate `ranges` list is allocated.
+    out: list[dict] = []
+    seen: dict[str, int] = {}
+
+    def emit(s: int, e: int) -> None:
+        slice_text = text[s:e]
+        out.append(
+            {
+                "block_id": _block_id(slice_text, seen),
+                "span": [s, e],
+                "hash": hashing.sha256_text(slice_text),
+            }
+        )
+
+    cur_start: int | None = None
+    cur_end = 0
     start = 0
 
     for line in text.splitlines(keepends=True):
         end = start + len(line)
         if _is_blank(line):
-            if cur is not None:
-                ranges.append(cur)
-                cur = None
+            if cur_start is not None:
+                emit(cur_start, cur_end)
+                cur_start = None
         elif _is_heading(line):
-            if cur is not None:
-                ranges.append(cur)
-                cur = None
-            ranges.append([start, end])  # a heading is its own block
+            if cur_start is not None:
+                emit(cur_start, cur_end)
+                cur_start = None
+            emit(start, end)  # a heading is its own block
         else:
-            if cur is None:
-                cur = [start, end]
-            else:
-                cur[1] = end
+            if cur_start is None:
+                cur_start = start
+            cur_end = end
         start = end
 
-    if cur is not None:
-        ranges.append(cur)
+    if cur_start is not None:
+        emit(cur_start, cur_end)
 
-    out: list[dict] = []
-    seen: dict[str, int] = {}
-    for s, e in ranges:
-        slice_text = text[s:e]
-        block_id = _block_id(slice_text, seen)
-        out.append(
-            {
-                "block_id": block_id,
-                "span": [s, e],
-                "hash": hashing.sha256_text(slice_text),
-            }
-        )
     return out
 
 

{scriptoria-0.9.0 → scriptoria-0.10.0}/src/scrip/cli.py

@@ -35,12 +35,20 @@ def _safe_slug(slug: str, what: str = "slug") -> str:
 # --------------------------------------------------------------------------- #
 # Root resolution
 # --------------------------------------------------------------------------- #
+def _looks_like_root(cand: Path) -> bool:
+    """True if ``cand`` looks like a scriptorium instance root: a directory
+    containing ``vault/`` plus either ``SPEC.md`` or ``.kb/``."""
+    return (cand / "vault").is_dir() and (
+        (cand / "SPEC.md").exists() or (cand / ".kb").is_dir()
+    )
+
+
 def resolve_root(root_arg: str | None) -> Path:
     """Return the scriptorium root.
 
     With ``--root`` the path is used verbatim (must be a directory). Otherwise we
-    walk up from the cwd for the nearest ancestor that looks like an instance: a
-    directory containing ``vault/`` plus either ``SPEC.md`` or ``.kb/``.
+    walk up from the cwd for the nearest ancestor that looks like an instance
+    (see :func:`_looks_like_root`).
     """
     if root_arg:
         root = Path(root_arg).expanduser().resolve()
@@ -50,13 +58,12 @@ def resolve_root(root_arg: str | None) -> Path:
 
     cur = Path.cwd().resolve()
     for cand in (cur, *cur.parents):
-        if (cand / "vault").is_dir() and (
-            (cand / "SPEC.md").exists() or (cand / ".kb").is_dir()
-        ):
+        if _looks_like_root(cand):
             return cand
     raise errors.UsageError(
         "could not locate a scriptorium root (looked for a parent with vault/ and "
-        "SPEC.md or .kb/). Pass --root explicitly."
+        "SPEC.md or .kb/). Run `scrip init` to start one here, or pass --root "
+        "explicitly."
     )
 
 
@@ -68,6 +75,58 @@ def _emit(payload: dict) -> None:
 # --------------------------------------------------------------------------- #
 # Subcommand handlers  ->  return an int exit code
 # --------------------------------------------------------------------------- #
+def cmd_init(args: argparse.Namespace) -> int:
+    from . import graph, manifest_path
+
+    target = Path(args.path or ".").expanduser().resolve()
+    if target.exists() and not target.is_dir():
+        raise errors.UsageError(f"init target is not a directory: {target}")
+    if _looks_like_root(target):
+        if args.json:
+            _emit({"root": str(target), "status": "exists", "created": []})
+        else:
+            print(f"already a scriptorium root: {target} (nothing to do)")
+        return 0
+    # Refuse to create a nested instance: an inner vault/ would shadow the outer
+    # root for every command run beneath it (resolve_root stops at the nearest
+    # ancestor).
+    for cand in target.parents:
+        if _looks_like_root(cand):
+            raise errors.UsageError(
+                f"refusing to create a nested scriptorium: {target} is inside the "
+                f"root at {cand}. Run `scrip init` at that root, or pick a "
+                f"directory outside it."
+            )
+
+    created: list[str] = []
+    for rel in ("vault/raw", "vault/facts", "vault/wiki", ".kb"):
+        d = target / rel
+        if d.is_dir():
+            continue
+        if d.exists():
+            raise errors.UsageError(
+                f"cannot create {rel}/: a file already exists at {d}"
+            )
+        d.mkdir(parents=True, exist_ok=True)
+        created.append(rel + "/")
+    # Same as `scrip status --rebuild-manifest`: scan the (empty) vault and write
+    # the .kb/manifest.json cache, so the instance starts warm and detectable.
+    graph.compute_status(target, rebuild=True)
+    created.append(str(manifest_path(target).relative_to(target)))
+
+    if args.json:
+        _emit({"root": str(target), "status": "initialized", "created": created})
+    else:
+        print(f"initialized scriptorium root at {target}")
+        for c in created:
+            print(f"  + {c}")
+        print(
+            "  next: add a source (`scrip ingest <url|file>`), compile a page "
+            "(`scrip new` + `scrip anchor` + `scrip stamp`), then `scrip verify`"
+        )
+    return 0
+
+
 def cmd_status(args: argparse.Namespace) -> int:
     from . import graph
 
@@ -555,6 +614,21 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--version", action="version", version=f"scrip {__version__}")
     sub = p.add_subparsers(dest="command", required=True, metavar="<command>")
 
+    pinit = sub.add_parser(
+        "init",
+        help="create the root skeleton (vault/{raw,facts,wiki}/ + .kb/ cache) and its manifest",
+    )
+    pinit.add_argument(
+        "path",
+        nargs="?",
+        metavar="DIR",
+        help="directory to initialize (default: current directory; created if absent)",
+    )
+    pinit.add_argument(
+        "--json", action="store_true", help="machine-readable JSON output"
+    )
+    pinit.set_defaults(func=cmd_init)
+
     ps = sub.add_parser(
         "status",
         parents=[common],

{scriptoria-0.9.0 → scriptoria-0.10.0}/src/scrip/facts.py

@@ -412,10 +412,7 @@ def _load_meta(root: Path) -> dict:
 
 def _write_meta(root: Path, data: dict, new_sources: list[str]) -> None:
     derived = list(data.get("derived-from") or [])
-    for sid in new_sources:
-        if sid not in derived:
-            derived.append(sid)
-    data["derived-from"] = derived
+    data["derived-from"] = list(dict.fromkeys(derived + new_sources))
     # Drop the stamp on EVERY append: with an unchanged derived-from the
     # recomputed input-hash would still match the stored one, and status would
     # report OK over facts nobody has blessed. Removing input-hash forces STALE
@@ -596,12 +593,12 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                 if not ends_with_newline:
                     f.write("\n")
                 f.write(payload)
-            new_sources: list[str] = []
+            new_sources_dict: dict[str, None] = {}
             if table in ("claims", "edges"):
                 for rec in appended:
                     sid = rec.get("source_id")  # cited edges carry one; bare edges don't
-                    if sid and sid not in new_sources:
-                        new_sources.append(sid)
-            _write_meta(root, meta, new_sources)
+                    if sid:
+                        new_sources_dict[sid] = None
+            _write_meta(root, meta, list(new_sources_dict.keys()))
 
     return {"table": table, "appended": appended, "skipped": skipped, "failures": []}

scriptoria-0.10.0/tests/test_init_cmd.py

@@ -0,0 +1,102 @@
+"""`scrip init` — create the root skeleton (vault/ layers + .kb/ cache) so a new
+instance starts detectable and green. Idempotent in an existing root; refuses to
+nest a new instance inside an existing one."""
+
+import json
+
+from scrip import cli, manifest_path
+
+
+def test_init_creates_skeleton_and_manifest(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    for rel in ("vault/raw", "vault/facts", "vault/wiki", ".kb"):
+        assert (root / rel).is_dir()
+    # same effect as `scrip status --rebuild-manifest`: the cache exists
+    assert manifest_path(root).exists()
+    out = capsys.readouterr().out
+    assert f"initialized scriptorium root at {root}" in out
+    assert "scrip ingest" in out  # next-steps hint: ingest -> compile -> verify
+    assert "scrip verify" in out
+
+
+def test_init_defaults_to_cwd(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert cli.main(["init"]) == 0
+    assert (tmp_path / "vault" / "raw").is_dir()
+    assert (tmp_path / ".kb").is_dir()
+
+
+def test_init_then_commands_resolve_root_without_flags(tmp_path, monkeypatch):
+    """The dogfooding gap this command closes: after init, `scrip status` and
+    `scrip verify` run green from inside the new root with no --root."""
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    monkeypatch.chdir(root)
+    assert cli.main(["status"]) == 0
+    assert cli.main(["verify"]) == 0
+
+
+def test_init_existing_root_is_noop(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    manifest_before = manifest_path(root).read_text(encoding="utf-8")
+    capsys.readouterr()
+    assert cli.main(["init", str(root)]) == 0
+    out = capsys.readouterr().out
+    assert f"already a scriptorium root: {root}" in out
+    # a true no-op: the manifest was not rewritten
+    assert manifest_path(root).read_text(encoding="utf-8") == manifest_before
+
+
+def test_init_detects_spec_marker_root_as_existing(kb, capsys):
+    """A root marked by SPEC.md (no .kb/ needed) counts as already initialized."""
+    assert cli.main(["init", str(kb.root)]) == 0
+    assert "already a scriptorium root" in capsys.readouterr().out
+
+
+def test_init_inside_existing_root_refused_exit_2(tmp_path):
+    root = tmp_path / "kb"
+    assert cli.main(["init", str(root)]) == 0
+    nested = root / "vault" / "raw" / "sub"
+    assert cli.main(["init", str(nested)]) == 2
+    # nothing was created for the refused nested instance
+    assert not nested.exists()
+
+
+def test_init_target_is_a_file_exit_2(tmp_path):
+    f = tmp_path / "notes.md"
+    f.write_text("hi\n", encoding="utf-8")
+    assert cli.main(["init", str(f)]) == 2
+
+
+def test_init_fills_in_missing_layers(tmp_path):
+    """A partial layout (vault/ alone is not a detectable root) is completed
+    rather than refused."""
+    root = tmp_path / "kb"
+    (root / "vault" / "raw").mkdir(parents=True)
+    assert cli.main(["init", str(root)]) == 0
+    for rel in ("vault/facts", "vault/wiki", ".kb"):
+        assert (root / rel).is_dir()
+
+
+def test_init_layer_path_is_a_file_refused_exit_2(tmp_path):
+    """A file squatting a layer path is refused cleanly (exit 2), not an
+    uncaught FileExistsError mapped to the internal-error exit code."""
+    root = tmp_path / "kb"
+    (root / "vault").mkdir(parents=True)
+    (root / "vault" / "facts").write_text("oops\n", encoding="utf-8")
+    assert cli.main(["init", str(root)]) == 2
+
+
+def test_init_json_shape(tmp_path, capsys):
+    root = tmp_path / "kb"
+    assert cli.main(["init", "--json", str(root)]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert set(data) == {"root", "status", "created"}
+    assert data["status"] == "initialized"
+    assert ".kb/manifest.json" in data["created"]
+    assert cli.main(["init", "--json", str(root)]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["status"] == "exists"
+    assert data["created"] == []

{scriptoria-0.9.0 → scriptoria-0.10.0}/uv.lock

@@ -1141,7 +1141,7 @@ wheels = [
 
 [[package]]
 name = "scriptoria"
-version = "0.9.0"
+version = "0.10.0"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },