typarr.services

typarr.services.bucket

Bucket management service. Each bucket is a git repo on disk with a .meta.yml.

class typarr.services.bucket.BucketService(data_dir: Path)

CRUD operations for buckets (git-backed project directories).

create(slug: str, description: str = '', access: list[AccessEntry] | None = None, user: User | None = None) → BucketInfo

Create a new bucket: mkdir, git init, write .meta.yml, initial commit.

delete(slug: str) → bool

Delete a bucket and its entire git repo from disk.

get(slug: str) → BucketInfo | None

Get a single bucket by slug, or None if it doesn’t exist.

list() → list[BucketInfo]

List all buckets (directories with a .git folder) in the data dir.

update(slug: str, description: str | None = None, access: list[AccessEntry] | None = None, user: User | None = None) → BucketInfo | None

Update a bucket’s .meta.yml. Only provided fields are changed.

typarr.services.compiler

Typst compiler service. Shells out to the system typst binary to produce SVG or PDF output.

class typarr.services.compiler.CompilerService(data_dir: Path, package_dir: Path | None = None, font_dir: Path | None = None)

Compiles .typ files to SVG or PDF by invoking the Typst CLI.

compile_pdf(slug: str, path: str) → Path

Compile a Typst file and return the path to the resulting PDF.

Writes to a temporary file; the caller is responsible for deleting it (typically via a BackgroundTask on the FileResponse). Raises FileNotFoundError if the source file doesn’t exist, or RuntimeError if compilation fails (with the stderr message).

compile_svg(slug: str, path: str) → list[str]

Compile a Typst file and return a list of SVG strings (one per page).

Raises FileNotFoundError if the source file doesn’t exist, or RuntimeError if compilation fails (with the stderr message).

compile_svg_from_content(slug: str, path: str, content: str) → list[str]

Compile SVG from in-memory editor content (e.g. a live Yjs buffer).

Writes the content to a hidden temp file beside the real file so that relative imports (./ and ../) resolve from the file’s own directory, exactly as they would on disk. Reading from stdin instead anchors the document at the project root, which breaks those imports. The temp file is always removed. Raises RuntimeError if compilation fails.

static version() → str

Return the installed Typst CLI version string.

typarr.services.file

File management service. Reads/writes files within bucket git repos.

class typarr.services.file.FileService(data_dir: Path)

CRUD operations for files within a bucket’s working tree.

create(slug: str, file_path: str, content: str = '') → bool

Create a new file. Returns False if it already exists or the path is invalid.

delete(slug: str, file_path: str) → bool

Delete a file. Returns False if not found.

delete_dir(slug: str, dir_path: str) → list[str] | None

Delete a directory and all its contents. Returns affected file paths.

list(slug: str) → list[FileEntry]

List all files and directories in a bucket, excluding .git and .meta.yml.

read(slug: str, file_path: str) → dict | None

Read a file’s content and modification time, or None if not found.

rename(slug: str, old_path: str, new_path: str) → bool

Rename/move a file. Returns False if source missing, dest exists, or path invalid.

rename_dir(slug: str, old_path: str, new_path: str) → list[str] | None

Rename a directory. Returns list of affected file paths, or None on error.

resolve(slug: str, file_path: str) → Path | None

Return the absolute path to a file, or None if invalid/missing.

unzip(slug: str, data: bytes, prefix: str = '') → list[str]

Extract a ZIP archive into the bucket. Returns list of extracted paths.

upload(slug: str, file_path: str, data: bytes) → bool

Write raw bytes to a file. Creates parent dirs as needed.

write(slug: str, file_path: str, content: str) → str | None

Write content to a file. Returns the ISO mtime on success, None on invalid path.

typarr.services.git

Git operations service. Wraps GitPython to expose status, commit, log, diff, and restore.

class typarr.services.git.GitService(data_dir: Path)

Git operations on bucket repositories (status, commit, log, diff, restore).

commit(slug: str, files: list[str], message: str, *, author: str = 'Typarr', email: str = '') → CommitInfo

Stage the specified files and create a commit.

diff(slug: str, path: str | None = None) → list[DiffEntry]

Return unified diffs for modified files in the working tree.

log(slug: str, path: str | None = None, max_count: int = 50) → list[CommitInfo]

Return commit history, optionally filtered to a single file.

restore(slug: str, ref: str, paths: list[str]) → list[str]

Restore files from a specific commit into the working tree.

show(slug: str, ref: str, path: str) → dict | None

Return a file’s content at a specific commit ref, or None if not found.

show_raw(slug: str, ref: str, path: str) → bytes | None

Return a file’s raw bytes at a specific commit ref, or None if not found.

status(slug: str) → list[FileStatus]

Return the working tree status of all user files (excludes .meta.yml and dotfiles).

tree(slug: str, ref: str) → list[str]

List all file paths at a specific commit ref.

typarr.services.template

Template service. Fetches the Typst package index and runs typst init.

class typarr.services.template.TemplateService(data_dir: Path, package_dir: Path | None = None)

Fetches Typst templates and initializes buckets from them.

init_template(slug: str, name: str, version: str, namespace: str = 'preview') → None

Run typst init in a temp directory, then copy files into the bucket.

This avoids the “project directory already exists” error that occurs when the bucket directory already contains .git or .meta.yml.

Raises FileNotFoundError if the bucket doesn’t exist, or RuntimeError if typst init fails.

list_local_templates() → list[dict]

Scan the package directory for local template packages, grouped by name.

Looks for typst.toml files with a [template] section under {package_dir}/{namespace}/{name}/{version}/. Same grouping shape as list_templates(): one row per (namespace, name) with all versions.

list_templates() → list[dict]

Return all Typst template packages, grouped by name with a versions list.

Each entry has the metadata of the latest version as canonical and a versions list sorted from newest to oldest. This collapses the raw index (one row per version) into one row per package for the UI.