vishnu-standard-time 0.2.0__tar.gz

vishnu_standard_time-0.2.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: vishnu-standard-time
+Version: 0.2.0
+Summary: Vishnu Standard Time: a flow-based productivity clock for humans and code.
+Author: Vishnu Gottimukkala
+License: MIT
+Project-URL: Homepage, https://time.vishnu.store
+Project-URL: Documentation, https://time.vishnu.store
+Project-URL: Source, https://time.vishnu.store
+Project-URL: Changelog, https://time.vishnu.store/.well-known/vst.json
+Keywords: time,clock,productivity,cli,vst,vishnu-standard-time
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Vishnu Standard Time for Python
+
+Vishnu Standard Time is a flow-based productivity clock for humans and code.
+
+Official clock:
+
+https://time.vishnu.store
+
+```bash
+pip install vishnu-standard-time
+```
+
+```python
+from vishnu_standard_time import local_now, format_vst, flows_for
+
+parts = local_now()
+print(format_vst(parts))
+print(flows_for(minutes=25))  # 4500
+```
+
+CLI:
+
+```bash
+vst now
+vst now --json
+vst percent
+vst flows-left
+vst stamp "started deploy"
+vst convert 25m
+vst after 4500
+vst until 180000
+vst timer 25m "deep work"
+vst focus 25m "write README"
+vst prompt
+vst badge vst.svg
+vst link
+```
+
+Core units:
+
+```text
+1 day    = 259,200 flows
+1 minute = 180 flows
+1 second = 3 flows
+1 flow   = 333⅓ ms
+```
+
+Vishnu Standard Time — https://time.vishnu.store

vishnu_standard_time-0.2.0/README.md

@@ -0,0 +1,48 @@
+# Vishnu Standard Time for Python
+
+Vishnu Standard Time is a flow-based productivity clock for humans and code.
+
+Official clock:
+
+https://time.vishnu.store
+
+```bash
+pip install vishnu-standard-time
+```
+
+```python
+from vishnu_standard_time import local_now, format_vst, flows_for
+
+parts = local_now()
+print(format_vst(parts))
+print(flows_for(minutes=25))  # 4500
+```
+
+CLI:
+
+```bash
+vst now
+vst now --json
+vst percent
+vst flows-left
+vst stamp "started deploy"
+vst convert 25m
+vst after 4500
+vst until 180000
+vst timer 25m "deep work"
+vst focus 25m "write README"
+vst prompt
+vst badge vst.svg
+vst link
+```
+
+Core units:
+
+```text
+1 day    = 259,200 flows
+1 minute = 180 flows
+1 second = 3 flows
+1 flow   = 333⅓ ms
+```
+
+Vishnu Standard Time — https://time.vishnu.store

vishnu_standard_time-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vishnu-standard-time"
+version = "0.2.0"
+description = "Vishnu Standard Time: a flow-based productivity clock for humans and code."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "Vishnu Gottimukkala" }
+]
+keywords = ["time", "clock", "productivity", "cli", "vst", "vishnu-standard-time"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Scheduling",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Utilities"
+]
+
+dependencies = []
+
+[project.urls]
+Homepage = "https://time.vishnu.store"
+Documentation = "https://time.vishnu.store"
+Source = "https://time.vishnu.store"
+Changelog = "https://time.vishnu.store/.well-known/vst.json"
+
+[project.scripts]
+vst = "vishnu_standard_time.cli:main"
+vst-py = "vishnu_standard_time.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

vishnu_standard_time-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vishnu_standard_time-0.2.0/src/vishnu_standard_time/__init__.py

@@ -0,0 +1,371 @@
+"""Vishnu Standard Time: flow-based productivity time for humans and code."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from html import escape
+import json
+import math
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+VERSION = "0.2.0"
+SCALE = "VST"
+STANDARD_NAME = "Vishnu Standard Time"
+WEBSITE_URL = "https://time.vishnu.store"
+STANDARD_LINK = f"{STANDARD_NAME} — {WEBSITE_URL}"
+
+FLOWS_PER_SECOND = 3
+FLOWS_PER_MINUTE = 180
+FLOWS_PER_HOUR = 10_800
+FLOWS_PER_DAY = 259_200
+MS_PER_DAY = 86_400_000
+# Hidden machine anchor for interop only: 2026-01-01T00:00:00.000Z
+EPOCH_UNIX_MS = 1_767_225_600_000
+
+# Legacy vick/pulse compatibility from early VST versions.
+VICKS_PER_DAY = 100_000
+PULSES_PER_VICK = 1_000
+
+
+@dataclass(frozen=True)
+class VstParts:
+    day: int
+    flow: int
+    flow_of_minute: int
+    day_ms: int
+    unix_ms: int
+    vick: int
+    pulse: int
+
+    @property
+    def flows_left_today(self) -> int:
+        return flows_left_today(self)
+
+    @property
+    def percent_of_day(self) -> float:
+        return percent_of_day(self)
+
+    @property
+    def percent_remaining(self) -> float:
+        return percent_remaining(self)
+
+    @property
+    def text(self) -> str:
+        return format_vst(self)
+
+    @property
+    def precise_text(self) -> str:
+        return format_precise(self)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return to_dict(self)
+
+
+def unix_ms_now() -> int:
+    return time.time_ns() // 1_000_000
+
+
+def from_unix_ms(unix_ms: int) -> VstParts:
+    elapsed = int(unix_ms) - EPOCH_UNIX_MS
+    day = math.floor(elapsed / MS_PER_DAY)
+    day_ms = elapsed - day * MS_PER_DAY
+    flow = min(FLOWS_PER_DAY - 1, max(0, (day_ms * FLOWS_PER_DAY) // MS_PER_DAY))
+    flow_of_minute = flow % FLOWS_PER_MINUTE
+    vick = min(VICKS_PER_DAY - 1, max(0, (day_ms * VICKS_PER_DAY) // MS_PER_DAY))
+    vick_start_ms = (vick * MS_PER_DAY) // VICKS_PER_DAY
+    pulse = min(PULSES_PER_VICK - 1, max(0, ((day_ms - vick_start_ms) * PULSES_PER_VICK) // (MS_PER_DAY // VICKS_PER_DAY or 1)))
+    return VstParts(day=int(day), flow=int(flow), flow_of_minute=int(flow_of_minute), day_ms=int(day_ms), unix_ms=int(unix_ms), vick=int(vick), pulse=int(pulse))
+
+
+def local_now() -> VstParts:
+    return from_unix_ms(unix_ms_now())
+
+
+def now() -> VstParts:
+    return local_now()
+
+
+def at_day_flow(day: int, flow: int) -> VstParts:
+    flow = int(flow) % FLOWS_PER_DAY
+    unix_ms = EPOCH_UNIX_MS + int(day) * MS_PER_DAY + (flow * MS_PER_DAY) // FLOWS_PER_DAY
+    return from_unix_ms(unix_ms)
+
+
+def format_int(value: int) -> str:
+    return f"{int(value):,}"
+
+
+def format_day(day: int) -> str:
+    sign = "+" if int(day) >= 0 else "-"
+    return f"D{sign}{abs(int(day)):06d}"
+
+
+def percent_of_day(parts: Optional[VstParts] = None) -> float:
+    p = parts or local_now()
+    return (p.day_ms / MS_PER_DAY) * 100.0
+
+
+def percent_remaining(parts: Optional[VstParts] = None) -> float:
+    return 100.0 - percent_of_day(parts)
+
+
+def flows_left_today(parts: Optional[VstParts] = None) -> int:
+    p = parts or local_now()
+    return FLOWS_PER_DAY - p.flow
+
+
+def format_percent_of_day(parts: Optional[VstParts] = None) -> str:
+    return f"{percent_of_day(parts):05.2f}% OF DAY"
+
+
+def format_percent_remaining(parts: Optional[VstParts] = None) -> str:
+    return f"{percent_remaining(parts):05.2f}% DAY REMAINING"
+
+
+def format_flow_count(parts: Optional[VstParts] = None) -> str:
+    p = parts or local_now()
+    return f"{format_int(p.flow)} / {format_int(FLOWS_PER_DAY)} flows"
+
+
+def format_flow_of_minute(parts: Optional[VstParts] = None) -> str:
+    p = parts or local_now()
+    return f"FLOW {p.flow_of_minute:03d} / {FLOWS_PER_MINUTE - 1}"
+
+
+def format_vst(parts: Optional[VstParts] = None) -> str:
+    p = parts or local_now()
+    return f"VST {format_day(p.day)} · {format_flow_count(p)} · {format_percent_of_day(p)}"
+
+
+def format_precise(parts: Optional[VstParts] = None) -> str:
+    p = parts or local_now()
+    return f"VST {format_day(p.day)} · {format_flow_of_minute(p)} · {format_flow_count(p)} · {format_percent_of_day(p)}"
+
+
+def format_flows_left(parts: Optional[VstParts] = None) -> str:
+    return f"{format_int(flows_left_today(parts))} flows left today"
+
+
+def prompt(parts: Optional[VstParts] = None) -> str:
+    p = parts or local_now()
+    return f"VST {format_int(p.flow)}/{format_int(FLOWS_PER_DAY)} {percent_of_day(p):.2f}%"
+
+
+def website_url() -> str:
+    return WEBSITE_URL
+
+
+def standard_link() -> str:
+    return STANDARD_LINK
+
+
+def to_dict(parts: Optional[VstParts] = None) -> Dict[str, Any]:
+    p = parts or local_now()
+    return {
+        "scale": SCALE,
+        "version": VERSION,
+        "day": str(p.day),
+        "flow": p.flow,
+        "flow_of_minute": p.flow_of_minute,
+        "flows_per_day": FLOWS_PER_DAY,
+        "flows_left_today": flows_left_today(p),
+        "percent_of_day": round(percent_of_day(p), 6),
+        "percent_remaining": round(percent_remaining(p), 6),
+        "text": format_vst(p),
+        "precise_text": format_precise(p),
+        "day_ms": str(p.day_ms),
+        "vick": p.vick,
+        "pulse": p.pulse,
+        "website_url": WEBSITE_URL,
+        "standard_link": STANDARD_LINK,
+    }
+
+
+def to_json(parts: Optional[VstParts] = None, *, indent: Optional[int] = 2) -> str:
+    return json.dumps(to_dict(parts), indent=indent)
+
+
+def stamp(message: str, parts: Optional[VstParts] = None) -> str:
+    return f"[{format_vst(parts or local_now())}] {message}"
+
+
+def flows_for(*, seconds: Optional[float] = None, minutes: Optional[float] = None, hours: Optional[float] = None, milliseconds: Optional[float] = None) -> int:
+    total_seconds = 0.0
+    if milliseconds is not None:
+        total_seconds += float(milliseconds) / 1000.0
+    if seconds is not None:
+        total_seconds += float(seconds)
+    if minutes is not None:
+        total_seconds += float(minutes) * 60.0
+    if hours is not None:
+        total_seconds += float(hours) * 3600.0
+    return int(round(total_seconds * FLOWS_PER_SECOND))
+
+
+def seconds_for(*, flows: int) -> float:
+    return int(flows) / FLOWS_PER_SECOND
+
+
+def minutes_for(*, flows: int) -> float:
+    return seconds_for(flows=flows) / 60.0
+
+
+def hours_for(*, flows: int) -> float:
+    return minutes_for(flows=flows) / 60.0
+
+
+def milliseconds_for(*, flows: int) -> int:
+    return int(round(seconds_for(flows=flows) * 1000.0))
+
+
+def parse_duration(value: Any) -> int:
+    if isinstance(value, int):
+        return value
+    text = str(value).strip().lower().replace("_", "")
+    if not text:
+        raise ValueError("missing duration")
+    if text.endswith("ms"):
+        return flows_for(milliseconds=float(text[:-2]))
+    if text.endswith("s"):
+        return flows_for(seconds=float(text[:-1]))
+    if text.endswith("m"):
+        return flows_for(minutes=float(text[:-1]))
+    if text.endswith("h"):
+        return flows_for(hours=float(text[:-1]))
+    return int(text)
+
+
+def duration_dict(flows: int, target: Optional[VstParts] = None) -> Dict[str, Any]:
+    return {
+        "flows": int(flows),
+        "milliseconds": milliseconds_for(flows=int(flows)),
+        "seconds": seconds_for(flows=int(flows)),
+        "minutes": minutes_for(flows=int(flows)),
+        "hours": hours_for(flows=int(flows)),
+        "target": to_dict(target) if target else None,
+    }
+
+
+def after(flows: int, parts: Optional[VstParts] = None) -> VstParts:
+    p = parts or local_now()
+    return from_unix_ms(p.unix_ms + milliseconds_for(flows=int(flows)))
+
+
+def until_flow(target_flow: int, parts: Optional[VstParts] = None) -> Dict[str, Any]:
+    p = parts or local_now()
+    target_flow = int(target_flow) % FLOWS_PER_DAY
+    day = p.day if target_flow > p.flow else p.day + 1
+    target = at_day_flow(day, target_flow)
+    flows = max(0, round((target.unix_ms - p.unix_ms) / 1000.0 * FLOWS_PER_SECOND))
+    return duration_dict(flows, target)
+
+
+@dataclass(frozen=True)
+class FocusSession:
+    label: str
+    flows: int
+    started_at: VstParts
+    ends_at: VstParts
+    mode: str = "FOCUS"
+    now_fn: Callable[[], VstParts] = local_now
+
+    @property
+    def elapsed_flows(self) -> int:
+        now_p = self.now_fn()
+        elapsed_ms = max(0, now_p.unix_ms - self.started_at.unix_ms)
+        return min(self.flows, int(round((elapsed_ms / 1000.0) * FLOWS_PER_SECOND)))
+
+    @property
+    def flows_remaining(self) -> int:
+        return max(0, self.flows - self.elapsed_flows)
+
+    @property
+    def percent_complete(self) -> float:
+        if self.flows <= 0:
+            return 100.0
+        return min(100.0, (self.elapsed_flows / self.flows) * 100.0)
+
+    def done(self) -> bool:
+        return self.flows_remaining <= 0
+
+    def summary(self) -> str:
+        return "\n".join([
+            f"{self.mode} · {self.label}",
+            f"Ends at: {format_vst(self.ends_at)}",
+            f"{format_int(self.flows_remaining)} flows left · {self.percent_complete:.2f}% complete",
+        ])
+
+
+def focus(*, flows: Optional[int] = None, seconds: Optional[float] = None, minutes: Optional[float] = None, hours: Optional[float] = None, label: str = "deep work", mode: str = "FOCUS") -> FocusSession:
+    total = int(flows if flows is not None else flows_for(seconds=seconds, minutes=minutes, hours=hours))
+    started = local_now()
+    return FocusSession(label=label, flows=total, started_at=started, ends_at=after(total, started), mode=mode)
+
+
+@dataclass(frozen=True)
+class PlanBlock:
+    name: str
+    flows: int
+
+    @property
+    def seconds(self) -> float:
+        return seconds_for(flows=self.flows)
+
+    @property
+    def minutes(self) -> float:
+        return minutes_for(flows=self.flows)
+
+
+class Plan:
+    def __init__(self) -> None:
+        self.blocks: List[PlanBlock] = []
+
+    def block(self, name: str, *, flows: Optional[int] = None, seconds: Optional[float] = None, minutes: Optional[float] = None, hours: Optional[float] = None) -> "Plan":
+        total = int(flows if flows is not None else flows_for(seconds=seconds, minutes=minutes, hours=hours))
+        self.blocks.append(PlanBlock(name=name, flows=total))
+        return self
+
+    @property
+    def total_flows(self) -> int:
+        return sum(b.flows for b in self.blocks)
+
+    @property
+    def percent_of_day(self) -> float:
+        return (self.total_flows / FLOWS_PER_DAY) * 100.0
+
+    def summary(self) -> str:
+        lines = [f"{b.name:<16} {format_int(b.flows):>9} flows · {b.minutes:.2f} min" for b in self.blocks]
+        lines.append("")
+        lines.append(f"Total: {format_int(self.total_flows)} flows · {self.percent_of_day:.2f}% of day")
+        return "\n".join(lines)
+
+
+def plan(builder: Optional[Callable[[Plan], Any]] = None) -> Plan:
+    p = Plan()
+    if builder is not None:
+        builder(p)
+    return p
+
+
+def svg_badge(parts: Optional[VstParts] = None) -> str:
+    p = parts or local_now()
+    label = escape(format_vst(p))
+    width = 560
+    return f'''<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="32" role="img" aria-label="{label}">
+  <rect width="{width}" height="32" rx="8" fill="#111"/>
+  <rect width="168" height="32" rx="8" fill="#222"/>
+  <text x="14" y="21" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13" fill="#fff">Vishnu Standard Time</text>
+  <text x="182" y="21" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13" fill="#fff">{label}</text>
+</svg>
+'''
+
+__all__ = [
+    "VERSION", "SCALE", "STANDARD_NAME", "WEBSITE_URL", "STANDARD_LINK",
+    "FLOWS_PER_SECOND", "FLOWS_PER_MINUTE", "FLOWS_PER_HOUR", "FLOWS_PER_DAY", "EPOCH_UNIX_MS",
+    "VstParts", "local_now", "now", "from_unix_ms", "at_day_flow",
+    "format_vst", "format_precise", "format_flow_count", "format_percent_of_day", "format_percent_remaining", "format_flows_left", "prompt",
+    "website_url", "standard_link", "to_dict", "to_json", "stamp",
+    "flows_for", "seconds_for", "minutes_for", "hours_for", "milliseconds_for", "parse_duration", "duration_dict", "after", "until_flow",
+    "FocusSession", "focus", "Plan", "PlanBlock", "plan", "svg_badge",
+]

vishnu_standard_time-0.2.0/src/vishnu_standard_time/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

vishnu_standard_time-0.2.0/src/vishnu_standard_time/cli.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+from . import (
+    VERSION,
+    STANDARD_LINK,
+    WEBSITE_URL,
+    duration_dict,
+    flows_left_today,
+    format_flows_left,
+    format_percent_of_day,
+    format_percent_remaining,
+    format_precise,
+    format_vst,
+    focus,
+    local_now,
+    parse_duration,
+    percent_of_day,
+    prompt,
+    stamp,
+    svg_badge,
+    to_json,
+    after,
+    until_flow,
+)
+
+HELP = f"""Vishnu Standard Time CLI
+
+Usage:
+  vst now [--json] [--precise]
+  vst percent
+  vst flows-left
+  vst stamp MESSAGE
+  vst convert 4500|25m|90s|1h [--json]
+  vst after 4500|25m|90s|1h
+  vst until FLOW [--json]
+  vst timer 4500|25m [label]
+  vst focus 4500|25m [label]
+  vst prompt
+  vst badge [file.svg]
+  vst link
+
+{STANDARD_LINK}
+"""
+
+
+def _has(args, flag):
+    return flag in args
+
+
+def _clean(args):
+    return [a for a in args if not a.startswith("--")]
+
+
+def _print_duration(flows, target=None, as_json=False):
+    data = duration_dict(flows, target)
+    if as_json:
+        print(json.dumps(data, indent=2))
+    else:
+        print(f"{data['flows']:,} flows")
+        print(f"{data['seconds']:.2f} seconds")
+        print(f"{data['minutes']:.2f} minutes")
+
+
+def _run_timer(args, mode):
+    if not args:
+        print(f"Missing duration for {mode.lower()}", file=sys.stderr)
+        return 1
+    flows = parse_duration(args[0])
+    label = " ".join(args[1:]) if len(args) > 1 else ("deep work" if mode == "FOCUS" else "timer")
+    session = focus(flows=flows, label=label, mode=mode)
+    print(session.summary())
+    # Lightweight real countdown for smoke tests and practical use.
+    sleep_s = min(max(flows / 3.0, 0.0), 1.0 if flows <= 3 else flows / 3.0)
+    if sleep_s > 0:
+        time.sleep(sleep_s)
+    print("Done.")
+    return 0
+
+
+def call(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"help", "-h", "--help"}:
+        print(HELP)
+        return 0
+
+    cmd = args.pop(0)
+
+    if cmd in {"version", "--version", "-v"}:
+        print(VERSION)
+        return 0
+
+    if cmd == "now":
+        p = local_now()
+        if _has(args, "--json"):
+            print(to_json(p))
+        elif _has(args, "--precise"):
+            print(format_precise(p))
+        else:
+            print(format_vst(p))
+        return 0
+
+    if cmd == "percent":
+        p = local_now()
+        print(format_percent_of_day(p))
+        print(format_percent_remaining(p))
+        return 0
+
+    if cmd == "flows-left":
+        print(format_flows_left(local_now()))
+        return 0
+
+    if cmd == "stamp":
+        message = " ".join(args).strip()
+        if not message:
+            print("Missing stamp message", file=sys.stderr)
+            return 1
+        print(stamp(message))
+        return 0
+
+    if cmd == "convert":
+        clean = _clean(args)
+        if not clean:
+            print("Missing duration", file=sys.stderr)
+            return 1
+        flows = parse_duration(clean[0])
+        _print_duration(flows, as_json=_has(args, "--json"))
+        return 0
+
+    if cmd == "after":
+        clean = _clean(args)
+        if not clean:
+            print("Missing duration", file=sys.stderr)
+            return 1
+        flows = parse_duration(clean[0])
+        print(format_vst(after(flows)))
+        return 0
+
+    if cmd == "until":
+        clean = _clean(args)
+        if not clean:
+            print("Missing target flow", file=sys.stderr)
+            return 1
+        data = until_flow(int(clean[0].replace(",", "")))
+        if _has(args, "--json"):
+            print(json.dumps(data, indent=2))
+        else:
+            print(f"{data['flows']:,} flows until {clean[0]}")
+            print(format_vst(local_now() if data.get("target") is None else after(data["flows"])))
+        return 0
+
+    if cmd == "timer":
+        return _run_timer(args, "TIMER")
+
+    if cmd == "focus":
+        return _run_timer(args, "FOCUS")
+
+    if cmd == "prompt":
+        print(prompt())
+        return 0
+
+    if cmd == "badge":
+        file_name = args[0] if args else "vst.svg"
+        Path(file_name).write_text(svg_badge(), encoding="utf-8")
+        print(file_name)
+        return 0
+
+    if cmd == "link":
+        print(STANDARD_LINK)
+        return 0
+
+    print(f"Unknown command: {cmd}", file=sys.stderr)
+    print(HELP)
+    return 1
+
+
+def main(argv=None):
+    raise SystemExit(call(argv))
+
+
+if __name__ == "__main__":
+    main()

vishnu_standard_time-0.2.0/src/vishnu_standard_time.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: vishnu-standard-time
+Version: 0.2.0
+Summary: Vishnu Standard Time: a flow-based productivity clock for humans and code.
+Author: Vishnu Gottimukkala
+License: MIT
+Project-URL: Homepage, https://time.vishnu.store
+Project-URL: Documentation, https://time.vishnu.store
+Project-URL: Source, https://time.vishnu.store
+Project-URL: Changelog, https://time.vishnu.store/.well-known/vst.json
+Keywords: time,clock,productivity,cli,vst,vishnu-standard-time
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Vishnu Standard Time for Python
+
+Vishnu Standard Time is a flow-based productivity clock for humans and code.
+
+Official clock:
+
+https://time.vishnu.store
+
+```bash
+pip install vishnu-standard-time
+```
+
+```python
+from vishnu_standard_time import local_now, format_vst, flows_for
+
+parts = local_now()
+print(format_vst(parts))
+print(flows_for(minutes=25))  # 4500
+```
+
+CLI:
+
+```bash
+vst now
+vst now --json
+vst percent
+vst flows-left
+vst stamp "started deploy"
+vst convert 25m
+vst after 4500
+vst until 180000
+vst timer 25m "deep work"
+vst focus 25m "write README"
+vst prompt
+vst badge vst.svg
+vst link
+```
+
+Core units:
+
+```text
+1 day    = 259,200 flows
+1 minute = 180 flows
+1 second = 3 flows
+1 flow   = 333⅓ ms
+```
+
+Vishnu Standard Time — https://time.vishnu.store

vishnu_standard_time-0.2.0/src/vishnu_standard_time.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/vishnu_standard_time/__init__.py
+src/vishnu_standard_time/__main__.py
+src/vishnu_standard_time/cli.py
+src/vishnu_standard_time.egg-info/PKG-INFO
+src/vishnu_standard_time.egg-info/SOURCES.txt
+src/vishnu_standard_time.egg-info/dependency_links.txt
+src/vishnu_standard_time.egg-info/entry_points.txt
+src/vishnu_standard_time.egg-info/top_level.txt
+tests/test_cli_smoke.py
+tests/test_vishnu_standard_time.py

vishnu_standard_time-0.2.0/src/vishnu_standard_time.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vishnu_standard_time-0.2.0/src/vishnu_standard_time.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+vst = vishnu_standard_time.cli:main
+vst-py = vishnu_standard_time.cli:main

vishnu_standard_time-0.2.0/src/vishnu_standard_time.egg-info/top_level.txt

@@ -0,0 +1 @@
+vishnu_standard_time

vishnu_standard_time-0.2.0/tests/test_cli_smoke.py

@@ -0,0 +1,59 @@
+import json
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run_vst(*args):
+    return subprocess.run(
+        [sys.executable, "-m", "vishnu_standard_time", *args],
+        cwd=ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env={**__import__("os").environ, "PYTHONPATH": str(ROOT / "src")},
+    )
+
+
+class TestCliSmoke(unittest.TestCase):
+    def assert_ok(self, *args):
+        res = run_vst(*args)
+        self.assertEqual(res.returncode, 0, f"stdout={res.stdout}\nstderr={res.stderr}")
+        return res.stdout
+
+    def test_version(self):
+        self.assertIn("0.2.0", self.assert_ok("version"))
+
+    def test_prompt(self):
+        self.assertIn("VST", self.assert_ok("prompt"))
+
+    def test_link(self):
+        self.assertIn("https://time.vishnu.store", self.assert_ok("link"))
+
+    def test_badge(self):
+        f = ROOT / "tmp-vst-py-test.svg"
+        if f.exists():
+            f.unlink()
+        self.assert_ok("badge", str(f))
+        self.assertIn("<svg", f.read_text())
+        f.unlink()
+
+    def test_now_json(self):
+        data = json.loads(self.assert_ok("now", "--json"))
+        self.assertEqual(data["scale"], "VST")
+        self.assertEqual(data["website_url"], "https://time.vishnu.store")
+
+    def test_convert_json(self):
+        data = json.loads(self.assert_ok("convert", "25m", "--json"))
+        self.assertEqual(data["flows"], 4500)
+
+    def test_unknown(self):
+        res = run_vst("not-a-real-command")
+        self.assertEqual(res.returncode, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

vishnu_standard_time-0.2.0/tests/test_vishnu_standard_time.py

@@ -0,0 +1,54 @@
+import json
+import unittest
+
+import vishnu_standard_time as vst
+
+
+class TestVishnuStandardTime(unittest.TestCase):
+    def test_epoch_day_zero(self):
+        p = vst.from_unix_ms(vst.EPOCH_UNIX_MS)
+        self.assertEqual(p.day, 0)
+        self.assertEqual(p.flow, 0)
+        self.assertEqual(vst.format_vst(p), "VST D+000000 · 0 / 259,200 flows · 00.00% OF DAY")
+
+    def test_noon_is_half_day(self):
+        p = vst.from_unix_ms(vst.EPOCH_UNIX_MS + 43_200_000)
+        self.assertEqual(p.flow, 129_600)
+        self.assertAlmostEqual(vst.percent_of_day(p), 50.0)
+
+    def test_duration_helpers(self):
+        self.assertEqual(vst.flows_for(minutes=25), 4500)
+        self.assertEqual(vst.flows_for(seconds=90), 270)
+        self.assertEqual(vst.flows_for(hours=1), 10800)
+        self.assertEqual(vst.minutes_for(flows=900), 5.0)
+
+    def test_parse_duration(self):
+        self.assertEqual(vst.parse_duration("25m"), 4500)
+        self.assertEqual(vst.parse_duration("90s"), 270)
+        self.assertEqual(vst.parse_duration("1h"), 10800)
+        self.assertEqual(vst.parse_duration("4500"), 4500)
+
+    def test_to_dict_has_site(self):
+        d = vst.to_dict(vst.from_unix_ms(vst.EPOCH_UNIX_MS))
+        self.assertEqual(d["scale"], "VST")
+        self.assertEqual(d["website_url"], "https://time.vishnu.store")
+        self.assertIn("Vishnu Standard Time", d["standard_link"])
+
+    def test_stamp(self):
+        text = vst.stamp("started", vst.from_unix_ms(vst.EPOCH_UNIX_MS))
+        self.assertIn("started", text)
+        self.assertIn("VST D+000000", text)
+
+    def test_plan(self):
+        p = vst.Plan()
+        p.block("Build", flows=18000).block("Break", minutes=5)
+        self.assertEqual(p.total_flows, 18900)
+        self.assertIn("Build", p.summary())
+
+    def test_json(self):
+        out = vst.to_json(vst.from_unix_ms(vst.EPOCH_UNIX_MS))
+        self.assertEqual(json.loads(out)["flow"], 0)
+
+
+if __name__ == "__main__":
+    unittest.main()