BundleWorkingCopy.h header

#include <ew/app/BundleWorkingCopy.h>

Namespace ew::app

PreparedWorkingCopy struct

struct ew::app::PreparedWorkingCopy

The outcome of preparing a bundle's working copy for opening.

Members

QString ew::app::PreparedWorkingCopy::directory

The working-copy folder, ready to be opened as a folder-of-text project.

BundleOpenAction ew::app::PreparedWorkingCopy::action =

What was done to get it ready (surface RecoverWorkingCopy and BackUpThenExtractFresh to the user as status notes; they mean something happened to their data's history).

QString ew::app::PreparedWorkingCopy::backupPath

When a diverged working copy was backed up before re-extraction, the .ewbackup path (empty otherwise, or when there was nothing to back up).

WorkingCopyMetadata struct

struct ew::app::WorkingCopyMetadata

What the working-copy sidecar records about the bundle as last synced: the exact bundle path it belongs to, and the SHA-256 of the bundle file's bytes at the last successful extract/repack. The sidecar lives BESIDE the working copy (<workingDir>.json), never inside it, so the project folder itself stays pristine.

Members

QString ew::app::WorkingCopyMetadata::bundlePath

The bundle file this working copy mirrors, as last recorded.

QString ew::app::WorkingCopyMetadata::bundleSha256

Hex SHA-256 of the bundle file's bytes as last synced (see bundleSha256).

bool ew::app::WorkingCopyMetadata::operator==(const WorkingCopyMetadata &) const =default

Value equality across all fields.

Enumerations

enum class BundleOpenAction { ExtractFresh, ReuseWorkingCopy, RecoverWorkingCopy, BackUpThenExtractFresh }

What opening a bundle should do with its working copy. See docs/SINGLE_FILE_PROJECTS.md section 1.4 for the policy this encodes.

enum class WorkingCopyState { Missing, MatchesBundle, DiffersPackable, Unpackable }

How a bundle's existing working copy relates to the bundle file right now – the observable half of the open decision (the other half is whether the sidecar fingerprint still matches the file, i.e. whether anything external replaced it).

Functions

QString ew::app::bundleWorkingCopyDir(const QString &workingCopiesRoot, const QString &bundlePath)

Where the working copy for the .ewriter bundle at bundlePath lives under workingCopiesRoot: <root>/<sanitised-stem>-<sha256-prefix>, keyed by the bundle file's cleaned absolute path folded to lower case (Windows paths are case-insensitive, so two spellings of one file must map to one working copy). Deterministic and collision-proof for distinct files: the readable stem is cosmetic, the hash is the identity. The bundle file need not exist yet (New Project derives the working copy before the file is first written).

BundleOpenAction ew::app::planBundleOpen(WorkingCopyState state, bool metadataMatchesBundle)

The deterministic, data-preserving open policy: given the working copy's state and whether the sidecar fingerprint still matches the bundle file (metadataMatchesBundle), decides what to do. Pure – the whole policy is this truth table: Missing -> ExtractFresh; MatchesBundle -> ReuseWorkingCopy (regardless of metadata); DiffersPackable + match -> RecoverWorkingCopy; DiffersPackable + mismatch -> BackUpThenExtractFresh; Unpackable -> BackUpThenExtractFresh.

ew::core::Result< PreparedWorkingCopy > ew::app::prepareBundleWorkingCopy(const QString &bundlePath, const QString &workingCopiesRoot, const QString &backupsDir, const QString &timestamp)

Prepares the working copy for the bundle at bundlePath under workingCopiesRoot so it can be opened as an ordinary folder project: classifies the existing copy, applies planBundleOpen (extract / reuse / recover-and-repack / back-up-then-re-extract, with backups written to backupsDir stamped timestamp), and records the synced fingerprint in the sidecar. Errors when the bundle file is missing, invalid, or hostile, or when a required filesystem step fails; on error an existing working copy is left untouched. A sidecar write failure is non-fatal (see writeWorkingCopyMetadata).

std::optional< WorkingCopyMetadata > ew::app::readWorkingCopyMetadata(const QString &workingDir)

Reads the sidecar for the working copy at workingDir, or nullopt when it is absent or unparseable (both mean "nothing reliable is known about the last sync" and resolve conservatively in planBundleOpen).

ew::core::Result< void > ew::app::syncWorkingCopyToBundle(const QString &workingDir, const QString &bundlePath)

Packs the working copy at workingDir into the .ewriter file at bundlePath (atomically) and records the new fingerprint in the sidecar – the one "the folder is now the truth, make the file match" step, shared by every save and by the external-change merge apply (which must sync the merged working copy into the file BEFORE reloading, or the open policy would treat the file replacement as newer and set the merge aside). A sidecar write failure is non-fatal (see writeWorkingCopyMetadata).

bool ew::app::writeWorkingCopyMetadata(const QString &workingDir, const WorkingCopyMetadata &metadata)

Writes the sidecar for the working copy at workingDir atomically. Returns false on an IO failure – which is deliberately non-fatal to callers: a missing sidecar only makes the next open resolve conservatively (back the copy up rather than recover it), never lose data.