sheetwright 0.1.0__py3-none-any.whl

sheetwright/__init__.py

@@ -0,0 +1,3 @@
+"""sheetwright — work with spreadsheets from Claude Code."""
+
+__version__ = '0.0.0'

sheetwright/build_hash.py

@@ -0,0 +1,41 @@
+"""Record and read the SHA-256 of the most recent built xlsx.
+
+Used by the escape-hatch detection in `import`/`build`/`recalc` to
+warn when the built xlsx has been edited externally.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class BuildHashRecord:
+    name: str
+    sha256: str
+    built_at: str  # ISO-8601 timestamp
+
+
+def write_build_hash(path: Path, rec: BuildHashRecord) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(asdict(rec), indent=2, sort_keys=True))
+
+
+def read_build_hash(path: Path) -> Optional[BuildHashRecord]:
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError:
+        return None
+    try:
+        return BuildHashRecord(
+            name=data['name'],
+            sha256=data['sha256'],
+            built_at=data['built_at'],
+        )
+    except (KeyError, TypeError):
+        return None

sheetwright/bulk.py

@@ -0,0 +1,82 @@
+"""Build the cached SQLite from data/*.csv."""
+
+from __future__ import annotations
+
+import csv
+import re
+import sqlite3
+from pathlib import Path
+from typing import List
+
+from sheetwright.exceptions import BulkInvalidIdentifierError
+
+_IDENT_RE = re.compile(r'[A-Za-z_][A-Za-z0-9_]{0,62}')
+
+
+def _validate_identifier(name: str) -> str:
+    if not _IDENT_RE.fullmatch(name):
+        raise BulkInvalidIdentifierError(
+            f'invalid SQL identifier: {name!r} '
+            '(must match [A-Za-z_][A-Za-z0-9_]{0,62})'
+        )
+    return name
+
+
+def table_name_for(filename: str) -> str:
+    stem = Path(filename).stem
+    s = re.sub(r'[^A-Za-z0-9]+', '_', stem).strip('_').lower()
+    return s or '_unnamed'
+
+
+def _csvs_newer_than(csv_paths: List[Path], db_path: Path) -> bool:
+    if not db_path.exists():
+        return True
+    db_mtime = db_path.stat().st_mtime
+    return any(p.stat().st_mtime > db_mtime for p in csv_paths)
+
+
+def build_bulk_cache(project_root: Path) -> Path:
+    project_root = Path(project_root)
+    data_dir = project_root / 'data'
+    cache_dir = project_root / '.sheetwright'
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    db_path = cache_dir / 'bulk.sqlite'
+
+    csvs = sorted(data_dir.glob('*.csv')) if data_dir.is_dir() else []
+    if not csvs:
+        # No CSVs: ensure no stale db
+        if db_path.exists():
+            db_path.unlink()
+        return db_path
+
+    if not _csvs_newer_than(csvs, db_path):
+        return db_path
+
+    # Rebuild from scratch (deterministic).
+    if db_path.exists():
+        db_path.unlink()
+
+    conn = sqlite3.connect(db_path)
+    try:
+        for csv_path in csvs:
+            table = _validate_identifier(table_name_for(csv_path.name))
+            with csv_path.open() as f:
+                reader = csv.reader(f)
+                header = next(reader, None)
+                if not header:
+                    continue
+                cols = [_validate_identifier(c) for c in header]
+                # All columns typed TEXT in Plan 1; _schema.sql support
+                # is deferred to a later plan.
+                cols_sql = ', '.join(f'"{c}" TEXT' for c in cols)
+                conn.execute(f'CREATE TABLE "{table}" ({cols_sql})')
+                placeholders = ', '.join(['?'] * len(header))
+                conn.executemany(
+                    f'INSERT INTO "{table}" VALUES ({placeholders})',
+                    list(reader),
+                )
+        conn.commit()
+    finally:
+        conn.close()
+
+    return db_path

sheetwright/calc/__init__.py

@@ -0,0 +1,20 @@
+"""Calc engine plugin layer.
+
+A calc engine evaluates a built `.xlsx` and returns the calculated
+values for every cell. The default engine is LibreOffice headless.
+"""
+
+from __future__ import annotations
+
+from sheetwright.calc.base import CalcEngine, CalcResult
+
+
+def get_calc_engine(name: str) -> CalcEngine:
+    if name == 'libreoffice':
+        from sheetwright.calc.libreoffice import LibreOfficeEngine
+
+        return LibreOfficeEngine()
+    raise ValueError(f'unknown calc engine: {name!r}')
+
+
+__all__ = ['CalcEngine', 'CalcResult', 'get_calc_engine']

sheetwright/calc/base.py

@@ -0,0 +1,22 @@
+"""CalcEngine ABC and the registry."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Dict
+
+from sheetwright.model.cell import CellValue
+from sheetwright.security import SecurityLimits
+
+CalcResult = Dict[str, Dict[str, CellValue]]
+
+
+class CalcEngine(ABC):
+    """Abstract calc engine: evaluate a built .xlsx and return values."""
+
+    @abstractmethod
+    def evaluate(
+        self, xlsx_path: Path, *, limits: SecurityLimits
+    ) -> CalcResult:
+        """Return calculated values keyed by sheet, then by A1 address."""

sheetwright/calc/cache.py

@@ -0,0 +1,59 @@
+"""Content-addressed calc cache.
+
+The cache key is the SHA-256 of the built xlsx bytes. Hits avoid
+running the calc engine entirely.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from sheetwright.calc.base import CalcResult
+
+
+def hash_xlsx(xlsx_path: Path) -> str:
+    h = hashlib.sha256()
+    with open(xlsx_path, 'rb') as f:
+        for chunk in iter(lambda: f.read(65536), b''):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def cache_path_for(cache_dir: Path, key: str) -> Path:
+    return cache_dir / f'{key}.json'
+
+
+def read_cached(cache_dir: Path, key: str) -> Optional[CalcResult]:
+    p = cache_path_for(cache_dir, key)
+    if not p.is_file():
+        return None
+    data = json.loads(p.read_text())
+    return data['result']
+
+
+def write_cached(cache_dir: Path, key: str, result: CalcResult) -> Path:
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    p = cache_path_for(cache_dir, key)
+    p.write_text(
+        json.dumps(
+            {
+                'key': key,
+                'computed_at': datetime.now(timezone.utc).isoformat(),
+                'result': result,
+            },
+            indent=2,
+            sort_keys=True,
+            default=_json_default,
+        )
+    )
+    return p
+
+
+def _json_default(obj: object) -> object:
+    if isinstance(obj, datetime):
+        return obj.isoformat() + 'Z'
+    raise TypeError(f'not JSON serializable: {type(obj).__name__}')

sheetwright/calc/libreoffice.py

@@ -0,0 +1,112 @@
+"""LibreOffice headless calc engine.
+
+Strategy: copy the input xlsx into a fresh temp dir, run
+`soffice --headless --calc --convert-to xlsx --outdir <tmp> <input>`
+which forces LibreOffice to recalculate every formula and persist
+cached values, then load the converted file with openpyxl in
+`data_only=True` mode and read every cell.
+
+We use `-env:UserInstallation=file://<tmp>/profile` to give each run
+its own profile directory so concurrent invocations do not block each
+other on LibreOffice's user-profile lock.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Dict, cast
+
+from sheetwright.calc.base import CalcEngine, CalcResult
+from sheetwright.model.cell import CellValue
+from sheetwright.security import SecurityLimits
+from sheetwright.xlsx.safe_load import safe_load_workbook
+
+
+class LibreOfficeError(RuntimeError):
+    """soffice exited non-zero or produced no output."""
+
+
+class LibreOfficeEngine(CalcEngine):
+    def __init__(self, soffice: str = 'soffice'):
+        self.soffice = soffice
+
+    def evaluate(
+        self, xlsx_path: Path, *, limits: SecurityLimits
+    ) -> CalcResult:
+        xlsx_path = Path(xlsx_path).resolve()
+        with tempfile.TemporaryDirectory(prefix='sheetwright-calc-') as td_str:
+            td = Path(td_str)
+            profile = td / 'profile'
+            outdir = td / 'out'
+            outdir.mkdir()
+
+            cmd = [
+                self.soffice,
+                '--headless',
+                '--safe-mode',
+                '--norestore',
+                '--nolockcheck',
+                '--nofirststartwizard',
+                '--nodefault',
+                '--calc',
+                f'-env:UserInstallation={profile.as_uri()}',
+                '--convert-to',
+                'xlsx',
+                '--outdir',
+                str(outdir),
+                str(xlsx_path),
+            ]
+            timeout = limits.soffice_timeout
+            try:
+                proc = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    timeout=timeout,
+                    check=False,
+                )
+            except FileNotFoundError as e:
+                raise LibreOfficeError(
+                    f'{self.soffice}: not on $PATH or not executable'
+                ) from e
+            except subprocess.TimeoutExpired as e:
+                raise LibreOfficeError(
+                    f'{self.soffice} timed out after {timeout}s'
+                ) from e
+
+            if proc.returncode != 0:
+                stderr = proc.stderr.decode('utf-8', 'replace').strip()
+                stdout = proc.stdout.decode('utf-8', 'replace').strip()
+                detail = stderr or stdout or '(no output)'
+                raise LibreOfficeError(
+                    f'soffice exited {proc.returncode}: {detail}'
+                )
+
+            converted = outdir / xlsx_path.name
+            if not converted.is_file():
+                candidates = list(outdir.glob('*.xlsx'))
+                if len(candidates) != 1:
+                    raise LibreOfficeError(
+                        f'expected 1 xlsx in {outdir}, found {candidates}'
+                    )
+                converted = candidates[0]
+
+            return _read_calculated(converted, limits)
+
+
+def _read_calculated(xlsx_path: Path, limits: SecurityLimits) -> CalcResult:
+    wb = safe_load_workbook(xlsx_path, limits, data_only=True, read_only=True)
+    try:
+        out: CalcResult = {}
+        for ws in wb.worksheets:
+            sheet: Dict[str, CellValue] = {}
+            for row in ws.iter_rows():
+                for cell in row:
+                    if cell.value is None:
+                        continue
+                    sheet[cell.coordinate] = cast(CellValue, cell.value)
+            out[ws.title] = sheet
+        return out
+    finally:
+        wb.close()

sheetwright/cli.py

@@ -0,0 +1,230 @@
+"""sheetwright CLI entry point."""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import click
+
+
+@click.group(context_settings={'help_option_names': ['-h', '--help']})
+@click.version_option(package_name='sheetwright')
+def main() -> None:
+    """Work with spreadsheets from Claude Code."""
+
+
+@main.command('init')
+@click.argument('path', type=click.Path(file_okay=False), default='.')
+def init_cmd(path: str) -> None:
+    """Scaffold an empty sheetwright project."""
+    from sheetwright.commands.init_cmd import run
+
+    run(path)
+
+
+@main.command('import')
+@click.argument(
+    'xlsx',
+    type=click.Path(exists=True, dir_okay=False),
+    required=False,
+)
+@click.option('--archive', is_flag=True, help='Copy the xlsx into imports/.')
+@click.option(
+    '--flatten',
+    is_flag=True,
+    help='Replace external-reference formulas with cached values.',
+)
+@click.option(
+    '-I',
+    '--non-interactive',
+    'non_interactive',
+    is_flag=True,
+    help='Print the diff and exit; use --apply or --abort to follow up.',
+)
+@click.option(
+    '--apply',
+    is_flag=True,
+    help='Apply a previously staged re-import.',
+)
+@click.option(
+    '--abort',
+    is_flag=True,
+    help='Discard a previously staged re-import.',
+)
+@click.option(
+    '--force',
+    is_flag=True,
+    help='Skip the uncommitted-source guard during re-import.',
+)
+@click.option(
+    '--project',
+    'project_path',
+    type=click.Path(file_okay=False),
+    default='.',
+    help='Path to the sheetwright project.',
+)
+def import_cmd(
+    xlsx: Optional[str],
+    archive: bool,
+    flatten: bool,
+    non_interactive: bool,
+    apply: bool,
+    abort: bool,
+    force: bool,
+    project_path: str,
+) -> None:
+    """Read an .xlsx file into source form, or merge updates into an
+    existing project."""
+    from sheetwright.commands.import_cmd import run
+
+    run(
+        xlsx_path=xlsx,
+        project_path=project_path,
+        archive=archive,
+        flatten=flatten,
+        non_interactive=non_interactive,
+        apply=apply,
+        abort=abort,
+        force=force,
+    )
+
+
+@main.command('build')
+@click.option(
+    '--out',
+    'out_path',
+    type=click.Path(dir_okay=False),
+    default=None,
+    help='Output path. Defaults to build/<workbook-name>.xlsx.',
+)
+@click.option(
+    '--project',
+    'project_path',
+    type=click.Path(file_okay=False),
+    default='.',
+    help='Path to the sheetwright project.',
+)
+def build_cmd(out_path: str | None, project_path: str) -> None:
+    """Compile source files into an .xlsx."""
+    from sheetwright.commands.build_cmd import run
+
+    run(project_path=project_path, out_path=out_path)
+
+
+@main.command('recalc')
+@click.option(
+    '--project',
+    'project_path',
+    type=click.Path(file_okay=False),
+    default='.',
+    help='Path to the sheetwright project.',
+)
+@click.option(
+    '--force',
+    is_flag=True,
+    help='Ignore the cache and re-run the calc engine.',
+)
+def recalc_cmd(project_path: str, force: bool) -> None:
+    """Run the calc engine and cache calculated values."""
+    from sheetwright.commands.recalc_cmd import run
+
+    run(project_path=project_path, force=force)
+
+
+@main.command('snapshot')
+@click.option(
+    '--project',
+    'project_path',
+    type=click.Path(file_okay=False),
+    default='.',
+    help='Path to the sheetwright project.',
+)
+@click.option(
+    '--update',
+    is_flag=True,
+    help='Overwrite the saved snapshot with the current calculated values.',
+)
+def snapshot_cmd(project_path: str, update: bool) -> None:
+    """Compare or update the golden-file snapshot of calculated values."""
+    from sheetwright.commands.snapshot_cmd import run
+
+    run(project_path=project_path, update=update)
+
+
+@main.command('diff')
+@click.option(
+    '--project',
+    'project_path',
+    type=click.Path(file_okay=False),
+    default='.',
+    help='Path to the sheetwright project.',
+)
+@click.option(
+    '--vs',
+    'vs',
+    type=str,
+    default=None,
+    help='Comparison target: "xlsx:<path>" or "source:<path>". '
+    'Default: build/<name>.xlsx of this project.',
+)
+def diff_cmd(project_path: str, vs: Optional[str]) -> None:
+    """Show a semantic diff between source and a target workbook."""
+    from sheetwright.commands.diff_cmd import run
+
+    run(project_path=project_path, vs=vs)
+
+
+@main.command('check')
+@click.option(
+    '--project',
+    'project_path',
+    type=click.Path(file_okay=False),
+    default='.',
+    help='Path to the sheetwright project.',
+)
+def check_cmd(project_path: str) -> None:
+    """Lint dangling refs, missing names, schema mismatches."""
+    from sheetwright.commands.check_cmd import run
+
+    run(project_path=project_path)
+
+
+@main.command(
+    'test',
+    context_settings={'ignore_unknown_options': True},
+)
+@click.option(
+    '--project',
+    'project_path',
+    type=click.Path(file_okay=False),
+    default='.',
+    help='Path to the sheetwright project.',
+)
+@click.argument('targets', nargs=-1, type=click.UNPROCESSED)
+def test_cmd(project_path: str, targets: tuple[str, ...]) -> None:
+    """Run the project's testsweet tests."""
+    from sheetwright.commands.test_cmd import run
+    from sheetwright.security import PathOutsideProjectError
+
+    try:
+        run(project_path=project_path, targets=list(targets))
+    except PathOutsideProjectError as e:
+        raise click.ClickException(str(e))
+
+
+@main.command('mcp')
+def mcp_cmd() -> None:
+    """Run the MCP server on stdio.
+
+    Most MCP clients launch this subcommand as a subprocess and
+    communicate via stdin/stdout. The server stays alive until the
+    client closes the connection.
+    """
+    from sheetwright.commands.mcp_cmd import run
+
+    run()
+
+
+if __name__ == '__main__':  # pragma: no cover
+    sys.exit(main())

sheetwright/commands/build_cmd.py

@@ -0,0 +1,44 @@
+"""Implementation of `sheetwright build`."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+from sheetwright.build_hash import BuildHashRecord, write_build_hash
+from sheetwright.bulk import build_bulk_cache
+from sheetwright.calc.cache import hash_xlsx
+from sheetwright.exceptions import ProjectError
+from sheetwright.project import Project
+from sheetwright.source.reader import read_source
+from sheetwright.xlsx.writer import write_xlsx
+
+
+def run(*, project_path: str, out_path: str | None) -> None:
+    try:
+        project = Project.open(project_path)
+    except ProjectError as e:
+        raise click.ClickException(str(e))
+
+    cfg = project.config
+
+    wb = read_source(project.root)
+    build_bulk_cache(project.root)
+
+    project.build_dir.mkdir(parents=True, exist_ok=True)
+    target = (
+        Path(out_path) if out_path else project.build_dir / f'{cfg.name}.xlsx'
+    )
+    write_xlsx(wb, target)
+    write_build_hash(
+        project.build_hash_path,
+        BuildHashRecord(
+            name=cfg.name,
+            sha256=hash_xlsx(target),
+            built_at=datetime.now(timezone.utc).isoformat(),
+        ),
+    )
+
+    click.echo(f'Built {target}')

sheetwright/commands/check_cmd.py

@@ -0,0 +1,29 @@
+"""Implementation of `sheetwright check`."""
+
+from __future__ import annotations
+
+import click
+
+from sheetwright.diff.check import check_workbook
+from sheetwright.exceptions import ProjectError
+from sheetwright.project import Project
+from sheetwright.source.reader import read_source
+
+
+def run(*, project_path: str) -> None:
+    try:
+        project = Project.open(project_path)
+    except ProjectError as e:
+        raise click.ClickException(str(e))
+
+    wb = read_source(project.root)
+    issues = check_workbook(wb, project)
+
+    if not issues:
+        click.echo('no issues')
+        return
+
+    for issue in issues:
+        loc = f' at {issue.location}' if issue.location else ''
+        click.echo(f'  [{issue.kind}]{loc}: {issue.detail}')
+    raise click.exceptions.Exit(1)

sheetwright/commands/diff_cmd.py

@@ -0,0 +1,29 @@
+"""Implementation of `sheetwright diff`."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from sheetwright.diff import diff_workbooks
+from sheetwright.diff.format import render
+from sheetwright.diff.loaders import load_target
+from sheetwright.exceptions import ProjectError
+from sheetwright.project import Project
+from sheetwright.source.reader import read_source
+
+
+def run(*, project_path: str, vs: Optional[str]) -> None:
+    try:
+        project = Project.open(project_path)
+    except ProjectError as e:
+        raise click.ClickException(str(e))
+
+    source_wb = read_source(project.root)
+    target_wb = load_target(project, vs)
+
+    d = diff_workbooks(target_wb, source_wb)
+    click.echo(render(d))
+    if not d.is_empty():
+        raise click.exceptions.Exit(1)