Getting Started

Getting Started

This page takes a stranger from a clean machine to a working sync in about five minutes, and every command below was run to produce the output shown.

What it needs

• Python 3.11 or later; the checks recorded on this wiki ran on 3.12.10.
• Git, to clone the repository.
• Network access during install only, to fetch jsonschema and pytest.
• Nothing else: no API key, no service, no other tool.

Install and test

git clone https://github.com/dboles99/rosetta.git
cd rosetta
python -m venv .venv
.venv/bin/pip install -e ".[dev]"      # Windows: .venv\Scripts\pip install -e ".[dev]"
.venv/bin/python -m pytest -q          # Windows: .venv\Scripts\python -m pytest -q

Expected output, from a run on Windows with Python 3.12.10:

..................................................                       [100%]
50 passed in 0.75s

The install adds a rosetta command (.venv/bin/rosetta, or .venv\Scripts\rosetta on Windows). The timing varies; the count does not.

First run: change a field and sync

The folder examples/rosetta_build/ holds a complete artifact of five files. Copy it to a scratch folder so that the repository stays clean, change a value in the packet, and sync:

cp -r examples/rosetta_build /tmp/ex
sed -i 's/^DECISION_COUNT=3/DECISION_COUNT=4/' /tmp/ex/rosetta_build.cpn
.venv/bin/rosetta sync rosetta_build --dir /tmp/ex

sync: machine-to-human

The Markdown view now reads - DECISION_COUNT: 4, the embedded ROSETTA:FIELDS comment records the new value, rosetta_build.fields.json matches, and the lock file holds the hashes of both regenerated views. A second sync on the same folder prints sync: no-op.

Validate

.venv/bin/rosetta validate rosetta_build --dir /tmp/ex

valid

validate reads rosetta_build.fields.json and rosetta_build.schema.json. The schema declares DECISION_COUNT as an integer with a minimum of 0, and the fields store holds the string "4" after a packet sync, so the validator first coerces numeric strings to the declared type. If the schema were tightened to a minimum of 10, the same command would print INVALID: DECISION_COUNT: 4 is less than the minimum of 10 on standard error and exit with code 1.

Provoke a conflict

Edit the same field in both views, changing the value in the packet and in the ROSETTA:FIELDS comment of the Markdown file, and run sync again:

CONFLICT: conflicting fields: DECISION_COUNT

The command exits with code 1 and changes nothing. The way out is to discard one side: restore the view you reject to its last synced content (copying the original rosetta_build.md back over the edited one will do), and the next sync takes the one-way path and carries the other side across. Making the two views agree by hand does not clear the conflict, because detection compares each view with the lock file and not with the other view; in a run for this wiki, a Markdown file edited to match the packet still produced CONFLICT: conflicting fields: with an empty list and exit code 1.

The commands

Command	Effect
rosetta sync <name> --dir <folder>	Bootstrap, update one view from the other, report a conflict, or do nothing
rosetta compile <name> --dir <folder>	An alias for sync
rosetta validate <name> --dir <folder>	Check the fields store against <name>.schema.json
rosetta expand <name> --dir <folder>	Print the Markdown view for the fields store, keeping existing notes, without writing a file

To start a new artifact, create <name>.fields.json with a schema_ver and a fields object, then run rosetta sync <name> --dir <folder>; with no lock file present, the first sync writes the packet, the Markdown, and the lock. Read the edit rules on Limits and Next Steps before editing the Markdown by hand.