stack/docs/case2/SURVEY-RUN.md

# Survey run sheet for the library host

This sheet is for whoever runs `mosaic library survey` on `<host>`, 10.1.1.54, under design 10 step
7. The survey reads one commit of a git repo and prints names and counts. It never prints note text,
property values, file names or link targets. Jason fills in the mapping for Melanie's books repo
from its output and her answers.

Out of scope: sending anything to Melanie. Design 10 step 7 makes that Jason's call.

## Before you start

- Jason's go for step 7. Step 4, the bot token in the `library-gitea` slot, comes first.
- You run as `mosaic` with `sudo -u mosaic -H` from `localadmin`. `mosaic` has no login shell.
- The stack copy from step 2 is in place at `/srv/mosaic/.local/share/mosaic-stack/copies/<id>`.
  `<id>` is the full commit id in Jason's go. It must hold row 231, which escapes control and bidi
  characters in folder names. In a canonical checkout, `git merge-base --is-ancestor 29ce1e360 <id>`
  exits 0 when it does.
- `<node dir>`, the directory that holds `node`. It is the directory of the `--node` path given to
  `case2-unit.sh` in step 2c. `scripts/mosaic` runs `node` from `PATH`.
- `<repo>`, an absolute path. See the next section.

## The repo to survey

The survey reads a local repo. It doesn't fetch. `<repo>` must:
- be the repo's top folder, or a bare repo's own folder. A folder inside a repo refuses, because the
  survey stops git from looking above the path's parent.
- belong to `mosaic`. The survey gives git no global config, so a `safe.directory` entry can't
  admit a repo another user owns.
- have a `HEAD` that names a commit. The survey reads `HEAD` and has no flag for another ref.

`<repo>` is the bus's bare mirror at `<dataRoot>/projects/<business>/<project>`, which C2-04 (row 215)
creates and C2-03a (row 222) fetches into. It is the only copy of her repo on the host (design 2.1), and
`mosaic` owns it. Survey it after the first `library.sync` succeeds. The mirror's `HEAD` points at
`refs/heads/served` (C2-03a brief), so the survey reads the commit the agents are served.

Don't survey anything else. A hand clone with the bot token would put the token where design 7.2 keeps
it out, and the mirror's refs belong to the bus. If `HEAD` names no commit, stop and report to Sage.

## Steps

1. `ssh [email protected]`.
2. Check which `node` runs. `PATH` ends in `/usr/bin:/bin`, so a wrong `<node dir>` would quietly run
   another `node`:

   ```sh
   cd /
   sudo -u mosaic -H env PATH="<node dir>:/usr/bin:/bin" sh -c 'command -v node; node --version'
   ```

   The first line must be `<node dir>/node`. If it isn't, fix `<node dir>` before going on.
3. Run the survey without a mapping:

   ```sh
   cd /
   sudo -u mosaic -H env PATH="<node dir>:/usr/bin:/bin" \
     /srv/mosaic/.local/share/mosaic-stack/copies/<id>/scripts/mosaic library survey <repo>
   echo "exit $?"
   ```

4. On exit 0, give the output to Jason. On any other exit, see "Refusals" below.
5. When Jason has a draft mapping, run it again with `--mapping`. The file holds the library entry
   alone, `{"kind": "library", "remote": ..., "branch": ..., ...}`, without the business file or the
   `"projects"` wrapper around it. `remote` and `branch` are required even though the survey doesn't
   fetch. `user` is optional here: it is the bot account name from design step 3, required for sync.
   `mosaic` must be able to read the file. Set `vaultPrefix` to her books repo's folder name
   in her vault. Without it, a link with the full path from the top of her vault resolves to nothing,
   and the setup sheet tells her to write links that way.

   ```sh
   sudo -u mosaic -H env PATH="<node dir>:/usr/bin:/bin" \
     /srv/mosaic/.local/share/mosaic-stack/copies/<id>/scripts/mosaic library survey <repo> --mapping <file>
   echo "exit $?"
   ```

The usage line is `mosaic library survey <repo> [--mapping <file>]`. `--mapping <file>` is the only
flag, and it may appear once. `--mapping=<file>` and every other flag refuse.

## What the output holds

Plain text on stdout, one line per item:

| Line | What it holds |
|---|---|
| `commit <id>` | the 40-hex commit `HEAD` names |
| `entries <n>` | every entry in that commit's tree |
| `folders (direct children: md canvas base other)` | then one line per folder that holds a file directly: its path as a JSON string and four counts. `(root)` is the repo's top |
| `markdown <n> files, <n> read, ...` | `.md` files, how many were read, how many have no front matter, how many have front matter the reader can't fully parse |
| `front matter key sets` | then `<count> [<keys>]` per set of property names. A name that isn't a short identifier prints as `(other key)` |
| `body links plain .., label .., heading .., embed .., self .., markdown ..; attachment ..` | link forms in note bodies, and embeds of a target with an extension other than `.md` |
| `field appears_in wikilink .., name ..` | values written as links and as plain names. A `relationships` line follows |

With `--mapping` three lines follow:

| Line | What it holds |
|---|---|
| `scopes canon .., playground .., unmapped ..; indexed ..` | tree entries per scope, and notes indexed |
| `resolved root .., vault-prefix .., relative .., shortest .., unresolved ..` | links per resolver step. `unresolved` is the R4 count |
| `problems R1 .., ..., R8 ..` | problems per rule |

Folder paths and short property names are the only words from her repo in the output. In a folder
name, tab, newline, carriage return, backspace and form feed print as `\t`, `\n`, `\r`, `\b` and `\f`.
Any other control or bidi character prints as `\uXXXX`.

## Refusals

A refusal prints nothing on stdout and one line on stderr. The survey checks the mapping before the
repo, so a bad mapping gives exit 3 even when the repo path is wrong too.

| Exit | stderr | Cause | What to do |
|---|---|---|---|
| 4 | `library survey: usage: mosaic library survey <repo> [--mapping <file>]` | no repo, two repos, an unknown flag, `--mapping` without a file or twice | Fix the command |
| 3 | `library survey: library-mapping-invalid: <file> is not a readable JSON file` | missing, unreadable by `mosaic`, or not JSON | Fix the file or its mode |
| 3 | `library survey: library-mapping-invalid: <file> <reason>` | the entry breaks the schema. The reason names the key | Give it to Jason for the draft |
| 3 | `library survey: library-playground-other-universe: <file> universes.<u>.playground "<prefix>" lies inside book folder "<book>" of universes.<v>`, or `holds book folder` | a playground prefix inside, or holding, another universe's book folder | Give it to Jason for the draft |
| 2 | `library survey: library-git: <repo> is not a directory` | wrong path | Check `<repo>` |
| 2 | `library survey: library-git: repository has no readable HEAD commit (project-git)` | not a repo, a folder inside one, another owner, no commits, a `HEAD` with no commit, or no `git` on `PATH` | Check each. If `<repo>` is the bus mirror, stop and report to Sage |
| 2 | `library survey: library-git: <other reason>`, such as `tree listing refused (project-git)` | git failed or ran past 100 seconds | Report to Sage |
| 2 | `library survey: library-commit: <reason>` | `HEAD` names something the reader can't take as a commit, for example in a SHA-256 repository | Report to Sage |
| 127 | a line ending `exec: node: not found` | `node` isn't in `<node dir>` | Fix `<node dir>` |
| other | a Node stack trace | a fault in the survey | Stop and report the exit code to Sage |

A refusal is the answer, not an obstacle. Don't run as another user, change modes on her repo or edit
its refs to get past one.