openlogbook 0.1.0__py3-none-any.whl

logbook/__init__.py

@@ -0,0 +1,4 @@
+"""Logbook — a diary that writes itself. Layer 1: the folder, the chain, the CLI."""
+
+__version__ = "0.1.0"
+FORMAT = "logbook/0.1"

logbook/chain.py

@@ -0,0 +1,52 @@
+"""The hash chain. Pure functions, no I/O. This file *is* SPEC.md §3."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable
+from typing import Any
+
+Line = dict[str, Any]
+
+GENESIS = "0" * 64
+CONTENT_FIELDS = ("at", "end", "tz", "source", "kind", "tier", "payload")
+
+
+def canonical_json(obj: object) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+
+
+def content_hash(line: Line) -> str:
+    content = {k: line.get(k) for k in CONTENT_FIELDS}
+    return hashlib.sha256(canonical_json(content).encode("utf-8")).hexdigest()
+
+
+def line_hash(prev: str, seq: int, chash: str, recorded_at: str) -> str:
+    return hashlib.sha256(f"{prev}|{seq}|{chash}|{recorded_at}".encode()).hexdigest()
+
+
+def compute_hash(line: Line) -> str:
+    return line_hash(line["prev"], line["seq"], content_hash(line), line["recorded_at"])
+
+
+def verify_lines(lines: Iterable[Line]) -> tuple[int, str, list[str]]:
+    """Walk lines in order. Returns (count, head, errors)."""
+    errors, prev, seq, head = [], GENESIS, 0, GENESIS
+    for n, line in enumerate(lines, 1):
+        if line.get("seq") != seq + 1:
+            errors.append(f"line {n}: seq {line.get('seq')} expected {seq + 1}")
+        if line.get("prev") != prev:
+            errors.append(f"line {n}: prev does not match previous hash")
+        if "payload" not in line or "schema" not in (line.get("payload") or {}):
+            errors.append(f"line {n}: payload.schema missing")
+        if line.get("tier") not in (1, 2, 3):
+            errors.append(f"line {n}: tier must be 1, 2 or 3")
+        expected = compute_hash(line) if all(k in line for k in ("prev", "seq", "recorded_at")) else None
+        if expected != line.get("hash"):
+            errors.append(f"line {n}: hash does not recompute")
+        prev, seq, head = line.get("hash", prev), line.get("seq", seq), line.get("hash", head)
+        if len(errors) > 20:
+            errors.append("…stopping after 20 errors")
+            break
+    return seq, head, errors

logbook/cli.py

@@ -0,0 +1,130 @@
+"""logbook — init · add · show · verify · export. Three verbs and two you run once a year."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date, datetime
+from pathlib import Path
+
+from . import __version__
+from .store import CodeCheckoutError, Logbook, now_utc
+
+
+def _tz_default() -> str:
+    key = getattr(datetime.now().astimezone().tzinfo, "key", None)
+    return key if isinstance(key, str) else "UTC"
+
+
+def cmd_init(a: argparse.Namespace) -> None:
+    root = Path(a.path or Path.home() / "Logbook").expanduser()
+    try:
+        lb = Logbook.init(root, a.timezone or _tz_default())
+    except CodeCheckoutError as e:
+        print(f"refusing to init: {e}", file=sys.stderr)
+        sys.exit(2)
+    print(f'created {lb.root}\nDrop any export into {lb.root / "inbox"}, or: logbook add "what happened"')
+
+
+def cmd_add(a: argparse.Namespace) -> None:
+    lb = Logbook.find()
+    what = " ".join(a.what).strip()
+    p = Path(what).expanduser()
+    if p.exists() and p.suffix == ".jsonl":  # observations produced by an adapter
+        drafts = [json.loads(line) for line in p.read_text(encoding="utf-8").splitlines() if line.strip()]
+        n = lb.append_many(drafts)
+        print(f"added {n} lines from {p.name}")
+    elif p.exists():
+        print(
+            f"{p.name}: no adapter for this file yet (roadmap phase 1). "
+            "Put it in inbox/ and it will be read when one exists."
+        )
+        sys.exit(2)
+    else:  # a sentence, in your own words
+        at = a.at or now_utc()
+        line = lb.append(
+            at=at, source="manual", kind="note", tier=2, payload={"schema": "note/v1", "text": what}
+        )
+        print(f"#{line['seq']} {line['at']}  {what}")
+
+
+def cmd_show(a: argparse.Namespace) -> None:
+    lb = Logbook.find()
+    day = date.today().isoformat() if a.day in (None, "today") else a.day
+    rows = [line for line in lb.lines() if line["at"].startswith(day)]
+    if not rows:
+        print(f"{day}: nothing logged")
+        return
+    print(day)
+    for line in rows:
+        p = line["payload"]
+        text = (
+            p.get("text")
+            or p.get("title")
+            or p.get("name")
+            or ", ".join(f"{k}={v}" for k, v in p.items() if k != "schema")
+        )
+        print(f"  {line['at'][11:16]}  {line['kind']:<10} {line['source']:<14} {text}")
+    note = lb.root / "notes" / day[:4] / f"{day}.md"
+    if note.exists():
+        print("  — note —\n" + "\n".join("  " + s for s in note.read_text(encoding="utf-8").splitlines()))
+
+
+def cmd_verify(a: argparse.Namespace) -> None:
+    lb = Logbook(Path(a.root).expanduser()) if a.root else Logbook.find()
+    seq, head, errors = lb.verify()
+    if a.expect:
+        exp = json.loads(Path(a.expect).read_text(encoding="utf-8"))
+        if (exp["seq"], exp["head"]) != (seq, head):
+            errors.append(
+                f"expected seq={exp['seq']} head={exp['head'][:12]}…, got seq={seq} head={head[:12]}…"
+            )
+    if errors:
+        print(f"INVALID — {len(errors)} problem(s):")
+        for e in errors:
+            print("  " + e)
+        sys.exit(1)
+    print(f"valid — {seq} lines, head {head}")
+
+
+def cmd_export(a: argparse.Namespace) -> None:
+    lb = Logbook.find()
+    out = Path(a.path).expanduser()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    n = 0
+    with out.open("w", encoding="utf-8") as fh:
+        for line in lb.lines():
+            fh.write(json.dumps(line, ensure_ascii=False, sort_keys=True) + "\n")
+            n += 1
+    print(f"exported {n} lines to {out} — verify with: logbook verify")
+
+
+def main(argv: list[str] | None = None) -> None:
+    ap = argparse.ArgumentParser(prog="logbook", description="A diary that writes itself.")
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("init", help="create a logbook (default ~/Logbook)")
+    s.add_argument("path", nargs="?")
+    s.add_argument("--timezone")
+    s.set_defaults(fn=cmd_init)
+    s = sub.add_parser("add", help="a sentence in your words, or an adapter's .jsonl")
+    s.add_argument("what", nargs="+")
+    s.add_argument("--at", help="RFC3339 UTC, default now")
+    s.set_defaults(fn=cmd_add)
+    s = sub.add_parser("show", help="one day (default today)")
+    s.add_argument("day", nargs="?")
+    s.set_defaults(fn=cmd_show)
+    s = sub.add_parser("verify", help="check the chain")
+    s.add_argument("--root", help="logbook folder (default: find)")
+    s.add_argument("--expect", help="expected.json with seq and head (conformance)")
+    s.set_defaults(fn=cmd_verify)
+    s = sub.add_parser("export", help="the whole log as one .jsonl")
+    s.add_argument("path")
+    s.set_defaults(fn=cmd_export)
+    a = ap.parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

logbook/store.py

@@ -0,0 +1,166 @@
+"""The folder. The only code that writes to logbook/*.jsonl."""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import time
+import uuid
+from collections.abc import Iterable, Iterator
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from . import FORMAT
+from .chain import GENESIS, Line, compute_hash, verify_lines
+
+
+def now_utc() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def uuid7() -> str:
+    """RFC 9562 UUIDv7: 48-bit ms timestamp, then random. Time-ordered, so ids sort like the log."""
+    ms = time.time_ns() // 1_000_000
+    rand_a = secrets.randbits(12)
+    rand_b = secrets.randbits(62)
+    value = (ms << 80) | (0x7 << 76) | (rand_a << 64) | (0b10 << 62) | rand_b
+    return str(uuid.UUID(int=value))
+
+
+CHECKOUT_MARKERS = ("pyproject.toml", ".git", "logbook/__init__.py")
+
+
+class CodeCheckoutError(Exception):
+    """The folder looks like a clone of this repository, not a personal record."""
+
+
+def code_checkout_marker(root: Path) -> str | None:
+    """The first thing in `root` that says "source code, not a diary", or None.
+
+    On a case-insensitive disk ~/Logbook and a clone at ~/logbook are the same folder,
+    so a logbook must never be created in, or found in, a folder that has one of these."""
+    return next((m for m in CHECKOUT_MARKERS if (Path(root) / m).exists()), None)
+
+
+class Logbook:
+    def __init__(self, root: Path):
+        self.root = Path(root)
+        self.meta_path = self.root / "logbook.json"
+        self.log_dir = self.root / "logbook"
+
+    # -- lifecycle -----------------------------------------------------------
+    @classmethod
+    def init(cls, root: Path, timezone_name: str) -> Logbook:
+        root = Path(root)
+        marker = code_checkout_marker(root)
+        if marker is not None:
+            raise CodeCheckoutError(
+                f"{root} looks like a code checkout (it has {marker}); "
+                "choose another folder or set LOGBOOK_HOME"
+            )
+        if (root / "logbook.json").exists():
+            raise FileExistsError(f"{root} is already a logbook")
+        for d in ("logbook", "notes", "inbox", "inbox/done"):
+            (root / d).mkdir(parents=True, exist_ok=True)
+        meta = {
+            "format": FORMAT,
+            "owner_id": uuid7(),
+            "created_at": now_utc(),
+            "timezone": timezone_name,
+            "seq": 0,
+            "head": GENESIS,
+        }
+        (root / "logbook.json").write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8")
+        return cls(root)
+
+    @classmethod
+    def find(cls, start: Path | None = None) -> Logbook:
+        env = os.environ.get("LOGBOOK_HOME")
+        candidates = [Path(env)] if env else []
+        p = Path(start or Path.cwd()).resolve()
+        candidates += [p, *p.parents, Path.home() / "Logbook"]
+        for c in candidates:
+            if (c / "logbook.json").exists() and code_checkout_marker(c) is None:
+                return cls(c)
+        raise FileNotFoundError("no logbook found; run `logbook init`")
+
+    @property
+    def meta(self) -> dict[str, Any]:
+        data: dict[str, Any] = json.loads(self.meta_path.read_text(encoding="utf-8"))
+        return data
+
+    def _save_meta(self, meta: dict[str, Any]) -> None:
+        self.meta_path.write_text(json.dumps(meta, indent=2) + "\n", encoding="utf-8")
+
+    # -- reading -------------------------------------------------------------
+    def files(self) -> list[Path]:
+        return sorted(self.log_dir.glob("*/*.jsonl"))
+
+    def lines(self) -> Iterator[Line]:
+        """All lines in chain order (by seq). Files partition by month of `at`; backfilled
+        history lands in old files, so file order is not chain order."""
+        rows: list[Line] = []
+        for f in self.files():
+            with f.open(encoding="utf-8") as fh:
+                rows.extend(json.loads(raw) for raw in fh if raw.strip())
+        rows.sort(key=lambda r: r.get("seq", 0))
+        return iter(rows)
+
+    def verify(self) -> tuple[int, str, list[str]]:
+        seq, head, errors = verify_lines(self.lines())
+        meta = self.meta
+        if meta["seq"] != seq or meta["head"] != head:
+            errors.append(
+                f"logbook.json says seq={meta['seq']} head={meta['head'][:12]}…, "
+                f"files say seq={seq} head={head[:12]}…"
+            )
+        return seq, head, errors
+
+    # -- writing -------------------------------------------------------------
+    def append(
+        self,
+        at: str,
+        source: str,
+        kind: str,
+        tier: int,
+        payload: dict[str, Any],
+        end: str | None = None,
+        tz: str | None = None,
+        recorded_at: str | None = None,
+    ) -> Line:
+        if "schema" not in payload:
+            raise ValueError("payload.schema is required")
+        if tier not in (1, 2, 3):
+            raise ValueError("tier must be 1, 2 or 3")
+        meta = self.meta
+        line: Line = {
+            "id": uuid7(),
+            "seq": meta["seq"] + 1,
+            "at": at,
+            "end": end,
+            "tz": tz or meta["timezone"],
+            "source": source,
+            "kind": kind,
+            "tier": tier,
+            "payload": payload,
+            "recorded_at": recorded_at or now_utc(),
+            "prev": meta["head"],
+        }
+        line["hash"] = compute_hash(line)
+        year, month = at[:4], at[5:7]
+        path = self.log_dir / year / f"{month}.jsonl"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(line, ensure_ascii=False, sort_keys=True) + "\n")
+        meta["seq"], meta["head"] = line["seq"], line["hash"]
+        self._save_meta(meta)
+        return line
+
+    def append_many(self, drafts: Iterable[dict[str, Any]]) -> int:
+        n = 0
+        for d in drafts:
+            self.append(**d)
+            n += 1
+        return n

openlogbook-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: openlogbook
+Version: 0.1.0
+Summary: A diary that writes itself. Your life, in a folder.
+Project-URL: Homepage, https://github.com/bighydro/logbook
+Project-URL: Specification, https://github.com/bighydro/logbook/blob/main/SPEC.md
+Project-URL: Changelog, https://github.com/bighydro/logbook/blob/main/CHANGELOG.md
+Author: bighydro
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: append-only,diary,hash-chain,lifelog,local-first,logbook,personal-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Logbook
+
+**A diary that writes itself.**
+
+Your life already gets recorded — by your phone, your photos, your calendar, your messages. Logbook writes it all down once, in one folder that only you hold, and reads it back to you as days. You hand a page to someone you care about; they hand one back.
+
+It is the opposite of social media: no feed, no followers, no likes, no counts. Reveal, never reward. Nothing leaves without a name.
+
+![How Logbook works](docs/how-it-works.svg)
+
+## Sixty seconds
+
+```bash
+pipx install openlogbook        # or: pip install .
+logbook init                    # creates ~/Logbook and your key
+logbook add "had lunch with a friend by the lake"
+logbook add ~/Downloads/takeout.zip     # any export, no flags
+logbook show today
+logbook verify                  # the chain is intact
+```
+
+That is the whole product. Everything else is a layer somebody plugs in.
+
+## What is in the folder
+
+```
+~/Logbook/
+  logbook/          the record. one file per month. append only. never edit.
+    2026/09.jsonl
+  inbox/            drop anything here. it gets read, then moved to done/.
+  notes/            what you write. plain Markdown, one file per day.
+  logbook.json      who this is, your timezone, the chain head.
+```
+
+Nothing here needs the app to make sense. Open the files in any editor twenty years from now.
+
+If you also keep a clone of this repository, set `LOGBOOK_HOME` to your record's folder and pass that path to `logbook init`. On a case-insensitive disk (macOS by default) `~/Logbook` and a clone named `~/logbook` are the same folder; `init` refuses a folder that contains `pyproject.toml`, `.git` or `logbook/__init__.py`, and the CLI never picks such a folder as your record.
+
+## Three rules
+
+1. **Append only.** Every line is hash-chained to the one before. A broken chain is an error, never repaired silently.
+2. **Files first.** No database is required to read, verify or export a logbook. Databases are caches.
+3. **Nothing leaves.** Personal lines are encrypted with your key. There is no server. Sharing is a page handed to a named person.
+
+## Read next
+
+- [VISION.md](VISION.md) — why, and the rules the product refuses to break
+- [LORE.md](LORE.md) — where the logbook comes from: ships, pilots, diaries, and the log in computing
+- [SPEC.md](SPEC.md) — the format, one page; this is the part meant to become a standard
+- [ARCHITECTURE.md](ARCHITECTURE.md) — the five layers and what each may depend on
+- [ROADMAP.md](ROADMAP.md) — what ships when
+- [CONTRIBUTING.md](CONTRIBUTING.md) — the easiest thing to build is an adapter for the export you have
+
+## Status
+
+v0.1 — the format, the CLI (init, add, show, verify, export) and the conformance fixture. Engines (days, trips, people) and the circle (sharing) are the next layers; see the roadmap.
+
+Apache-2.0 for code. The specification is CC0.

openlogbook-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+logbook/__init__.py,sha256=N87aAwK21etcjCRblv3_U-uDSku-0QeIwEEkkRXi3LE,133
+logbook/chain.py,sha256=HG9-TZ5dqKpYiZU9K86SnnVEn9SNE-AYJZCvpSwCXXo,2074
+logbook/cli.py,sha256=ftFoS-BQ6sOAcV8GhJrJIplsSdgEeu1s9n4BKOeQOBQ,4877
+logbook/store.py,sha256=mW81JE5flwg9UwSznnmfgXTMcXkUkVYHKNjebjDMGyE,5983
+openlogbook-0.1.0.dist-info/METADATA,sha256=_uvLWCVjBuqz_JtxjpMf6Uuk64OoaL6LHZogsNePP3w,3653
+openlogbook-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+openlogbook-0.1.0.dist-info/entry_points.txt,sha256=ovE9nsrl54dyY_PqB9x0faDRQHy3cG9j9B2vVa4DrMw,45
+openlogbook-0.1.0.dist-info/licenses/LICENSE,sha256=OKQ3H79ngWXufbd6r2VeG-wTYtMvRpRKbgJ61wiG-iY,582
+openlogbook-0.1.0.dist-info/RECORD,,

openlogbook-0.1.0.dist-info/WHEEL

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

openlogbook-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+logbook = logbook.cli:main

openlogbook-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Apache License 2.0 — https://www.apache.org/licenses/LICENSE-2.0
+
+Copyright 2026 bighydro
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at the URL above. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+SPEC.md and everything under schema/ and rfcs/ are dedicated to the public domain under CC0 1.0.