sqlmirror 0.2.0__py3-none-any.whl

sqlmirror/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

sqlmirror/apply.py

@@ -0,0 +1,136 @@
+"""Load change files written by the Forge app into the mirror database."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Callable
+
+from .cron import Cron
+from .db import ApplyStats, Mirror
+from .util import utcnow
+from .mapper import Mapper
+from .source import Source, parse_records
+
+# How far back to re-list files on each run. Files that land late (a slow
+# writer, clock skew) are still picked up because applied files are tracked
+# individually rather than by a single high-water mark.
+LOOKBACK = timedelta(days=1)
+
+
+class LicenseError(RuntimeError):
+    pass
+
+
+@dataclass
+class ApplyResult:
+    files: int
+    metadata_files: int
+    stats: ApplyStats
+
+
+def _day_key(source: Source, sub: str, last_key: str | None) -> str | None:
+    """Start listing one day before the newest applied file."""
+    if not last_key:
+        return None
+    rest = last_key[len(source.key(sub)):] if last_key.startswith(source.key(sub)) else ""
+    parts = rest.split("/")
+    try:
+        day = datetime(int(parts[0]), int(parts[1]), int(parts[2]))
+    except (ValueError, IndexError):
+        return None
+    start = day - LOOKBACK
+    return source.key(f"{sub}{start:%Y/%m/%d}/")
+
+
+def check_license(source: Source, log: Callable[[str], None]) -> None:
+    status = source.status()
+    if status is None:
+        log("Note: no app status file in the bucket yet (_sqlmirror/status.json).")
+        return
+    lic = status.get("license") or {}
+    if lic.get("active") is False:
+        raise LicenseError(
+            f"The SQL Mirror app on {status.get('site', 'your site')} reports an inactive license. "
+            "Renew it in Jira (Apps > Manage apps) to continue applying changes."
+        )
+
+
+def apply_once(source: Source, db: Mirror, mapper: Mapper, *, log: Callable[[str], None] = print,
+               verbose: bool = False) -> ApplyResult:
+    db.load_registry(mapper)
+    check_license(source, log)
+    stats = ApplyStats()
+
+    # Metadata first, so new custom fields are known before issues reference them.
+    last_meta = db.last_applied_file(source.key("metadata/"))
+    meta_keys = list(source.list("metadata/", _day_key(source, "metadata/", last_meta)))
+    new_meta = [k for k in meta_keys if k not in db.applied_files(meta_keys)]
+    if new_meta:
+        newest = new_meta[-1]
+        raw = source.read(newest)
+        if raw is not None:
+            for rec in parse_records(newest, raw):
+                if rec.get("type") == "metadata":
+                    db.apply_metadata(mapper, rec)
+        for k in new_meta:
+            db.mark_file_applied(k, 1 if k == newest else 0)
+        db.conn.commit()
+        if verbose:
+            log(f"Applied metadata {newest}")
+
+    last_issue = db.last_applied_file(source.key("issues/"))
+    keys = list(source.list("issues/", _day_key(source, "issues/", last_issue)))
+    applied = db.applied_files(keys)
+    todo = [k for k in keys if k not in applied]
+    for k in todo:
+        raw = source.read(k)
+        if raw is None:
+            continue
+        records = parse_records(k, raw)
+        file_stats = db.apply_records(mapper, records, source="forge")
+        db.mark_file_applied(k, len(records))
+        db.conn.commit()
+        stats.add(file_stats)
+        if verbose:
+            log(f"{k}: {file_stats.summary()}")
+    return ApplyResult(files=len(todo), metadata_files=len(new_meta), stats=stats)
+
+
+def apply_logged(source: Source, db: Mirror, mapper: Mapper, *, log: Callable[[str], None] = print,
+                 verbose: bool = False) -> ApplyResult:
+    """apply_once plus a row in sqlmirror_sync_log (also on failure)."""
+    started = utcnow()
+    try:
+        res = apply_once(source, db, mapper, log=log, verbose=verbose)
+    except Exception as exc:
+        db.log_run("apply", source.describe(), started, error=str(exc)[:1000])
+        raise
+    if res.files or res.metadata_files:
+        db.log_run("apply", source.describe(), started, files=res.files + res.metadata_files, stats=res.stats)
+    return res
+
+
+def apply_loop(source: Source, db: Mirror, mapper: Mapper, *, interval: int = 60, cron: str | None = None,
+               log: Callable[[str], None] = print, verbose: bool = False) -> None:
+    """Keep applying new files: every `interval` seconds, or on a cron schedule (UTC)."""
+    schedule = Cron.parse(cron) if cron else None
+    if schedule:
+        log(f"Watching {source.describe()} on schedule '{cron}' (UTC). Next run {schedule.next_after(utcnow()):%Y-%m-%d %H:%M} UTC. "
+            "Press Ctrl+C to stop.")
+    else:
+        log(f"Watching {source.describe()} every {interval}s. Press Ctrl+C to stop.")
+    while True:
+        if schedule:
+            wait = (schedule.next_after(utcnow()) - utcnow()).total_seconds()
+            time.sleep(max(0.0, wait))
+        try:
+            res = apply_logged(source, db, mapper, log=log, verbose=verbose)
+            if res.files or res.metadata_files:
+                log(f"{time.strftime('%H:%M:%S')} applied {res.files} files: {res.stats.summary()}")
+        except LicenseError as exc:
+            log(str(exc))
+        except Exception as exc:  # keep watching; the failure is in the sync log
+            log(f"{time.strftime('%H:%M:%S')} apply failed: {exc}")
+        if not schedule:
+            time.sleep(interval)

sqlmirror/backfill.py

@@ -0,0 +1,65 @@
+"""Initial load: read every issue with the customer's API token and write the mirror.
+
+Runs on the customer's machine. Uses the customer's own Jira rate limit, not
+the Forge app's shared pool, so a 50k-issue history never starves the app's
+incremental sync.
+"""
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable
+
+from .db import ApplyStats, Mirror
+from .jira import JiraClient
+from .mapper import Mapper
+from .util import iso, utcnow
+
+
+def _jql_quote(key: str) -> str:
+    return '"' + key.replace('"', '\\"') + '"'
+
+
+def backfill(client: JiraClient, db: Mirror, mapper: Mapper, *, projects: list[str] | None = None,
+             resume: bool = False, workers: int = 4, page_size: int = 100,
+             log: Callable[[str], None] = print) -> ApplyStats:
+    started = time.time()
+    db.load_registry(mapper)
+    log("Fetching configuration (projects, statuses, fields, versions, components)...")
+    meta = client.metadata()
+    db.apply_metadata(mapper, meta)
+    all_keys = [p["key"] for p in meta.get("projects", [])]
+    keys = [k for k in all_keys if not projects or k in {p.upper() for p in projects}]
+    missing = sorted({p.upper() for p in projects or []} - set(all_keys))
+    if missing:
+        log(f"Warning: projects not visible to this token: {', '.join(missing)}")
+    log(f"{len(meta.get('projects', []))} projects, {len(meta.get('fields', []))} fields. "
+        f"Mirroring: {', '.join(keys) or 'none'}")
+
+    total = ApplyStats()
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        for key in keys:
+            last_id = db.get_meta(f"backfill:{key}:last_id") if resume else None
+            jql = f"project = {_jql_quote(key)}"
+            if last_id:
+                jql += f" AND id > {int(last_id)}"
+            jql += " ORDER BY id ASC"
+            approx = client.approximate_count(f"project = {_jql_quote(key)}")
+            log(f"[{key}] {approx if approx is not None else '?'} issues" + (f", resuming after id {last_id}" if last_id else ""))
+            done = 0
+            fetched_at = iso(utcnow())
+            for page in client.search(jql, fields=["*all"], expand="changelog", page_size=page_size):
+                snapshots = list(pool.map(lambda i: client.complete_snapshot(i, fetched_at), page))
+                stats = db.apply_records(mapper, snapshots, source="backfill")
+                total.add(stats)
+                done += len(page)
+                db.set_meta(f"backfill:{key}:last_id", str(max(int(i["id"]) for i in page)))
+                db.conn.commit()
+                log(f"[{key}] {done} issues mirrored")
+                fetched_at = iso(utcnow())
+            db.set_meta(f"backfill:{key}:completed_at", iso(utcnow()))
+            db.conn.commit()
+    db.set_meta("backfill_completed_at", iso(utcnow()))
+    db.conn.commit()
+    log(f"Backfill finished in {time.time() - started:.0f}s: {total.summary()}. {client.api_call_summary()}.")
+    return total

sqlmirror/cli.py

@@ -0,0 +1,335 @@
+"""sqlmirror: keep a Data-Center-compatible copy of Jira Cloud in your own Postgres or SQL Server.
+
+Settings come from flags, environment variables, or a .env file in the
+current folder:
+
+  DATABASE_URL     postgresql://user:password@host:5432/dbname
+                   or sqlserver://user:password@host:1433/dbname (add ?encrypt=true for Azure SQL)
+  JIRA_SITE        https://your-site.atlassian.net
+  JIRA_EMAIL       the account that owns the API token
+  JIRA_API_TOKEN   an API token; it never leaves this machine
+  SQLMIRROR_SOURCE s3://bucket/prefix written by the Forge app (or a local folder)
+  SQLMIRROR_S3_ENDPOINT, AWS_PROFILE / AWS_* credentials for reading the bucket
+"""
+from __future__ import annotations
+
+import csv
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv
+
+from . import __version__
+
+
+def _env(name: str) -> str | None:
+    v = os.environ.get(name)
+    return v.strip() if v else None
+
+
+def _db(dsn: str | None, schema: str | None):
+    from .db import open_mirror
+
+    dsn = dsn or _env("DATABASE_URL")
+    if not dsn:
+        raise click.UsageError("Set DATABASE_URL or pass --dsn postgresql://user:pass@host/db "
+                               "(or sqlserver://user:pass@host:1433/db)")
+    return open_mirror(dsn, schema=schema or _env("SQLMIRROR_SCHEMA"))
+
+
+def _jira(verbose: bool = False):
+    from .jira import JiraClient
+
+    site, email = _env("JIRA_SITE"), _env("JIRA_EMAIL")
+    token = _env("JIRA_API_TOKEN") or _env("ATLASSIAN_API_TOKEN") or _env("ATLASSIAN_API")
+    missing = [n for n, v in (("JIRA_SITE", site), ("JIRA_EMAIL", email), ("JIRA_API_TOKEN", token)) if not v]
+    if missing:
+        raise click.UsageError(f"Set {', '.join(missing)} (environment or .env). Create a token at "
+                               "https://id.atlassian.com/manage-profile/security/api-tokens")
+    return JiraClient(site, email, token, verbose=verbose)
+
+
+def _source(location: str | None, endpoint: str | None, region: str | None, profile: str | None):
+    from .source import open_source
+
+    location = location or _env("SQLMIRROR_SOURCE")
+    if not location:
+        raise click.UsageError("Give the bucket as s3://bucket/prefix (or set SQLMIRROR_SOURCE).")
+    kwargs = {}
+    if location.startswith("s3://"):
+        kwargs = {"endpoint_url": endpoint or _env("SQLMIRROR_S3_ENDPOINT"), "region": region or _env("AWS_REGION"),
+                  "profile": profile or _env("AWS_PROFILE")}
+    return open_source(location, **kwargs)
+
+
+dsn_option = click.option("--dsn", help="postgresql://... or sqlserver://... connection string (default: $DATABASE_URL).")
+schema_option = click.option("--schema", help="Schema for the mirror tables (default: public on Postgres, dbo on SQL Server; "
+                                              "on SQL Server prefer a separate database).")
+
+
+@click.group()
+@click.version_option(__version__)
+@click.option("--env-file", type=click.Path(dir_okay=False), help="Read settings from this file (default: ./.env).")
+def main(env_file: str | None) -> None:
+    """Mirror Jira Cloud into your own Postgres or SQL Server under Data Center table names."""
+    load_dotenv(env_file or Path.cwd() / ".env", override=False)
+
+
+# ------------------------------------------------------------------- setup
+@main.command("init-db")
+@dsn_option
+@schema_option
+def init_db(dsn: str | None, schema: str | None) -> None:
+    """Create the mirror tables (safe to run again)."""
+    db = _db(dsn, schema)
+    db.init_schema()
+    click.echo("Mirror tables are ready.")
+
+
+@main.command("ddl")
+@click.option("--dialect", default=None, help="postgres or sqlserver (default: from $DATABASE_URL, else postgres).")
+@schema_option
+def print_ddl(dialect: str | None, schema: str | None) -> None:
+    """Print the CREATE TABLE statements (for a DBA to run, if sqlmirror may not create tables)."""
+    from .db import is_sqlserver_dsn
+    from .schema import ddl
+
+    if not dialect:
+        dialect = "sqlserver" if is_sqlserver_dsn(_env("DATABASE_URL") or "") else "postgres"
+    try:
+        click.echo(ddl(dialect, schema or _env("SQLMIRROR_SCHEMA")))
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="--dialect")
+
+
+@main.command("check-jira")
+def check_jira() -> None:
+    """Check the Jira token works and show what it can see."""
+    client = _jira()
+    me = client.myself()
+    click.echo(f"Signed in to {client.site} as {me.get('displayName')} ({me.get('accountId')}).")
+    projects = list(client.paged_values("/rest/api/2/project/search", 50))
+    click.echo(f"{len(projects)} projects visible: {', '.join(p['key'] for p in projects[:20])}"
+               + (" ..." if len(projects) > 20 else ""))
+
+
+# ------------------------------------------------------------------- sync
+@main.command()
+@dsn_option
+@schema_option
+@click.option("--project", "projects", multiple=True, help="Project key to mirror; repeat for more. Default: all.")
+@click.option("--resume", is_flag=True, help="Continue an interrupted backfill instead of starting over.")
+@click.option("--workers", default=4, show_default=True, help="Parallel requests for long histories.")
+@click.option("--verbose", is_flag=True)
+def backfill(dsn, schema, projects, resume, workers, verbose) -> None:
+    """Load all issues and history with your own API token (run once)."""
+    from .backfill import backfill as run
+    from .mapper import Mapper
+
+    from .util import utcnow
+
+    db = _db(dsn, schema)
+    db.init_schema()
+    started = utcnow()
+    try:
+        stats = run(_jira(verbose), db, Mapper(), projects=list(projects) or None, resume=resume, workers=workers)
+    except Exception as exc:
+        db.log_run("backfill", ",".join(projects) or "all projects", started, error=str(exc)[:1000])
+        raise
+    db.log_run("backfill", ",".join(projects) or "all projects", started, stats=stats)
+
+
+@main.command()
+@click.argument("source", required=False)
+@dsn_option
+@schema_option
+@click.option("--endpoint-url", help="S3-compatible endpoint (R2, GCS, MinIO). Default: AWS.")
+@click.option("--region", help="Bucket region.")
+@click.option("--profile", help="AWS profile to read the bucket with.")
+@click.option("--watch", is_flag=True, help="Keep running and apply new files as they arrive.")
+@click.option("--interval", default=60, show_default=True, help="Seconds between checks with --watch.")
+@click.option("--cron", "cron_expr", help='Run on a cron schedule in UTC instead, e.g. "*/15 * * * *" (implies --watch).')
+@click.option("--verbose", is_flag=True)
+def apply(source, dsn, schema, endpoint_url, region, profile, watch, interval, cron_expr, verbose) -> None:
+    """Apply change files written by the Forge app (s3://bucket/prefix or a folder)."""
+    from .apply import LicenseError, apply_logged, apply_loop
+    from .cron import Cron, CronError
+    from .mapper import Mapper
+
+    if cron_expr:
+        try:
+            Cron.parse(cron_expr)
+        except CronError as exc:
+            raise click.BadParameter(str(exc), param_hint="--cron")
+    src = _source(source, endpoint_url, region, profile)
+    db = _db(dsn, schema)
+    db.init_schema()
+    if watch or cron_expr:
+        apply_loop(src, db, Mapper(), interval=interval, cron=cron_expr, verbose=verbose)
+        return
+    try:
+        res = apply_logged(src, db, Mapper(), verbose=verbose)
+    except LicenseError as exc:
+        raise click.ClickException(str(exc))
+    click.echo(f"Applied {res.files} change files and {res.metadata_files} configuration files from "
+               f"{src.describe()}: {res.stats.summary()}.")
+
+
+@main.command()
+@dsn_option
+@schema_option
+@click.option("--project", "projects", multiple=True)
+@click.option("--deep", is_flag=True, help="Compare every issue id and updated time, not just counts.")
+@click.option("--repair", is_flag=True, help="Re-fetch missing or stale issues and remove deleted ones.")
+def reconcile(dsn, schema, projects, deep, repair) -> None:
+    """Compare the mirror with Jira (uses your API token)."""
+    from .mapper import Mapper
+    from .reconcile import format_reports, reconcile as run
+
+    reports = run(_jira(), _db(dsn, schema), Mapper(), projects=list(projects) or None, deep=deep or repair,
+                  repair=repair)
+    click.echo(format_reports(reports, deep or repair))
+    if not all(r.ok if (deep or repair) else r.jira == r.mirror for r in reports):
+        sys.exit(1)
+
+
+@main.command()
+@dsn_option
+@schema_option
+@click.option("--source", help="Also show the app status file from this bucket.")
+@click.option("--endpoint-url")
+@click.option("--region")
+@click.option("--profile")
+def status(dsn, schema, source, endpoint_url, region, profile) -> None:
+    """Show what is in the mirror and how fresh it is."""
+    db = _db(dsn, schema)
+    counts = db.table_counts()
+    applied_at, fetched_at = db.freshness()
+    click.echo(f"Issues: {counts['jiraissue']}  changes: {counts['changeitem']}  comments: {counts['jiraaction']}  "
+               f"worklogs: {counts['worklog']}  custom field values: {counts['customfieldvalue']}")
+    click.echo(f"Projects: {', '.join(f'{k} ({v})' for k, v in db.project_counts().items())}")
+    click.echo(f"Newest data fetched from Jira: {fetched_at}; last write: {applied_at}")
+    click.echo(f"Last change file applied: {db.last_applied_file() or 'none'}")
+    click.echo(f"Configuration fetched: {db.get_meta('metadata_fetched_at') or 'never'}; "
+               f"backfill finished: {db.get_meta('backfill_completed_at') or 'never'}")
+    if source or _env("SQLMIRROR_SOURCE"):
+        st = _source(source, endpoint_url, region, profile).status()
+        click.echo("App status: " + (json.dumps(st, indent=2) if st else "no status file yet"))
+
+
+@main.command("log")
+@dsn_option
+@schema_option
+@click.option("--limit", default=20, show_default=True)
+@click.option("--app", "show_app", is_flag=True, help="Also show the Forge app's sync log from the bucket.")
+@click.option("--source", help="Bucket (default $SQLMIRROR_SOURCE), for --app.")
+@click.option("--endpoint-url")
+@click.option("--region")
+@click.option("--profile")
+def show_log(dsn, schema, limit, show_app, source, endpoint_url, region, profile) -> None:
+    """Show recent runs: apply / backfill on this side, and with --app the app's sync jobs."""
+    db = _db(dsn, schema)
+    db.init_schema()
+    rows = db.recent_log(limit)
+    click.echo("Database side (apply, backfill):")
+    if not rows:
+        click.echo("  nothing yet")
+    for started, finished, kind, src, files, issues, tombstones, skipped, error in rows:
+        took = (finished - started).total_seconds() if finished and started else 0
+        line = (f"  {started:%Y-%m-%d %H:%M:%S} UTC  {kind:<9} {issues:>6} issues {tombstones:>4} deleted "
+                f"{files:>5} files {skipped:>5} skipped  {took:>6.0f}s")
+        click.echo(line + (f"  ERROR: {error}" if error else ""))
+    if show_app:
+        st = _source(source, endpoint_url, region, profile).status()
+        entries = (st or {}).get("log") or []
+        click.echo(f"\nApp side (sync jobs; schedule {(st or {}).get('schedule', '?')}):")
+        if not entries:
+            click.echo("  nothing yet (the app writes its log into _sqlmirror/status.json after each job)")
+        for e in entries[:limit]:
+            changed = ", ".join(e.get("changed") or [])
+            more = (e.get("changedCount") or 0) - len(e.get("changed") or [])
+            click.echo(f"  {e['at'][:19].replace('T', ' ')} UTC  {e.get('trigger', ''):<9} {e.get('issuesWritten', 0):>6} issues "
+                       f"{e.get('tombstones', 0):>4} deleted {e.get('apiCalls', 0):>4} Jira calls"
+                       + (f"  ERROR: {e['error']}" if e.get("error") else "")
+                       + (f"\n      {changed}" + (f" and {more} more" if more > 0 else "") if changed else ""))
+
+
+# ---------------------------------------------------------------- SQL check
+@main.command("check-sql")
+@click.argument("paths", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path))
+@click.option("--dialect", default="postgres", show_default=True,
+              help="Dialect the reports were written for: postgres, sqlserver, mysql, oracle.")
+@click.option("--id-map", type=click.Path(exists=True), help="CSV from 'sqlmirror idmap build' to rewrite ids.")
+@click.option("--out", "out_dir", type=click.Path(path_type=Path), default=Path("sqlmirror-checked"), show_default=True,
+              help="Folder for rewritten SQL and report.md.")
+@click.option("--target", default=None,
+              help="Dialect to rewrite into: postgres or sqlserver (default: the mirror's, else postgres).")
+@click.option("--explain/--no-explain", default=True, show_default=True,
+              help="Compile each rewritten statement against the mirror ($DATABASE_URL): EXPLAIN on Postgres, "
+                   "sp_describe_first_result_set on SQL Server.")
+@dsn_option
+@schema_option
+def check_sql(paths, dialect, id_map, target, out_dir, explain, dsn, schema) -> None:
+    """Check Data Center report SQL against the mirror and rewrite what it can."""
+    from .db import is_sqlserver_dsn
+    from .idmap import IdMap
+    from .sqlcheck import Checker, check_paths, markdown_report, write_outputs
+
+    mirror = None
+    if explain and (dsn or _env("DATABASE_URL")):
+        mirror = _db(dsn, schema)
+    if not target:
+        if mirror is not None:
+            target = mirror.dialect
+        else:
+            target = "sqlserver" if is_sqlserver_dsn(dsn or _env("DATABASE_URL") or "") else "postgres"
+    try:
+        checker = Checker(dialect, idmap=IdMap.load(id_map) if id_map else None, mirror=mirror, target=target)
+    except ValueError as exc:
+        raise click.UsageError(str(exc))
+    results = check_paths(list(paths), checker)
+    write_outputs(results, out_dir)
+    report = markdown_report(results, dialect=dialect, explained=mirror is not None, target=checker.target)
+    (out_dir / "report.md").write_text(report, encoding="utf-8")
+    click.echo(report)
+    click.echo(f"\nRewritten SQL and report.md are in {out_dir}/")
+
+
+@main.group()
+def idmap() -> None:
+    """Map Data Center ids (statuses, fields, users...) to Cloud ids."""
+
+
+@idmap.command("export-sql")
+@click.option("--dialect", default="postgres", show_default=True, help="Your Data Center database type.")
+def idmap_export(dialect: str) -> None:
+    """Print the query to run on the Data Center database (save the result as CSV)."""
+    from .idmap import export_sql
+
+    click.echo(export_sql(dialect))
+
+
+@idmap.command("build")
+@click.argument("dc_csv", type=click.Path(exists=True))
+@click.option("--out", default="id_map.csv", show_default=True)
+@dsn_option
+@schema_option
+def idmap_build(dc_csv: str, out: str, dsn, schema) -> None:
+    """Match the Data Center export to the mirror by name and write id_map.csv."""
+    from .idmap import build, write_csv
+
+    with open(dc_csv, newline="", encoding="utf-8-sig") as fh:
+        rows = build(csv.DictReader(fh), _db(dsn, schema))
+    write_csv(rows, out)
+    matched = sum(1 for r in rows if r["cloud_id"])
+    click.echo(f"Matched {matched} of {len(rows)} Data Center ids; wrote {out}.")
+    for r in rows:
+        if not r["cloud_id"]:
+            click.echo(f"  no match: {r['entity']} {r['dc_id']} ({r['name']}) - {r['match']}")
+
+
+if __name__ == "__main__":
+    main()

sqlmirror/cron.py

@@ -0,0 +1,103 @@
+"""Minimal 5-field cron (UTC by default): minute hour day-of-month month day-of-week.
+
+Supports *, numbers, ranges, lists, steps, month/day names and the presets
+@hourly, @daily, @weekly, @monthly. Same rules as sql-mirror/src/cron.js.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+PRESETS = {"@hourly": "0 * * * *", "@daily": "0 0 * * *", "@midnight": "0 0 * * *",
+           "@weekly": "0 0 * * 0", "@monthly": "0 0 1 * *"}
+MONTHS = ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"]
+DAYS = ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"]
+FIELDS = [("minute", 0, 59, None, 0), ("hour", 0, 23, None, 0), ("day of month", 1, 31, None, 0),
+          ("month", 1, 12, MONTHS, 1), ("day of week", 0, 7, DAYS, 0)]
+
+
+class CronError(ValueError):
+    pass
+
+
+def _value(token: str, field) -> int:
+    name, lo, hi, names, offset = field
+    if names and token.upper() in names:
+        return names.index(token.upper()) + offset
+    if not token.isdigit():
+        raise CronError(f'"{token}" is not valid in the {name} field')
+    n = int(token)
+    if n < lo or n > hi:
+        raise CronError(f"{n} is out of range for {name} ({lo}-{hi})")
+    return n
+
+
+def _field(text: str, field) -> set[int]:
+    name, lo_f, hi_f, _, _ = field
+    out: set[int] = set()
+    for part in text.split(","):
+        rng, _, step_text = part.partition("/")
+        step = int(step_text) if step_text else 1
+        if step < 1:
+            raise CronError(f"bad step in {name}")
+        if rng == "*":
+            lo, hi = lo_f, hi_f
+        elif "-" in rng:
+            a, b = rng.split("-", 1)
+            lo, hi = _value(a, field), _value(b, field)
+            if lo > hi:
+                raise CronError(f"range {rng} goes backwards in {name}")
+        else:
+            lo = _value(rng, field)
+            hi = hi_f if step_text else lo
+        out.update(range(lo, hi + 1, step))
+    return out
+
+
+@dataclass
+class Cron:
+    expr: str
+    minute: set[int]
+    hour: set[int]
+    dom: set[int]
+    month: set[int]
+    dow: set[int]
+    dom_any: bool
+    dow_any: bool
+
+    @classmethod
+    def parse(cls, expr: str) -> "Cron":
+        text = PRESETS.get(expr.strip().lower(), expr).strip()
+        parts = text.split()
+        if len(parts) != 5:
+            raise CronError("A schedule needs 5 fields: minute hour day-of-month month day-of-week")
+        sets = [_field(p, FIELDS[i]) for i, p in enumerate(parts)]
+        if 7 in sets[4]:
+            sets[4].add(0)
+        return cls(expr, *sets, parts[2] == "*", parts[4] == "*")
+
+    def matches(self, dt: datetime) -> bool:
+        if dt.minute not in self.minute or dt.hour not in self.hour or dt.month not in self.month:
+            return False
+        dom_ok = dt.day in self.dom
+        dow_ok = (dt.isoweekday() % 7) in self.dow  # Sunday = 0
+        if self.dom_any and self.dow_any:
+            return True
+        if self.dom_any:
+            return dow_ok
+        if self.dow_any:
+            return dom_ok
+        return dom_ok or dow_ok
+
+    def next_after(self, dt: datetime) -> datetime:
+        t = dt.replace(second=0, microsecond=0) + timedelta(minutes=1)
+        limit = t + timedelta(days=366)
+        while t < limit:
+            if self.matches(t):
+                return t
+            t += timedelta(minutes=1)
+        raise CronError(f"schedule {self.expr!r} never runs")
+
+
+def now_local(tz: timezone | None = None) -> datetime:
+    return datetime.now(tz or timezone.utc)