note-state 0.1.0__py3-none-any.whl

note_state/__init__.py

@@ -0,0 +1,3 @@
+"""note-state — a portable state-tracking layer for markdown note vaults."""
+
+__version__ = "0.1.0"

note_state/cli.py

@@ -0,0 +1,251 @@
+"""
+note_state.cli — a portable state-tracking layer for markdown-based note apps.
+
+Works with any note application that stores notes as markdown files with
+YAML frontmatter on local disk: Obsidian, Dendron, Foam, plain markdown
+vaults, and similar. (See the project README for notes on Logseq/Notion,
+which store notes a little differently.)
+
+It does one job: read/write a `state` field (plus a `state_history` log)
+in each note's frontmatter, and enforce the transition rules defined in
+states.yaml so a note can't silently skip stages of the pipeline.
+
+Commands:
+    note-state init   <file_or_dir>
+    note-state set    <file> <state> [--force] [--note "reason"]
+    note-state list   [dir] [--state STATE]
+    note-state report [dir]
+    note-state graph
+"""
+
+import argparse
+import datetime
+import importlib.resources
+import os
+import pathlib
+import sys
+
+import yaml
+
+from . import __version__
+
+DEFAULT_CONFIG_NAMES = ["states.yaml", ".note-states.yaml"]
+FRONTMATTER_DELIM = "---"
+
+
+# ---------------------------------------------------------------- config --
+
+def find_local_config():
+    """Look for states.yaml in the current directory or any parent."""
+    d = pathlib.Path.cwd()
+    while True:
+        for name in DEFAULT_CONFIG_NAMES:
+            p = d / name
+            if p.exists():
+                return str(p)
+        if d.parent == d:
+            return None
+        d = d.parent
+
+
+def load_config(path=None):
+    if path:
+        with open(path, "r", encoding="utf-8") as f:
+            cfg = yaml.safe_load(f)
+    else:
+        local = find_local_config()
+        if local:
+            with open(local, "r", encoding="utf-8") as f:
+                cfg = yaml.safe_load(f)
+        else:
+            # Fall back to the bundled default pipeline.
+            data = importlib.resources.files("note_state").joinpath("default_states.yaml")
+            cfg = yaml.safe_load(data.read_text(encoding="utf-8"))
+
+    if "states" not in cfg or "transitions" not in cfg or "initial_state" not in cfg:
+        sys.exit("Config is missing required keys: states, transitions, initial_state")
+    return cfg
+
+
+# ------------------------------------------------------------- frontmatter --
+
+def read_note(path):
+    """Return (meta_dict, body_text) for a markdown file, tolerating no frontmatter."""
+    text = pathlib.Path(path).read_text(encoding="utf-8")
+    if text.startswith(FRONTMATTER_DELIM):
+        parts = text.split(FRONTMATTER_DELIM, 2)
+        if len(parts) == 3:
+            meta = yaml.safe_load(parts[1]) or {}
+            body = parts[2].lstrip("\n")
+            return meta, body
+    return {}, text
+
+
+def write_note(path, meta, body):
+    yaml_str = yaml.safe_dump(
+        meta, sort_keys=False, allow_unicode=True, default_flow_style=False
+    )
+    content = f"{FRONTMATTER_DELIM}\n{yaml_str}{FRONTMATTER_DELIM}\n\n{body}"
+    pathlib.Path(path).write_text(content, encoding="utf-8")
+
+
+def iter_md_files(root):
+    if os.path.isfile(root):
+        yield root
+        return
+    for dirpath, _, filenames in os.walk(root):
+        for fn in filenames:
+            if fn.endswith(".md"):
+                yield os.path.join(dirpath, fn)
+
+
+def today_iso():
+    return datetime.date.today().isoformat()
+
+
+# -------------------------------------------------------------- commands --
+
+def cmd_init(args, cfg):
+    initial = cfg["initial_state"]
+    touched = 0
+    for path in iter_md_files(args.target):
+        meta, body = read_note(path)
+        if "state" in meta:
+            print(f"skip   {path}  (already: {meta['state']})")
+            continue
+        meta["state"] = initial
+        meta["state_history"] = [{"state": initial, "date": today_iso()}]
+        write_note(path, meta, body)
+        print(f"init   {path}  -> {initial}")
+        touched += 1
+    print(f"\n{touched} note(s) initialized.")
+
+
+def cmd_set(args, cfg):
+    path = args.file
+    meta, body = read_note(path)
+    current = meta.get("state", cfg["initial_state"])
+    target = args.state
+
+    if target not in cfg["states"]:
+        valid = ", ".join(cfg["states"].keys())
+        sys.exit(f"Unknown state '{target}'. Valid states: {valid}")
+
+    allowed = cfg["transitions"].get(current, [])
+    if target not in allowed and not args.force:
+        allowed_str = ", ".join(allowed) if allowed else "(none — terminal state)"
+        sys.exit(
+            f"Can't move '{path}' from '{current}' to '{target}'.\n"
+            f"Allowed next states from '{current}': {allowed_str}\n"
+            f"Use --force to override anyway."
+        )
+
+    meta["state"] = target
+    history = meta.setdefault("state_history", [])
+    entry = {"state": target, "date": today_iso()}
+    if args.note:
+        entry["note"] = args.note
+    history.append(entry)
+    write_note(path, meta, body)
+    print(f"{path}: {current} -> {target}")
+
+
+def cmd_list(args, cfg):
+    rows = []
+    for path in iter_md_files(args.target):
+        meta, _ = read_note(path)
+        state = meta.get("state", "(none)")
+        if args.state and state != args.state:
+            continue
+        history = meta.get("state_history", [])
+        last_date = history[-1]["date"] if history else "?"
+        rows.append((state, last_date, path))
+
+    if not rows:
+        print("No notes found.")
+        return
+
+    rows.sort(key=lambda r: (r[0], r[2]))
+    width = max(len(r[0]) for r in rows)
+    for state, last_date, path in rows:
+        print(f"{state.ljust(width)}  {last_date}  {path}")
+
+
+def cmd_report(args, cfg):
+    counts = {}
+    aged = []
+    today = datetime.date.today()
+
+    for path in iter_md_files(args.target):
+        meta, _ = read_note(path)
+        state = meta.get("state", "(none)")
+        counts[state] = counts.get(state, 0) + 1
+        history = meta.get("state_history", [])
+        if history:
+            try:
+                last = datetime.date.fromisoformat(history[-1]["date"])
+                aged.append(((today - last).days, state, path))
+            except ValueError:
+                pass
+
+    print("Notes per state:")
+    for state, n in sorted(counts.items(), key=lambda kv: -kv[1]):
+        print(f"  {state.ljust(16)} {n}")
+
+    if aged:
+        aged.sort(reverse=True)
+        print("\nOldest since last transition (possible bottlenecks):")
+        for age, state, path in aged[:10]:
+            print(f"  {age:>4}d  {state.ljust(16)} {path}")
+
+
+def cmd_graph(args, cfg):
+    print("stateDiagram-v2")
+    for src, dests in cfg["transitions"].items():
+        if not dests:
+            continue
+        for dest in dests:
+            print(f"    {src} --> {dest}")
+
+
+# ------------------------------------------------------------------ main --
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="note-state",
+        description="Track note states through a knowledge-processing pipeline.",
+    )
+    parser.add_argument("--version", action="version", version=f"note-state {__version__}")
+    parser.add_argument("--config", help="path to states.yaml", default=None)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="stamp an initial state onto notes that don't have one")
+    p_init.add_argument("target", help="file or directory")
+    p_init.set_defaults(func=cmd_init)
+
+    p_set = sub.add_parser("set", help="transition a note to a new state")
+    p_set.add_argument("file")
+    p_set.add_argument("state")
+    p_set.add_argument("--force", action="store_true", help="allow a transition not listed in states.yaml")
+    p_set.add_argument("--note", default=None, help="optional short reason, stored in state_history")
+    p_set.set_defaults(func=cmd_set)
+
+    p_list = sub.add_parser("list", help="list notes and their current state")
+    p_list.add_argument("target", nargs="?", default=".")
+    p_list.add_argument("--state", default=None, help="filter to a single state")
+    p_list.set_defaults(func=cmd_list)
+
+    p_report = sub.add_parser("report", help="counts per state + oldest unmoved notes")
+    p_report.add_argument("target", nargs="?", default=".")
+    p_report.set_defaults(func=cmd_report)
+
+    p_graph = sub.add_parser("graph", help="print the state machine as a Mermaid diagram")
+    p_graph.set_defaults(func=cmd_graph)
+
+    args = parser.parse_args()
+    cfg = load_config(args.config)
+    args.func(args, cfg)
+
+
+if __name__ == "__main__":
+    main()

note_state/default_states.yaml

@@ -0,0 +1,62 @@
+# Bundled default state machine — used automatically when no states.yaml
+# is found in the current directory or any parent. Copy this file into
+# your vault as `states.yaml` (or `.note-states.yaml`) and edit freely;
+# a local copy always takes priority over this bundled default.
+
+initial_state: drafting
+
+states:
+  drafting:
+    label: "Drafting"
+    description: >
+      Raw capture. Get the idea down with as little friction as possible —
+      fragments, bullet points, half-formed sentences are all fine here.
+  review:
+    label: "Review"
+    description: >
+      Check the idea for accuracy, internal consistency, and missing gaps.
+      Decide whether it deserves to keep moving or needs rework.
+  formatting:
+    label: "Formatting"
+    description: >
+      Give the note a shape: headings, atomic scope (one idea per note),
+      consistent title, clean prose, tags.
+  referencing:
+    label: "Referencing"
+    description: >
+      Attach provenance: citations, source links, backlinks to the notes
+      this one draws on or was extracted from.
+  integrating:
+    label: "Integrating"
+    description: >
+      Weave the note into the graph: link it from relevant Maps of
+      Content / index notes, cross-link related permanent notes, make it
+      discoverable through search and tags rather than sitting orphaned.
+  published:
+    label: "Published"
+    description: >
+      Stable and reusable. Safe to cite, export, or share outside the
+      vault. The "done" state of the main pipeline.
+  needs_revision:
+    label: "Needs Revision"
+    description: >
+      Flagged during any stage as having a problem (factual error,
+      unclear scope, broken links). Always exits back to the stage that
+      flagged it, once fixed.
+  archived:
+    label: "Archived"
+    description: >
+      Retired or superseded by another note. No longer part of the
+      active pipeline, but kept for the record.
+
+# Map of state -> list of states it's allowed to move to.
+# cmd `set` enforces this unless you pass --force.
+transitions:
+  drafting:        [review, archived]
+  review:          [formatting, drafting, needs_revision, archived]
+  formatting:      [referencing, review, needs_revision, archived]
+  referencing:     [integrating, formatting, needs_revision, archived]
+  integrating:     [published, referencing, needs_revision, archived]
+  published:       [integrating, archived]
+  needs_revision:  [drafting, review, formatting, referencing, integrating]
+  archived:        []

note_state-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: note-state
+Version: 0.1.0
+Summary: A portable state-tracking layer for markdown note vaults (Obsidian, Dendron, Foam, and plain markdown folders).
+Author-email: superxgen <superxgen@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/resystem0/note-state
+Project-URL: Issues, https://github.com/resystem0/note-state/issues
+Keywords: notes,markdown,obsidian,pkm,zettelkasten,frontmatter,state-machine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# note-state
+
+A portable "patch" for turning a pile of notes into a *pipeline*: every note
+carries an explicit `state` telling you how far it's traveled from raw
+capture to integrated, trustworthy knowledge — the same way a ticket in an
+issue tracker carries a status, or a part on an assembly line carries a
+stage.
+
+Works with any note application that stores notes as markdown files with
+**YAML frontmatter** on local disk — Obsidian, Dendron, Foam, Logseq, plain
+markdown vaults, even a folder of `.md` files with no app at all.
+
+## Install
+
+```bash
+pip install note-state
+```
+
+## The pipeline
+
+```
+drafting → review → formatting → referencing → integrating → published
+                ↘         ↘            ↘             ↘
+                          needs_revision  (loops back to whichever
+                                           stage flagged the problem)
+
+              any state ──────────────────────────────→ archived
+```
+
+| State | What happens here | Exit condition |
+|---|---|---|
+| **Drafting** | Raw capture. Get the idea down with as little friction as possible. | The idea has enough substance to be judged. |
+| **Review** | Read it critically: accurate, internally consistent, complete? | Content is verified, or it's sent back to Drafting. |
+| **Formatting** | Give it shape: headings, atomic scope, a real title, clean prose, tags. | It reads well and is scoped correctly. |
+| **Referencing** | Attach provenance: citations, source links, backlinks. | Every non-obvious claim is traceable to a source. |
+| **Integrating** | Weave it into the graph: link from a Map of Content, cross-link related notes. | It's reachable from at least one other place in the vault. |
+| **Published** | Stable and reusable — safe to cite, export, or share. | Terminal, but can be pulled back into Integrating. |
+| **Needs Revision** *(utility state)* | Something's wrong. Flagged from any stage. | Always exits back to the stage that flagged it. |
+| **Archived** *(utility state)* | Retired or superseded. | Terminal. |
+
+This isn't sacred — it's just the bundled default. Drop your own
+`states.yaml` next to your notes (or in any parent directory) to define a
+different pipeline; `note-state` doesn't hardcode the states, it just
+enforces whatever pipeline you describe.
+
+## The metadata schema
+
+Every tracked note gets two frontmatter fields: the current state, and a
+timestamped log of how it got there.
+
+```yaml
+---
+title: "Maps of Content connect clusters of related notes"
+state: referencing
+state_history:
+  - state: drafting
+    date: 2026-07-01
+  - state: review
+    date: 2026-07-05
+  - state: formatting
+    date: 2026-07-08
+  - state: referencing
+    date: 2026-07-12
+    note: "added three sources"
+tags: [pkm, moc]
+---
+
+Note body goes here as normal — nothing about the state system touches
+the content itself.
+```
+
+`state_history` is what makes the system useful beyond a label: it's an
+audit trail you can query later ("which notes have been stuck in Review for
+three weeks?", "how long does formatting usually take?").
+
+## Usage
+
+```bash
+# Stamp every note in a folder with the initial state (only touches
+# notes that don't already have one — safe to run repeatedly)
+note-state init ./my-vault
+
+# Move a note forward
+note-state set my-vault/atomic-notes.md review
+
+# Try to skip a stage — this is rejected unless you pass --force
+note-state set my-vault/atomic-notes.md published
+
+# See what's where
+note-state list ./my-vault
+note-state list ./my-vault --state review
+
+# Find bottlenecks — counts per state + oldest untouched notes
+note-state report ./my-vault
+
+# Print the pipeline as a Mermaid diagram (paste into anything that renders it)
+note-state graph
+```
+
+## Customizing the pipeline
+
+Two files define the state machine:
+
+- **`states.yaml`** — states + allowed transitions. `note-state` looks for
+  this file (or `.note-states.yaml`) in the current directory, then any
+  parent directory, and falls back to the bundled default pipeline above if
+  none is found. Copy the bundled default as a starting point and edit
+  freely — rename stages, add a `translating` or `peer-review` state,
+  rewire transitions.
+- Pass `--config path/to/states.yaml` to point at a specific file instead
+  of relying on directory discovery.
+
+## Wiring it into a specific app
+
+- **Obsidian, Dendron, Foam, plain markdown folders** — these already read
+  and preserve YAML frontmatter, so `note-state` works with zero
+  adaptation: run it straight against your vault folder. In Obsidian, the
+  [Dataview](https://github.com/blacksmithgu/obsidian-dataview) plugin can
+  turn `state` into a live board, e.g.:
+
+  ```
+  TABLE state, state_history[-1].date AS "last moved"
+  FROM "Notes"
+  SORT state
+  ```
+
+- **Logseq** — pages are markdown files too, but Logseq's own metadata
+  lives as a `key:: value` line on the first block rather than a `---`
+  frontmatter block. Keep frontmatter *and* Logseq properties side by side
+  (Logseq ignores the frontmatter block, `note-state` ignores the `::`
+  line), or adapt the parser in `note_state/cli.py` to read
+  `state:: drafting` instead.
+
+- **Notion** (or any database-backed app without local files) — recreate
+  `states.yaml` as a **Status** property with matching options, and use a
+  Board view grouped by it. You lose `note-state`'s enforcement of
+  transition rules unless you script it against the Notion API, but the
+  state vocabulary and pipeline shape carry over directly.
+
+## Design notes
+
+- **Backward moves are allowed on purpose.** Review can send a note back to
+  Drafting; Formatting can send it back to Review. Knowledge work isn't
+  strictly linear, and a state system that can't represent "this needs
+  another pass" will just get ignored.
+- **`needs_revision` is a trapdoor, not a stage.** It exists so a problem
+  found at any point can be flagged without losing the note's place in the
+  pipeline — it always returns to wherever it came from.
+- **`--force` exists deliberately.** Rules are useful defaults, not a cage;
+  sometimes you really do want to fast-track or bulk-correct a note.
+
+## License
+
+MIT

note_state-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+note_state/__init__.py,sha256=EfgXMRAmWn2fjHw_V1DnoVMAnPKo6-Zm-Zfcamsx3Vw,102
+note_state/cli.py,sha256=ogm3ao6RmzurMxxcnU3trmVzSRZKcZm5VYK-nntTaPo,8362
+note_state/default_states.yaml,sha256=M755AD8e2OCGZTAKLBxcZytD2f7m-mGewsyZwQckEAk,2489
+note_state-0.1.0.dist-info/licenses/LICENSE,sha256=kly0zl_87o8kF1kD2kW0EJIqFOirFiZPYRw5X3BOXkQ,1066
+note_state-0.1.0.dist-info/METADATA,sha256=ArYtmw15IgoCZH10Tbga02WEOjhnqcp4x-QeEuuxgNI,7137
+note_state-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+note_state-0.1.0.dist-info/entry_points.txt,sha256=p_oMzKEtUQsiXkyhYEB7Nbop3QbQ4JYOYTW1pLUFUIM,51
+note_state-0.1.0.dist-info/top_level.txt,sha256=rN_hy_ZhAEaNiK62LQwFhAOBEsEO_eQZm_tKwoAxzZU,11
+note_state-0.1.0.dist-info/RECORD,,

note_state-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

note_state-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+note-state = note_state.cli:main

note_state-0.1.0.dist-info/licenses/LICENSE

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

note_state-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+note_state