filemaker-patchwork 0.1.0__py3-none-any.whl

patchwork/skills/fm-standards/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fm-standards
+description: >
+  Interview the user and write a FileMaker naming-standards file before any
+  schema is created. Use when the user mentions standards, naming conventions,
+  keys, prefixes, or anchor-buoy.
+---
+
+# Naming standards
+
+Read `standards/naming.md`. If it says `status: unset`, ask these questions one at a time and wait for each answer:
+
+1. Primary keys: serial number, UUID, or a key already in the file.
+2. Table names: singular or plural.
+3. A prefix, or none.
+4. One table for global fields, and its name.
+5. Relationship graph: anchor-buoy, or the layout already used.
+6. Script and layout naming (folders, prefixes).
+
+Write the answers to `standards/naming.md` and change `unset` to `set`. Do not invent a missing answer.
+
+If the file already has schema, look at it first (`patchwork_list kind=tables`, `kind=fields`, `kind=scripts`), show the conventions that conflict, and ask which to keep.

patchwork/skills/patchwork/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: patchwork
+description: >
+  Edit a FileMaker (.fmp12) file directly: add or change fields, scripts and
+  script steps, value lists, custom functions, layouts and themes, through
+  Patchwork and Claris FMUpgradeTool, on a versioned working copy. Use when the
+  user asks to change, build, fix or explore a FileMaker solution.
+---
+
+# Edit FileMaker with Patchwork
+
+Use the `patchwork_*` MCP tools when they are available, otherwise the `patchwork` command (same names: `patchwork_add_field` is `patchwork add-field`). Never drive the FileMaker window to change schema.
+
+## The loop
+
+1. **Open once.** `patchwork_open source=... account=...` (CLI: `patchwork open app.fmp12 --account Admin`). This creates a working copy, v000. The source file is never written.
+2. **Read.** `patchwork_list kind=scripts`, `patchwork_show kind=script name="..."`. Read the object you are about to change, and one similar to what you are about to create.
+3. **Change, one thing at a time,** with a `message`. Each call creates a version, re-exports the file, and lists what changed (`+` added, `~` modified, `-` deleted).
+4. **Check** the change list. If it is not what you meant, `patchwork_undo`.
+5. **Save** with `patchwork_save dest=...` to a new file, and ask the user to open it in FileMaker.
+
+## Writing scripts
+
+Scripts are text, one step per line, as the Script Workspace shows them. Indentation is optional.
+
+```
+# Mark the client as Gold
+Set Variable [ $count ; Value: Get ( FoundCount ) ]
+If [ $count = 0 ]
+    Show Custom Dialog [ "Nothing to do" ; "No client found." ; Buttons: "OK" ]
+    Exit Script [ Text Result: False ]
+End If
+Set Field [ Clients::Status ; "Gold" ]
+Commit Records/Requests [ With dialog: Off ]
+Perform Script [ "Sort Clients" ; Parameter: "gold" ]
+```
+
+- **To edit a script:** `patchwork_show kind=script name=...`, change the lines you need, send the whole text to `patchwork_set_steps`. Lines you did not touch keep their exact step, whatever the step.
+- **New lines** work for: `# comment`, Set Field, Set Variable, If, Else If, Else, End If, Loop, Exit Loop If, End Loop, Go to Layout, Perform Script, Show Custom Dialog, Exit Script, Commit Records/Requests, Delete Record/Request, Set Error Capture, Allow User Abort, Refresh Window, Close Window, Freeze Window, New Record/Request, Show All Records, Halt Script, Beep.
+- Fields are `Occurrence::Field`, scripts and layouts are quoted names. Start a line with `//` to disable the step. In a comment, `¶` is a new line.
+- **Another step** (Perform Find, Sort Records, New Window…): copy a line for it from another script of the file if one exists. Otherwise use XML: `patchwork_show kind=step name="Sort Records"` prints a real one, and the steps parameter also takes `<Step>` elements.
+
+After every script change, Patchwork re-reads each step. If FileMaker dropped a parameter, the version is refused and the message names the step.
+
+## Putting a field on a layout
+
+`patchwork_place_field layout="Clients Details" field="Clients::Status" near="Contact Email"` copies the look and the label of the `near` field and inserts a row below it: what is underneath moves down and the part grows. `side=right` puts it next to `near` instead, if there is room. Add the field first with `patchwork_add_field` if it does not exist.
+
+## Editing a layout
+
+For anything else, `patchwork_show kind=layout name=...` gives the whole layout. Edit it (bounds, text, styles, objects), then `patchwork_replace kind=layout` with the **whole** `<Layout>` element. FMUpgradeTool skips a lone layout-object replace. `<Bounds>` are absolute, from the top of the layout. Anchoring is in each object's `<Options>`.
+
+## Deleting or renaming
+
+1. `patchwork_uses kind=... name=...` first. References are certain. Mentions are a name found in calculation text, so check them.
+2. Tell the user what uses the object, and ask before going on.
+3. `patchwork_delete` refuses while references exist. Retry with `force=true` only after the user agreed. Then fix or report each script, layout or calculation from the list.
+
+## When a change is refused
+
+- "the file did not change: this patch was skipped": FMUpgradeTool ignored it. Do not retry the same call. Check the XML against a real object from `patchwork_show`, or choose another way (for example replace the whole layout).
+- "Not deleted: these would point at nothing": other objects use it. See "Deleting or renaming".
+- Error 803: the file is open in FileMaker. Ask the user to close it.
+- A password error: `PATCHWORK_PASSWORD` is missing or wrong. Ask the user to set it in their environment. Never ask for the password in the chat.
+
+Full list of verified behaviors: https://github.com/Abdeltoto/patchwork-filemaker-mcp/blob/main/docs/fmupgradetool-field-guide.md

patchwork/templates/AGENTS.md

@@ -0,0 +1,30 @@
+# {{NAME}}
+
+This is a FileMaker project. You edit the FileMaker file with [Patchwork](https://github.com/Abdeltoto/patchwork-filemaker-mcp), through its MCP tools (`patchwork_*`) or the `patchwork` command. Never drive the FileMaker window to change schema.
+
+## How to work
+
+1. `patchwork_open` (or `patchwork open file.fmp12 --account NAME`) once. It makes a working copy in `.patchwork/`; the original file is never modified.
+2. **Read before you write.** `patchwork_list` and `patchwork_show` show any object. Scripts come as FileMaker text, one step per line (`Set Field [ Clients::Status ; "Gold" ]`): edit the text and send it back with `patchwork_set_steps`. Everything else comes as XML.
+3. Make one change per call, with a clear `message`. Each change becomes a version, is re-exported and checked. If Patchwork says the change was skipped, read the message and try another way: do not repeat the same call.
+4. `patchwork_log` shows what changed, `patchwork_undo` steps back.
+5. When the user is happy, `patchwork_save` writes the result to a **new** file. Tell the user to open it in FileMaker to check the screens.
+
+## What you can change
+
+| Object | Add | Edit | Delete |
+|---|---|---|---|
+| Field | `add_field` (text, number, date, container, calculation, global) | | `delete kind=field` |
+| Script | `add_script` with steps as text | `set_steps`, `append_steps` | `delete` |
+| Value list | `add_value_list` | `replace` | `delete` |
+| Custom function | `add_custom_function` | `replace` | `delete` |
+| Layout | `place_field` puts a field on it | `replace` (whole layout), `recolor_layouts` | `delete` |
+| Theme | | `retheme`, `replace` | |
+
+## Rules
+
+- Never ask for the password and never write it anywhere. It lives in the `PATCHWORK_PASSWORD` environment variable.
+- Before deleting or renaming anything, run `patchwork_uses`, tell the user what uses it, and wait for their go-ahead. Only then retry a refused delete with `force=true`.
+- If a call fails with error 803, the file is open in FileMaker: ask the user to close it.
+- Read `standards/naming.md` before creating schema. If it says `status: unset`, ask for the standards first.
+- Never paste record data from the file into the conversation.

patchwork/templates/gitignore

@@ -0,0 +1,9 @@
+# FileMaker files, exports and the working copies stay on this machine.
+*.fmp12
+*.fmp12.bak
+.patchwork/
+raw/
+
+# Secrets
+.env
+.env.*

patchwork/templates/naming.md

@@ -0,0 +1,12 @@
+# Naming standards - {{NAME}}
+
+status: unset
+
+Answer before creating any schema. One answer per line. Do not invent a convention that is not here.
+
+- Primary keys (serial number, UUID, existing key):
+- Table names (singular or plural):
+- Prefix (or none):
+- Table for global fields:
+- Relationship graph (anchor-buoy, other):
+- Starting theme:

patchwork/tools.py

@@ -0,0 +1,190 @@
+"""Run Claris FMUpgradeTool and FMDeveloperTool safely.
+
+- The source file is never overwritten: every command writes a new copy.
+- The password comes from PATCHWORK_PASSWORD (or --no-password) and is never printed.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+from patchwork import PatchworkError
+
+PASSWORD_ENV = "PATCHWORK_PASSWORD"
+KEY_ENV = "PATCHWORK_KEY"
+SECRET_FLAGS = {"-src_pwd", "-src_key", "-patch_key"}
+LOCAL_TOOLS = Path(os.environ.get("LOCALAPPDATA", Path.home() / ".local" / "share")) / "patchwork" / "fms-tools"
+
+
+def candidates(name: str) -> list[Path]:
+    exe = name + (".exe" if platform.system() == "Windows" else "")
+    found = []
+    override = os.environ.get("FM_UPGRADE_TOOL" if name == "FMUpgradeTool" else "FM_DEVELOPER_TOOL")
+    if override:
+        found.append(Path(override))
+    on_path = shutil.which(name)
+    if on_path:
+        found.append(Path(on_path))
+    program_files = Path(os.environ.get("ProgramFiles", r"C:\Program Files"))
+    found += [
+        program_files / "FileMaker" / "FileMaker Server" / "Database Server" / exe,
+        LOCAL_TOOLS / "PFiles64" / "FileMaker" / "FileMaker Server" / "Database Server" / exe,
+        Path("/Library/FileMaker Server/Database Server/bin") / name,
+        Path("/opt/FileMaker/FileMaker Server/Database Server/bin") / name,
+    ]
+    return found
+
+
+def find_tool(name: str) -> Path | None:
+    for path in candidates(name):
+        if path.is_file():
+            return path
+    if name == "FMDeveloperTool":
+        upgrade = find_tool("FMUpgradeTool")
+        if upgrade is not None:
+            sibling = upgrade.with_name("FMDeveloperTool" + upgrade.suffix)
+            if sibling.is_file():
+                return sibling
+    return None
+
+
+def require_tool(name: str) -> Path:
+    tool = find_tool(name)
+    if tool is None:
+        variable = "FM_UPGRADE_TOOL" if name == "FMUpgradeTool" else "FM_DEVELOPER_TOOL"
+        raise PatchworkError(
+            f"{name} not found. It ships with FileMaker Server (the free trial works). "
+            f"See docs/install-fmupgradetool.md, or set {variable} to its path."
+        )
+    return tool
+
+
+def password(no_password: bool) -> str:
+    if no_password:
+        return ""
+    value = os.environ.get(PASSWORD_ENV)
+    if not value:
+        raise PatchworkError(
+            f"Set {PASSWORD_ENV} in your shell, or pass --no-password if the account has none. "
+            "Never put it in a file or on the command line."
+        )
+    return value
+
+
+def redact(command: list[str]) -> list[str]:
+    shown, hide = [], False
+    for part in command:
+        shown.append("***" if hide else part)
+        hide = part in SECRET_FLAGS and not hide
+    return shown
+
+
+def same_path(left: Path, right: Path) -> bool:
+    return os.path.normcase(str(left.resolve())) == os.path.normcase(str(right.resolve()))
+
+
+def require_source(src: Path) -> Path:
+    src = src.resolve()
+    if not src.is_file():
+        raise PatchworkError(f"Source file not found: {src}")
+    if src.suffix.lower() != ".fmp12":
+        raise PatchworkError(f"The source must be a .fmp12 file: {src.name}")
+    return src
+
+
+def require_copy(src: Path, dest: Path, force: bool) -> Path:
+    dest = dest.resolve()
+    if same_path(src, dest):
+        raise PatchworkError("The destination is the source file. Patchwork always writes a copy.")
+    if dest.suffix.lower() != ".fmp12":
+        raise PatchworkError("The destination must end in .fmp12.")
+    if dest.exists() and not force:
+        raise PatchworkError(f"{dest} already exists. Pass --force to replace it.")
+    return dest
+
+
+def require_root(path: Path, expected: str) -> None:
+    if not path.is_file():
+        raise PatchworkError(f"File not found: {path}")
+    found = root_tag(path)
+    if found != expected:
+        raise PatchworkError(f"{path.name} has root <{found or 'unreadable'}>, expected <{expected}>.")
+
+
+def root_tag(path: Path) -> str | None:
+    raw = path.read_bytes()[:8192]
+    if raw.startswith(b"\xff\xfe") or raw.startswith(b"\xfe\xff"):
+        text = raw.decode("utf-16", errors="ignore")
+    else:
+        text = raw.decode("utf-8-sig", errors="ignore")
+    for token in text.split("<")[1:]:
+        if token.startswith(("?", "!")):
+            continue
+        name = token.split(">", 1)[0].split()
+        return name[0] if name else None
+    return None
+
+
+class Runner:
+    """Builds and runs tool commands. `quiet` captures output and shows it only on failure."""
+
+    def __init__(self, account: str, no_password: bool = False, quiet: bool = False, echo=print) -> None:
+        self.account = account
+        self.no_password = no_password
+        self.quiet = quiet
+        self.echo = echo
+
+    def generate_guids(self, src: Path, dest: Path, force: bool = False) -> None:
+        command = [str(require_tool("FMUpgradeTool")), "--generateGUIDs", "-src_path", str(src)]
+        command += self.credentials() + ["-dest_path", str(dest)]
+        if force:
+            command.append("-force")
+        self.run(command, dest)
+
+    def export_xml(self, src: Path, out: Path, force: bool = False) -> None:
+        tool = require_tool("FMDeveloperTool")
+        command = [str(tool), "--saveAsXML", str(src), self.account, password(self.no_password), "-t", str(out), "-q"]
+        if force:
+            command.append("-f")
+        shown = command.copy()
+        shown[4] = "***"
+        self.run(command, out, shown)
+
+    def validate(self, src: Path, patch: Path) -> None:
+        self.run(self.upgrade("--validatePatch", src, patch))
+
+    def apply(self, src: Path, patch: Path, dest: Path, force: bool = False) -> None:
+        command = self.upgrade("--update", src, patch) + ["-dest_path", str(dest)]
+        if force:
+            command.append("-force")
+        self.run(command, dest)
+
+    def new_file(self, xml: Path) -> None:
+        self.run([str(require_tool("FMUpgradeTool")), "--generateDBFile", "-src_path", str(xml)])
+
+    def upgrade(self, action: str, src: Path, patch: Path) -> list[str]:
+        command = [str(require_tool("FMUpgradeTool")), action, "-src_path", str(src)]
+        command += self.credentials() + ["-patch_path", str(patch), "-v"]
+        key = os.environ.get(KEY_ENV)
+        if key:
+            command += ["-src_key", key]
+        return command
+
+    def credentials(self) -> list[str]:
+        return ["-src_account", self.account, "-src_pwd", password(self.no_password)]
+
+    def run(self, command: list[str], output: Path | None = None, shown: list[str] | None = None) -> None:
+        if not self.quiet:
+            self.echo("$ " + " ".join(shown or redact(command)))
+        completed = subprocess.run(command, check=False, capture_output=self.quiet, text=True, errors="replace")
+        failed = completed.returncode != 0 or (output is not None and not output.exists())
+        if failed:
+            details = ((completed.stdout or "") + (completed.stderr or "")).strip() if self.quiet else ""
+            hint = " Is the file open in FileMaker? Close it (error 803)." if "803" in details else ""
+            raise PatchworkError(
+                f"{Path(command[0]).stem} failed (exit {completed.returncode}).{hint}" + (f"\n{details}" if details else "")
+            )

patchwork/uses.py

@@ -0,0 +1,123 @@
+"""Who uses an object: references by UUID (certain) and mentions in calculation text (possible).
+
+FileMaker exports point at layouts, scripts, fields, value lists and tables with
+`<…Reference … UUID="…">` elements. Custom functions, and fields used in calculations,
+only appear as text, so those are reported as possible mentions.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+
+from patchwork import PatchworkError, objects
+from patchwork.export import Export, unescape
+
+CDATA = re.compile(r"<!\[CDATA\[([\s\S]*?)\]\]>")
+STRING = re.compile(r'"(?:[^"\\]|\\.)*"')
+
+
+@dataclass
+class Uses:
+    target: str
+    references: Counter = field(default_factory=Counter)
+    mentions: Counter = field(default_factory=Counter)
+
+    def report(self) -> str:
+        if not self.references and not self.mentions:
+            return f"Nothing in the file uses {self.target}."
+        lines = []
+        if self.references:
+            lines.append(f"{self.target} is referenced by {len(self.references)} object(s):")
+            lines += [f"  {owner}  ({count}x)" for owner, count in sorted(self.references.items())]
+        if self.mentions:
+            lines.append(f"Possible mentions by name in calculations ({len(self.mentions)}):")
+            lines += [f"  {owner}  ({count}x)" for owner, count in sorted(self.mentions.items())]
+        return "\n".join(lines)
+
+
+def owners(export: Export) -> list[tuple[int, int, str]]:
+    """(start, end, label) of every object that can hold a reference, plus each catalog as a fallback."""
+    text = export.text
+    spans: list[tuple[int, int, str]] = []
+
+    def section(tag: str) -> tuple[int, int] | None:
+        start = text.find(f"<{tag}")
+        end = text.find(f"</{tag}>", start)
+        return (start, end) if start >= 0 and end >= 0 else None
+
+    def scan(tag: str, pattern: str, label) -> None:
+        bounds = section(tag)
+        if bounds:
+            for match in re.compile(pattern).finditer(text, *bounds):
+                spans.append((match.start(), match.end(), label(match)))
+
+    for catalog in set(re.findall(r"<(\w+Catalog)[ >]", text)) - {"FieldCatalog"}:
+        bounds = section(catalog)
+        if bounds:
+            words = re.sub(r"(?<!^)(?=[A-Z])", " ", catalog[: -len("Catalog")]).lower()
+            spans.append((*bounds, f"{words} catalog"))
+    scan("StepsForScripts", r'<Script>\s*<ScriptReference [^>]*\bname="([^"]*)"[\s\S]*?</Script>',
+         lambda m: f"script {unescape(m.group(1))}")
+    scan("LayoutCatalog", r'<Layout [^>]*\bname="([^"]*)"[^>]*>[\s\S]*?</Layout>', lambda m: f"layout {unescape(m.group(1))}")
+    scan("CustomFunctionsCatalog", r'<CustomFunction [^>]*\bname="([^"]*)"[\s\S]*?</CustomFunction>',
+         lambda m: f"custom-function {unescape(m.group(1))}")
+    scan("TableOccurrenceCatalog", r'<TableOccurrence [^>]*\bname="([^"]*)"[\s\S]*?</TableOccurrence>',
+         lambda m: f"table-occurrence {unescape(m.group(1))}")
+    scan("ValueListCatalog", r'<ValueList [^>]*\bname="([^"]*)"[\s\S]*?</ValueList>', lambda m: f"value-list {unescape(m.group(1))}")
+    bounds = section("FieldsForTables")
+    if bounds:
+        for catalog in re.compile(r"<FieldCatalog>[\s\S]*?</FieldCatalog>").finditer(text, *bounds):
+            table = re.search(r'<BaseTableReference [^>]*\bname="([^"]*)"', catalog.group(0))
+            prefix = unescape(table.group(1)) if table else "?"
+            spans.append((catalog.start(), catalog.end(), f"table {prefix}"))
+            for match in re.compile(r'<Field id="\d+" name="([^"]*)"[\s\S]*?</Field>').finditer(text, catalog.start(), catalog.end()):
+                spans.append((match.start(), match.end(), f"field {prefix}::{unescape(match.group(1))}"))
+    return spans
+
+
+def owner_at(spans: list[tuple[int, int, str]], position: int) -> str:
+    inside = [(end - start, label) for start, end, label in spans if start <= position < end]
+    return min(inside)[1] if inside else "file"
+
+
+def resolve(export: Export, kind: str, name: str) -> tuple[str, str, list[re.Pattern], str | None]:
+    """(label, UUID, mention patterns, table whose own field calculations may use the bare name)."""
+    if kind == "field":
+        table, field_name = objects.split_field(name)
+        _, uuid = export.field(table, field_name)
+        occurrences = [o.name for o in objects.items(export, "table-occurrences")
+                       if re.search(rf'<BaseTableReference [^>]*\bname="{re.escape(table)}"', o.xml)]
+        patterns = [re.compile(rf"(?<![\w:]){re.escape(o)}::{re.escape(field_name)}(?![\w])") for o in occurrences or [table]]
+        return f"field {table}::{field_name}", uuid, patterns, table
+    item = objects.find(export, kind, name)
+    patterns = [re.compile(rf"(?<![\w.]){re.escape(item.name)}(?![\w])")] if kind == "custom-function" else []
+    return f"{kind} {item.name}", item.uuid, patterns, None
+
+
+def find_uses(export: Export, kind: str, name: str) -> Uses:
+    if kind != "field":
+        kind = objects.kind(kind).name
+    label, uuid, patterns, table = resolve(export, kind, name)
+    spans = owners(export)
+    result = Uses(label)
+    if uuid:
+        for match in re.finditer(rf'<\w+Reference [^>]*\bUUID="{re.escape(uuid)}"', export.text):
+            owner = owner_at(spans, match.start())
+            if owner != label:
+                result.references[owner] += 1
+    bare = re.compile(rf"(?<![\w:]){re.escape(name.split('::', 1)[1])}(?![\w:])") if table else None
+    for match in CDATA.finditer(export.text):
+        calc = STRING.sub('""', match.group(1))
+        owner = None
+        hits = sum(len(p.findall(calc)) for p in patterns)
+        if bare:
+            owner = owner_at(spans, match.start())
+            if owner.startswith(f"field {table}::"):
+                hits += len(bare.findall(calc))
+        if hits:
+            owner = owner or owner_at(spans, match.start())
+            if owner != label and owner not in result.references:
+                result.mentions[owner] += hits
+    return result

patchwork/workspace.py

@@ -0,0 +1,174 @@
+"""A versioned working copy of a FileMaker file, kept in <project>/.patchwork/.
+
+    open    copy the source, give every object a UUID, export it        -> v000
+    apply   patch the current version into a new one, export it again   -> v001, v002...
+            and refuse the version if FMUpgradeTool changed nothing (it skips bad patches silently)
+    undo    drop the last version
+    save    copy the current version to a new .fmp12
+
+The source file is never written. The password is never stored: it comes from PATCHWORK_PASSWORD.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from patchwork import PatchworkError
+from patchwork.build import wrap
+from patchwork.export import Export
+from patchwork.objects import diff, normalize
+from patchwork.tools import Runner, require_copy, require_source
+
+FOLDER = ".patchwork"
+WORKSPACE_ENV = "PATCHWORK_PROJECT"
+
+
+@dataclass
+class Result:
+    version: int
+    message: str
+    changes: list[str]
+    patch: Path
+
+
+class Workspace:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.state_file = root / "state.json"
+        if not self.state_file.is_file():
+            raise PatchworkError(f"No Patchwork workspace in {root.parent}. Start with `patchwork open file.fmp12 --account NAME`.")
+        self.state = json.loads(self.state_file.read_text(encoding="utf-8"))
+        self._export: Export | None = None
+
+    # ----- locate -----
+
+    @staticmethod
+    def locate(project: Path | None = None) -> "Workspace":
+        if project is None and os.environ.get(WORKSPACE_ENV):
+            project = Path(os.environ[WORKSPACE_ENV])
+        if project is not None:
+            return Workspace(project.resolve() / FOLDER)
+        here = Path.cwd().resolve()
+        for folder in (here, *here.parents):
+            if (folder / FOLDER / "state.json").is_file():
+                return Workspace(folder / FOLDER)
+        raise PatchworkError("No Patchwork workspace here. Start with `patchwork open file.fmp12 --account NAME`.")
+
+    @staticmethod
+    def create(src: Path, account: str, no_password: bool, project: Path | None = None, force: bool = False,
+               runner: Runner | None = None) -> "Workspace":
+        src = require_source(src)
+        project = (project or Path.cwd()).resolve()
+        root = project / FOLDER
+        if (root / "state.json").is_file():
+            if not force:
+                current = json.loads((root / "state.json").read_text(encoding="utf-8"))
+                raise PatchworkError(
+                    f"A workspace already exists here for {Path(current['source']).name}. "
+                    "`patchwork save` your work, then pass --force to start over."
+                )
+            shutil.rmtree(root)
+        root.mkdir(parents=True)
+        (root / ".gitignore").write_text("*\n", encoding="utf-8")
+        runner = runner or Runner(account, no_password, quiet=True)
+        try:
+            runner.generate_guids(src, root / "v000.fmp12")
+            runner.export_xml(root / "v000.fmp12", root / "v000.xml", force=True)
+        except Exception:
+            shutil.rmtree(root, ignore_errors=True)
+            raise
+        state = {
+            "source": str(src),
+            "account": account,
+            "no_password": no_password,
+            "versions": [{"n": 0, "message": f"open {src.name}", "time": now(), "changes": []}],
+        }
+        (root / "state.json").write_text(json.dumps(state, indent=2), encoding="utf-8")
+        return Workspace(root)
+
+    # ----- state -----
+
+    @property
+    def version(self) -> int:
+        return self.state["versions"][-1]["n"]
+
+    def file(self, n: int | None = None) -> Path:
+        return self.root / f"v{self.version if n is None else n:03d}.fmp12"
+
+    def export_path(self, n: int | None = None) -> Path:
+        return self.root / f"v{self.version if n is None else n:03d}.xml"
+
+    @property
+    def export(self) -> Export:
+        if self._export is None:
+            self._export = Export.load(self.export_path())
+        return self._export
+
+    def runner(self, quiet: bool = True) -> Runner:
+        return Runner(self.state["account"], self.state.get("no_password", False), quiet=quiet)
+
+    def save_state(self) -> None:
+        self.state_file.write_text(json.dumps(self.state, indent=2), encoding="utf-8")
+
+    # ----- operations -----
+
+    def apply(self, actions: str | list[str], message: str, runner: Runner | None = None, dry_run: bool = False) -> Result:
+        """Apply patch actions (or a full FMUpgradeToolPatch) as a new version."""
+        parts = [actions] if isinstance(actions, str) else actions
+        text = parts[0] if len(parts) == 1 and "<FMUpgradeToolPatch" in parts[0] else wrap(*parts, version=self.export.version)
+        n = self.version + 1
+        patch = self.root / f"p{n:03d}.xml"
+        patch.write_text(text, encoding="utf-8")
+        if dry_run:
+            return Result(self.version, message, [], patch)
+        runner = runner or self.runner()
+        out, xml = self.file(n), self.export_path(n)
+        try:
+            runner.apply(self.file(), patch, out, force=True)
+            runner.export_xml(out, xml, force=True)
+            after = Export.load(xml)
+            if normalize(after.text) == normalize(self.export.text):
+                raise PatchworkError(
+                    "FMUpgradeTool reported success but the file did not change: this patch was skipped. "
+                    "See docs/fmupgradetool-field-guide.md. The patch is kept in " + str(patch)
+                )
+        except Exception:
+            for leftover in (out, xml):
+                if leftover.exists():
+                    leftover.unlink()
+            raise
+        changes = diff(self.export, after)
+        self.state["versions"].append({"n": n, "message": message, "time": now(), "changes": changes})
+        self.save_state()
+        self._export = after
+        return Result(n, message, changes, patch)
+
+    def undo(self) -> int:
+        if self.version == 0:
+            raise PatchworkError("Nothing to undo: this is the opened file.")
+        n = self.version
+        for path in (self.file(n), self.export_path(n)):
+            if path.exists():
+                path.unlink()
+        self.state["versions"].pop()
+        self.save_state()
+        self._export = None
+        return self.version
+
+    def save(self, dest: Path, force: bool = False) -> Path:
+        dest = require_copy(Path(self.state["source"]), dest, force)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(self.file(), dest)
+        return dest
+
+    def log(self) -> list[dict]:
+        return self.state["versions"]
+
+
+def now() -> str:
+    return time.strftime("%Y-%m-%d %H:%M:%S")