section0/rta-handbook
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve collaborator setup UX

Browse Source
This commit is contained in:
virgil
2026-06-07 17:31:08 -07:00
parent d086243fe1
commit cf7f4d95fc
4 changed files with 158 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@@ -31,6 +31,12 @@ The script clones this repo into:
~/Developer/Section0/rta-mock-docs
```
It also installs a small helper command at:
```text
~/.local/bin/rta-mock-docs
```
Override the destination if you prefer:
```sh
@@ -41,15 +47,13 @@ TARGET_DIR=~/work/rta-mock-docs \
## Daily Flow
```sh
cd ~/Developer/Section0/rta-mock-docs
git pull --ff-only
rta-mock-docs pull
# Edit Markdown files in your normal editor.
git status
git add path/to/file.md
git commit -m "Describe the doc change"
git push
rta-mock-docs status
MESSAGE="Describe the doc change" rta-mock-docs commit
rta-mock-docs push
```
After a push, ask the projection operator to pull and project. For now that is

35
docs/projection-operations.md
View File

@@ -30,6 +30,17 @@ git push
The operator keeps a separate checkout so projection never depends on a
collaborator's dirty working tree.
Nice wrapper:
```sh
/Users/virgil/Developer/rta/tmp/markdown-projection-gitea/collaborator-checkout/rta-mock-docs/scripts/project-rta-mock-docs.sh
```
It pulls the projector checkout, checks it is clean, and runs the AFFiNE
projection command.
Manual equivalent:
```sh
git -C /Users/virgil/Developer/rta/tmp/markdown-projection-gitea/projector-checkout/rta-mock-docs pull --ff-only
```
@@ -52,14 +63,34 @@ nix develop --command bash -lc 'scripts/ops/sync-obsidian-affine.rb \
--apply'
```
Expected healthy result:
Expected healthy result currently includes five docs:
```text
docs: 3
docs: 5
mark stale: 0
mode: one-way read-only AFFiNE docs
```
## Push-To-Projection Automation
Pushing to `main` can trigger sync, but it should be implemented as a small
projection worker, not as a Gitea container hook.
Preferred shape:
```text
Gitea push webhook
-> RTA projection worker endpoint
-> pull projector checkout
-> validate clean source
-> run projection
-> emit logs/receipt
```
This keeps Gitea as Git infrastructure and keeps projection policy in RTA. A
server-side Git hook inside the Gitea container would be harder to observe,
harder to recover, and too tightly coupled to the packaged app internals.
## Rule Of Thumb
If the source repo changes, pull the projector checkout and run projection.

39
scripts/project-rta-mock-docs.sh Executable file
View File

@@ -0,0 +1,39 @@
#!/usr/bin/env sh
set -eu
PROJECTOR_DIR="${PROJECTOR_DIR:-/Users/virgil/Developer/rta/tmp/markdown-projection-gitea/projector-checkout/rta-mock-docs}"
HOME_LAB_DIR="${HOME_LAB_DIR:-/Users/virgil/Developer/Virgil-Info/home-lab-v7}"
if [ ! -d "$PROJECTOR_DIR/.git" ]; then
echo "Projector checkout not found: $PROJECTOR_DIR" >&2
exit 1
fi
if [ ! -d "$HOME_LAB_DIR" ]; then
echo "home-lab-v7 not found: $HOME_LAB_DIR" >&2
exit 1
fi
echo "==> Pulling projector checkout"
git -C "$PROJECTOR_DIR" pull --ff-only
echo "==> Checking projector checkout is clean"
if [ -n "$(git -C "$PROJECTOR_DIR" status --porcelain)" ]; then
git -C "$PROJECTOR_DIR" status --short
echo "Projector checkout is dirty; projection must read a clean source." >&2
exit 1
fi
echo "==> Projecting Markdown into AFFiNE"
cd "$HOME_LAB_DIR"
nix develop --command bash -lc "scripts/ops/sync-obsidian-affine.rb \
--name rta-mock-docs \
--source '$PROJECTOR_DIR' \
--username projection-bot \
--authentik-sub rta-projection-bot \
--affine-workspace 'Agent Workspace' \
--affine-workspace-id 53ea0a0b-eca7-4887-8e31-f5b2a8ab7744 \
--affine-user-id ce42f50a-5367-4466-920b-7422c4e27de0 \
--affine-namespace projected-markdown/mock-rta-docs \
--include '**/*.md' \
--apply"

81
scripts/setup-rta-mock-docs.sh
View File

@@ -3,12 +3,20 @@ set -eu
REPO_URL="${REPO_URL:-http://100.64.0.1:30087/virgil-admin/rta-mock-docs.git}"
TARGET_DIR="${TARGET_DIR:-$HOME/Developer/Section0/rta-mock-docs}"
COMMAND_DIR="${COMMAND_DIR:-$HOME/.local/bin}"
COMMAND_NAME="${COMMAND_NAME:-rta-mock-docs}"
COMMAND_PATH="$COMMAND_DIR/$COMMAND_NAME"
step() {
printf "\n==> %s\n" "$*"
}
if ! command -v git >/dev/null 2>&1; then
echo "git is required but was not found on PATH" >&2
exit 1
fi
step "Preparing local Markdown workspace"
if [ -d "$TARGET_DIR/.git" ]; then
echo "Repo already exists: $TARGET_DIR"
git -C "$TARGET_DIR" remote set-url origin "$REPO_URL"
@@ -22,19 +30,82 @@ fi
git -C "$TARGET_DIR" config pull.ff only
step "Installing helper command"
mkdir -p "$COMMAND_DIR"
cat > "$COMMAND_PATH" <<EOF
#!/usr/bin/env sh
set -eu
REPO_DIR="$TARGET_DIR"
usage() {
cat <<USAGE
rta-mock-docs - helper for the RTA mock docs projection repo
Commands:
open print the repo path
pull pull latest Markdown with --ff-only
status show Git status
commit commit all current changes with MESSAGE
push push current branch
help show this help
Examples:
rta-mock-docs pull
rta-mock-docs status
MESSAGE="Update concept notes" rta-mock-docs commit
rta-mock-docs push
AFFiNE is read-only for this repo. Durable edits happen in Markdown, then the
projection operator pulls and projects.
USAGE
}
case "\${1:-help}" in
open)
printf "%s\n" "\$REPO_DIR"
;;
pull)
git -C "\$REPO_DIR" pull --ff-only
;;
status)
git -C "\$REPO_DIR" status --short --branch
;;
commit)
: "\${MESSAGE:?Set MESSAGE before running commit}"
git -C "\$REPO_DIR" add .
git -C "\$REPO_DIR" commit -m "\$MESSAGE"
;;
push)
git -C "\$REPO_DIR" push
;;
help|--help|-h)
usage
;;
*)
usage >&2
exit 1
;;
esac
EOF
chmod +x "$COMMAND_PATH"
cat <<EOF
Ready.
Repo: $TARGET_DIR
Remote: $REPO_URL
Helper: $COMMAND_PATH
Daily flow:
cd "$TARGET_DIR"
git pull --ff-only
$COMMAND_NAME pull
# edit Markdown
git add .
git commit -m "Update docs"
git push
$COMMAND_NAME status
MESSAGE="Update docs" $COMMAND_NAME commit
$COMMAND_NAME push
AFFiNE updates after the projection operator pulls and runs projection.
If $COMMAND_DIR is not on PATH, add this to your shell profile:
export PATH="$COMMAND_DIR:\$PATH"
EOF