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:

   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:

   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.

   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.