@debonet/idd 0.0.0-stage → 0.1.1

package/scripts/commands.js

@@ -0,0 +1,908 @@
+// @tested-by test/idd-page.test.js
+// @implements s-4lt6mo@2440660
+// @implements s-cg2j10@e28309f
+// @implements s-dal2u7@29b9549
+// @implements s-s1eg2z@e4283c0
+// @implements s-hsle36@555b1d8
+// @implements s-7wfrt9@cf88f5c
+// @implements s-q3kge1@ba97ef3
+// @implements s-854kw7@d393719
+// @implements s-y1y75p@326b683
+// @implements s-zrui8r@5a4422e
+// @implements s-zqk718@d5acf2d
+// @implements s-qvff9k@3d4e66c
+// @implements s-w9knti@d14fa7f
+// @implements s-9oyy6g@e000a9d
+// @implements s-f9mmtf@b19805c
+// @implements s-0fiha8@6f2ad42
+// @implements s-0399cx@d927ab4
+// @implements s-dvurdo@4167f20
+// @implements s-ddc95k@7196ab1
+// @implements s-2bfbql@55fab0b
+// @implements s-0ys3dr@2da1f17
+// @implements s-fm0j9h@debe84e
+// @implements s-51ncq9@71d9dc3
+// @implements s-cd2jke@3b2070f
+// @implements s-hcsr5l@76b1b4a
+// @implements s-9exkpo@4f91381
+// @implements s-sse100@ccc5706
+// @implements s-qzz6xu@29b0633
+// @implements s-9e2f7d@5833072
+// @implements s-mvtsgu@0347ca1
+// @implements s-r2o7ne@b4bd635
+// @implements s-30veoz@0e078f1
+// @implements s-hbdizs@70b7167
+// @implements s-zopa6h@ac3585f
+// @implements s-yx8tuh@612f0b5
+// @implements s-xrkyna@a015af7
+// @implements s-lzdklu@60f00ba
+// @implements s-vhcbdr@9334045
+// @implements s-cals8z@4a2d967
+// @implements s-rueqkl@c59d2d4
+// @implements s-hnxl58@6be6d28
+// @implements s-zmh8z6@a41e05d
+// @implements s-51kf4i@4cf5a6a
+// @implements s-2s3q95@7154581
+// @implements s-akhsa6@5f649c1
+// @implements s-pos9d5@0cf7fea
+// @implements s-o5jdcy@e401a4f
+// @implements s-19wno0@e8ab1b2
+// @implements s-09iime@6063232
+// @implements s-p66ewo@a59e771
+// @implements s-4y820y@d019d03
+// @implements s-vfgnzf@47216b8
+// @implements s-vwase3@5417720
+// @implements s-4w8iuj@b42f67f
+// @implements s-83u8i8@a535264
+// @implements s-1mid3a@fe7e2f2
+// @implements s-6uvlo6@47f8459
+// @implements s-t8xsan@8e2e532
+// @implements s-jpjbwh@b74a3f0
+// @implements s-yufw52@ad4e715
+// @implements s-14wrxl@7a4474b
+// @implements s-amd1ad@5c9c949
+// @implements s-8hvj7z@4ee0664
+// @implements s-2jdc1d@964ddde
+// @implements s-ky6iv4@0879c7a
+// @implements s-7pdsig@761907d
+// @implements s-7uz5pq@ea5a63d
+// @implements s-wapj39@5412047
+// @implements s-twjecx@96950c4
+// @implements s-g5gxep@784430f
+// @implements s-axz9ts@7132791
+const fs = require( "fs" )
+const path = require( "path" )
+const { URL } = require( "url" )
+const { spawnSync } = require( "child_process" )
+const {
+  fvsProblem, fvsAddProblem, fbIsoTime, sFilePage, sFileQuestion, sFileAnswer,
+  sFilePending, fsQuestionId, fsLegacyQuestionId, fsBranchHash, faQuestionOptions,
+  sFileStatus, fvsStatusProblem,
+  sFileHistory, sFileConflict, faQuestionOfId, sFileThoughts, sFileClaims,
+} = require( "./check" )
+const { fxWithLock } = require( "./project-lock" )
+const { fsHtml } = require( "./page-build" )
+const { fvaQuestionFromPage } = require( "./import-page" )
+
+const sFileBuilt = "tmp/idd/page.html"
+const sUsage = [
+  "usage: idd <subcommand> [arguments]",
+  "       idd guide",
+  "       idd viewer-url <owner/repository> <code-branch>",
+  "       idd init <title> <branch-hash>",
+  "       idd branch-hash <repository-id> <full-ref>",
+  "       idd check",
+  "       idd build",
+  "       idd add   (a JSON question on stdin)",
+  "       idd archive <question-id> <replacement-id>",
+  "       idd import <page>",
+  "       idd answer <id>   (a JSON answer on stdin)",
+  "       idd status <session-id> <blocked|working|clear>",
+  "       idd claim <answer|thought|conflict> <item-id> <session-id>",
+  "       idd release <answer|thought|conflict> <item-id> <session-id>",
+  "       idd count [--nosync] [--type <c|u|a|s|conflicts|unanswered|answered|superseded>]",
+  "       idd thoughts [--nosync]",
+  "       idd clear-pending <id> <time>",
+  "       idd wait <question-id> [interval-seconds]",
+].join( "\n" )
+
+class Project {
+  constructor( sRoot ){
+    this.sRoot = sRoot
+  }
+
+  sPath( sFile ){
+    return path.join( this.sRoot, sFile )
+  }
+
+  bExists( sFile ){
+    return fs.existsSync( this.sPath( sFile ))
+  }
+
+  sRead( sFile ){
+    return fs.readFileSync( this.sPath( sFile ), "utf8" )
+  }
+
+  sReadOrNull( sFile ){
+    return this.bExists( sFile ) ? this.sRead( sFile ) : null
+  }
+
+  write( sFile, sText ){
+    fs.mkdirSync( path.dirname( this.sPath( sFile )), { recursive: true })
+    const sDirTemp = this.sPath( "tmp/idd" )
+    fs.mkdirSync( sDirTemp, { recursive: true })
+    const sTemp = path.join(
+      sDirTemp,
+      path.basename( sFile ) + "." + process.pid + "." +
+        Math.random().toString( 36 ).slice( 2 ) + ".tmp"
+    )
+    fs.writeFileSync( sTemp, sText )
+    fs.renameSync( sTemp, this.sPath( sFile ))
+  }
+
+  writeJson( sFile, x ){
+    this.write( sFile, JSON.stringify( x, null, 2 ) + "\n" )
+  }
+}
+
+function aResult( nExit, sOut = "", sErr = "" ){
+  return { nExit, sOut, sErr }
+}
+
+function aUsage(){
+  return aResult( 2, "", sUsage + "\n" )
+}
+
+function aGuide(){
+  return aResult( 0, fs.readFileSync(
+    path.join( __dirname, "..", "INSTRUCTIONS.md" ), "utf8"
+  ))
+}
+
+function aViewerUrl( project, vsArg ){
+  const [ sRepository, sBranch ] = vsArg
+  if( !/^[^/\s]+\/[^/\s]+$/.test( sRepository ) ){
+    return aResult( 2, "", "repository must be <owner>/<repository>\n" )
+  }
+  if( !sBranch || /[\r\n]/.test( sBranch ) ){
+    return aResult( 2, "", "code-branch must be non-empty\n" )
+  }
+  let uViewer
+  try {
+    uViewer = new URL(
+      process.env.IDD_VIEWER_URL ||
+        "https://interrogation.dev"
+    )
+  } catch( xError ){
+    return aResult( 2, "", "IDD_VIEWER_URL is not a valid URL\n" )
+  }
+  if( ![ "http:", "https:" ].includes( uViewer.protocol ) ){
+    return aResult( 2, "", "IDD_VIEWER_URL must use HTTP or HTTPS\n" )
+  }
+  uViewer.searchParams.set( "repo", sRepository )
+  uViewer.searchParams.set( "branch", sBranch )
+  return aResult( 0, uViewer.toString() + "\n" )
+}
+
+function fzGit( sRoot, vsArgs ){
+  const aRun = spawnSync( "git", vsArgs, {
+    cwd: sRoot, encoding: "utf8", timeout: 120000,
+  })
+  if( aRun.error || aRun.status !== 0 ){
+    return {
+      error: ( aRun.error && aRun.error.message ) ||
+        ( aRun.stderr || "git " + vsArgs[ 0 ] + " failed" ).trim(),
+    }
+  }
+  return { out: aRun.stdout || "" }
+}
+
+async function fOpenEventStream(){
+  let uEvents
+  try {
+    const uViewer = new URL(
+      process.env.IDD_VIEWER_URL ||
+        "https://interrogation.dev"
+    )
+    if( ![ "http:", "https:" ].includes( uViewer.protocol )) return null
+    uEvents = new URL( "/events", uViewer )
+  } catch( xError ){
+    return null
+  }
+
+  const aStream = (async function*(){
+    const aController = new AbortController()
+    const nConnectTimeout = setTimeout( () => aController.abort(), 10000 )
+    let aResponse
+    try {
+      aResponse = await fetch( uEvents, {
+        headers: { Accept: "text/event-stream" }, signal: aController.signal,
+      })
+    } catch( xError ){
+      return
+    } finally {
+      clearTimeout( nConnectTimeout )
+    }
+    if( !aResponse.ok || !aResponse.body ) return
+
+    const aReader = aResponse.body.getReader()
+    const aDecoder = new TextDecoder()
+    let sBuffer = ""
+    try {
+      for(;;){
+        const aRead = await aReader.read()
+        if( aRead.done ) return
+        sBuffer += aDecoder.decode( aRead.value, { stream: true })
+        const vaFrame = sBuffer.split( /\r?\n\r?\n/ )
+        sBuffer = vaFrame.pop()
+        for( const sFrame of vaFrame ){
+          let sEvent = "message"
+          const vsData = []
+          for( const sLine of sFrame.split( /\r?\n/ )){
+            if( sLine.startsWith( ":" )) continue
+            const nColon = sLine.indexOf( ":" )
+            const sField = nColon < 0 ? sLine : sLine.slice( 0, nColon )
+            const sValue = nColon < 0 ? "" : sLine.slice( nColon + 1 ).replace( /^ /, "" )
+            if( sField === "event" ) sEvent = sValue
+            else if( sField === "data" ) vsData.push( sValue )
+          }
+          if( vsData.length ) yield { event: sEvent, data: vsData.join( "\n" ) }
+        }
+      }
+    } finally {
+      await aReader.cancel().catch( () => {} )
+    }
+  })()
+
+  try {
+    const aReady = await aStream.next()
+    if( aReady.done || aReady.value.event !== "ready" ){
+      await aStream.return()
+      return null
+    }
+    const aReadyData = JSON.parse( aReady.value.data )
+    if( aReadyData.push !== true ){
+      await aStream.return()
+      return { push: false }
+    }
+    return { push: true, stream: aStream }
+  } catch( xError ){
+    await aStream.return().catch( () => {} )
+    return null
+  }
+}
+
+function fzWait( sRoot, vsArg ){
+  const [ sId, sInterval = "30" ] = vsArg
+  if( !/^[0-9a-f]{64}$/.test( sId ) ){
+    return Promise.resolve( aResult( 2, "", "question-id must be a lowercase SHA-256 digest\n" ))
+  }
+  if( !/^[0-9]+$/.test( sInterval ) ||
+    Number( sInterval ) < 1 || Number( sInterval ) > 3600 ){
+    return Promise.resolve( aResult( 2, "", "interval-seconds must be from 1 to 3600\n" ))
+  }
+  const aRoot = fzGit( sRoot, [ "rev-parse", "--show-toplevel" ] )
+  const aBranch = fzGit( sRoot, [ "branch", "--show-current" ] )
+  if( aRoot.error || aBranch.error || !aBranch.out.trim().startsWith( "idd-" ) ){
+    return Promise.resolve( aResult( 1, "", "wait must run from a checked-out IDD data worktree\n" ))
+  }
+  const sDataRoot = aRoot.out.trim()
+  const sBranch = aBranch.out.trim()
+  const aStatus = fzGit( sDataRoot, [ "status", "--porcelain" ] )
+  if( aStatus.error ) return Promise.resolve( aResult( 1, "", aStatus.error + "\n" ))
+  if( aStatus.out ){
+    return Promise.resolve( aResult( 1, "", "wait requires a clean IDD data worktree\n" ))
+  }
+
+  async function faPoll(){
+    let aEvents = await fOpenEventStream()
+    for(;;){
+      for( const vsArgs of [
+        [ "fetch", "--quiet", "origin", "refs/heads/" + sBranch ],
+        [ "merge", "--ff-only", "FETCH_HEAD" ],
+      ]){
+        const aGit = fzGit( sDataRoot, vsArgs )
+        if( aGit.error ){
+          return aResult( 1, "", "idd wait: " + aGit.error + "\n" )
+        }
+      }
+      let bHasAnswer = false
+      let aAnswer = null
+      try {
+        const aQuestions = JSON.parse( fs.readFileSync(
+          path.join( sDataRoot, sFileQuestion ), "utf8"
+        ))
+        const aQuestion = Array.isArray( aQuestions )
+          ? aQuestions.find(( a ) => a && a.id === sId ) : null
+        if( !aQuestion ){
+          return aResult( 2, "", "question-id is not active on the IDD branch\n" )
+        }
+        const sAnswerFile = path.join( sDataRoot, sFileAnswer )
+        const aAnswers = fs.existsSync( sAnswerFile )
+          ? JSON.parse( fs.readFileSync( sAnswerFile, "utf8" )) : {}
+        if( !fbObject( aAnswers )){
+          return aResult( 1, "", sFileAnswer + " is not a JSON object\n" )
+        }
+        bHasAnswer = Object.prototype.hasOwnProperty.call( aAnswers, sId )
+        aAnswer = bHasAnswer ? aAnswers[ sId ] : null
+        if( bHasAnswer && ( !fbObject( aAnswer ) || !fbIsoTime( aAnswer.time ) ||
+          typeof aAnswer.choice !== "string" || typeof aAnswer.note !== "string" )){
+          return aResult( 1, "", sFileAnswer + ": malformed accepted answer for " + sId + "\n" )
+        }
+        if( bHasAnswer ){
+          const project = new Project( sDataRoot )
+          const aRecorded = fxWithLock(
+            sDataRoot,
+            () => {
+              const aPending = aParsedOrNull(
+                project.sReadOrNull( sFilePending ) || "{}"
+              )
+              if( !fbObject( aPending )){
+                return aResult( 1, "", sFilePending + " is not a JSON object\n" )
+              }
+              project.writeJson( sFilePending, {
+                ...aPending,
+                [ sId ]: {
+                  choice: aAnswer.choice, note: aAnswer.note, time: aAnswer.time,
+                },
+              })
+              return aResult( 0 )
+            },
+            () => aResult( 2, "", "the project's files are held by another run\n" )
+          )
+          if( aRecorded.nExit !== 0 ) return aRecorded
+        }
+      } catch( xError ){
+        return aResult( 1, "", "idd wait: " + xError.message + "\n" )
+      }
+      if( bHasAnswer ) return aResult( 0, JSON.stringify( aAnswer, null, 2 ) + "\n" )
+
+      if( aEvents && aEvents.push ){
+        let bInvalidated = false
+        try {
+          for(;;){
+            const aEvent = await aEvents.stream.next()
+            if( aEvent.done ) break
+            if( aEvent.value.event === "idd-update" ){
+              bInvalidated = true
+              break
+            }
+          }
+        } catch( xError ){}
+        if( bInvalidated ) continue
+        await aEvents.stream.return().catch( () => {} )
+        aEvents = null
+      } else {
+        await new Promise(( fResolve ) => setTimeout( fResolve, Number( sInterval ) * 1000 ))
+        aEvents = await fOpenEventStream()
+      }
+    }
+  }
+  return faPoll()
+}
+
+function aBranchHash( project, vsArg ){
+  const [ sRepositoryId, sFullRef ] = vsArg
+  if( !/^[1-9][0-9]*$/.test( sRepositoryId ) ){
+    return aResult( 2, "", "repository-id is not a positive decimal integer\n" )
+  }
+  if( !sFullRef.startsWith( "refs/heads/" ) || !sFullRef.slice( 11 ) ){
+    return aResult( 2, "", "full-ref is not a non-empty refs/heads branch\n" )
+  }
+  return aResult( 0, fsBranchHash( sRepositoryId, sFullRef ) + "\n" )
+}
+
+function aInit( project, vsArg ){
+  const sExisting = [ sFilePage, sFileQuestion ].find(
+    ( s ) => project.bExists( s )
+  )
+  if( sExisting ){
+    return aResult( 2, "", sExisting + " already exists\n" )
+  }
+  if( !/^[0-9a-f]{64}$/.test( vsArg[ 1 ] )){
+    return aResult( 2, "", "branch-hash is not a lowercase SHA-256 digest\n" )
+  }
+  project.writeJson( sFilePage, {
+    title: vsArg[ 0 ], url: null, branchHash: vsArg[ 1 ],
+  })
+  project.writeJson( sFileQuestion, [] )
+  return aResult( 0 )
+}
+
+function fvsProblemOf( project ){
+  return fvsProblem(
+    project.sRead( sFilePage ), project.sReadOrNull( sFileQuestion ),
+    project.sReadOrNull( sFileAnswer ), project.sReadOrNull( sFilePending ),
+    project.sReadOrNull( sFileStatus ), project.sReadOrNull( sFileHistory ),
+    project.sReadOrNull( sFileConflict ),
+    project.sReadOrNull( sFileThoughts ), project.sReadOrNull( sFileClaims )
+  )
+}
+
+function fbObject( x ){
+  return typeof x == "object" && x !== null && !Array.isArray( x )
+}
+
+function aProblem( vsProblem ){
+  return aResult( 1, vsProblem.join( "\n" ) + "\n" )
+}
+
+function aCheck( project ){
+  const vsProblem = fvsProblemOf( project )
+  return vsProblem.length ? aProblem( vsProblem ) : aResult( 0, "idd: ok\n" )
+}
+
+function aBuild( project ){
+  const vsProblem = fvsProblemOf( project )
+  if( vsProblem.length ){
+    return aProblem( vsProblem )
+  }
+  project.write(
+    sFileBuilt,
+    fsHtml(
+      JSON.parse( project.sRead( sFilePage )),
+      JSON.parse( project.sRead( sFileQuestion ))
+    )
+  )
+  return aResult( 0, sFileBuilt + "\n" )
+}
+
+function aAdd( project, vsArg, fsStdin ){
+  const aIn = aParsedOrNull( fsStdin())
+  const vsInput = fvsAddProblem( aIn )
+  if( vsInput.length ){
+    return aResult( 2, "", vsInput.join( "\n" ) + "\n" )
+  }
+  const vsProblem = fvsProblemOf( project )
+  if( vsProblem.length ){
+    return aProblem( vsProblem )
+  }
+  const vaQuestion = JSON.parse( project.sRead( sFileQuestion ))
+  const aPage = JSON.parse( project.sRead( sFilePage ))
+  const aNew = {
+    ...aIn, options: faQuestionOptions( aIn.options ),
+    branchHash: aPage.branchHash,
+  }
+  const sId = fsQuestionId( aPage.branchHash, aNew )
+  const sLegacyId = fsLegacyQuestionId( aPage.branchHash, aNew )
+  const aExisting = vaQuestion.find(( a ) => {
+    const aWithDisplayOption = { ...a, options: faQuestionOptions( a.options ) }
+    return fsQuestionId( a.branchHash, aWithDisplayOption ) === sId ||
+      fsLegacyQuestionId( a.branchHash, aWithDisplayOption ) === sLegacyId
+  })
+  if( aExisting ){
+    return aResult( 2, "", "question already exists:\n" +
+      JSON.stringify( aExisting, null, 2 ) + "\n" )
+  }
+  project.writeJson(
+    sFileQuestion,
+    [ ...vaQuestion, {
+      id: sId, branchHash: aPage.branchHash,
+      title: aNew.title, body: aNew.body, options: aNew.options,
+      createdAt: new Date().toISOString(),
+    } ]
+  )
+  return aResult( 0, sId + "\n" )
+}
+
+function aArchive( project, vsArg ){
+  const [ sId, sReplacementId ] = vsArg
+  if( !/^[0-9a-f]{64}$/.test( sId ) || !/^[0-9a-f]{64}$/.test( sReplacementId )){
+    return aResult( 2, "", "question ids must be lowercase SHA-256 digests\n" )
+  }
+  if( sId === sReplacementId ){
+    return aResult( 2, "", "question cannot replace itself\n" )
+  }
+  const vsProblem = fvsProblemOf( project )
+  if( vsProblem.length ) return aProblem( vsProblem )
+  const vaQuestion = JSON.parse( project.sRead( sFileQuestion ))
+  const nQuestion = vaQuestion.findIndex(( a ) => a.id === sId )
+  if( nQuestion < 0 ){
+    return aResult( 2, "", "question-id is not active\n" )
+  }
+  if( !vaQuestion.some(( a ) => a.id === sReplacementId )){
+    return aResult( 2, "", "replacement-id is not active\n" )
+  }
+  const vaHistory = project.sReadOrNull( sFileHistory ) === null
+    ? [] : JSON.parse( project.sRead( sFileHistory ))
+  const aQuestion = vaQuestion[ nQuestion ]
+  project.writeJson( sFileHistory, [ ...vaHistory, {
+    questionId: sId,
+    question: aQuestion,
+    replacedBy: sReplacementId,
+    time: new Date().toISOString(),
+  } ])
+  project.writeJson( sFileQuestion,
+    vaQuestion.filter(( a ) => a.id !== sId ))
+  return aResult( 0 )
+}
+
+function fbHoldsQuestion( project ){
+  try {
+    const va = JSON.parse( project.sReadOrNull( sFileQuestion ))
+    return Array.isArray( va ) && va.length > 0
+  } catch( xError ){
+    return false
+  }
+}
+
+function aParsedOrNull( sText ){
+  try {
+    return JSON.parse( sText )
+  } catch( xError ){
+    return null
+  }
+}
+
+function fsAnswerProblem( aIn, aQuestion ){
+  if( !aQuestion ){
+    return "the id is the id of no question of " + sFileQuestion
+  }
+  if( !fbObject( aIn )){
+    return "stdin does not hold a JSON object"
+  }
+  const vaOption = faQuestionOptions( aQuestion.options )
+  if( typeof aIn.sChoice != "string" || ( aIn.sChoice !== "" &&
+    !vaOption.some(( a ) => a && a.key === aIn.sChoice ))){
+    return "sChoice is neither \"\" nor a key of the question's options"
+  }
+  if( typeof aIn.sNote != "string" ){
+    return "sNote is not a string"
+  }
+  if( !fbIsoTime( aIn.dtm )){
+    return "dtm is not an ISO 8601 time"
+  }
+  return null
+}
+
+function aAnswer( project, vsArg, fsStdin ){
+  const sId = vsArg[ 0 ]
+  const vaQuestion = aParsedOrNull( project.sReadOrNull( sFileQuestion ))
+  const aQuestion = Array.isArray( vaQuestion )
+    ? vaQuestion.find(( a ) => fbObject( a ) && a.id === sId ) : null
+  const aIn = aParsedOrNull( fsStdin())
+  const sProblem = fsAnswerProblem( aIn, aQuestion )
+  if( sProblem ){
+    return aResult( 2, "", sProblem + "\n" )
+  }
+  const sTextAnswer = project.sReadOrNull( sFileAnswer )
+  const aAnswerFile = sTextAnswer === null ? {} : aParsedOrNull( sTextAnswer )
+  if( !fbObject( aAnswerFile )){
+    return aResult( 2, "", sFileAnswer + " is not a JSON object\n" )
+  }
+  const aOld = Object.prototype.hasOwnProperty.call( aAnswerFile, sId )
+    ? aAnswerFile[ sId ] : null
+  if( Object.prototype.hasOwnProperty.call( aAnswerFile, sId )){
+    return aResult( 2, "", "answer already accepted for " + sId + ":\n" +
+      JSON.stringify( aOld, null, 2 ) + "\n" )
+  }
+  const sTextPending = project.sReadOrNull( sFilePending )
+  const aPending = sTextPending === null ? {} : aParsedOrNull( sTextPending )
+  if( !fbObject( aPending )){
+    return aResult( 2, "", sFilePending + " is not a JSON object\n" )
+  }
+  const aEntry = {
+    choice: aIn.sChoice, note: aIn.sNote, time: aIn.dtm,
+  }
+  project.writeJson( sFileAnswer, { ...aAnswerFile, [ sId ]: aEntry })
+  project.writeJson(
+    sFilePending,
+    { ...aPending, [ sId ]: aEntry }
+  )
+  return aResult( 0 )
+}
+
+function aClearPending( project, vsArg ){
+  const [ sId, sTime ] = vsArg
+  const aQuestionOfId = faQuestionOfId(
+    project.sReadOrNull( sFileQuestion ), project.sReadOrNull( sFileHistory )
+  )
+  const bHasQuestion = Object.prototype.hasOwnProperty.call( aQuestionOfId, sId )
+  if( !bHasQuestion ){
+    return aResult( 2, "", "the id is the id of no question of "
+      + sFileQuestion + "\n" )
+  }
+  if( !fbIsoTime( sTime )){
+    return aResult( 2, "", "time is not an ISO 8601 time\n" )
+  }
+  const sTextPending = project.sReadOrNull( sFilePending )
+  if( sTextPending === null ){
+    return aResult( 0 )
+  }
+  const aPending = aParsedOrNull( sTextPending )
+  if( !fbObject( aPending )){
+    return aResult( 1, sFilePending + ": not a JSON object\n" )
+  }
+  const aCurrent = aPending[ sId ]
+  if( !fbObject( aCurrent ) || aCurrent.time !== sTime ){
+    return aResult( 0 )
+  }
+  const aNext = { ...aPending }
+  delete aNext[ sId ]
+  project.writeJson( sFilePending, aNext )
+  return aResult( 0 )
+}
+
+function aStatus( project, vsArg ){
+  const [ sSessionId, sState ] = vsArg
+  if( !/^[A-Za-z0-9._:-]{1,128}$/.test( sSessionId )){
+    return aResult( 2, "", "session-id must be 1 to 128 ASCII letters, digits, periods, underscores, colons or hyphens\n" )
+  }
+  if( ![ "blocked", "working", "clear" ].includes( sState )){
+    return aResult( 2, "", "state must be blocked, working or clear\n" )
+  }
+  const sTextStatus = project.sReadOrNull( sFileStatus )
+  const aStatus = sTextStatus === null ? {} : aParsedOrNull( sTextStatus )
+  const vsProblem = fvsStatusProblem( aStatus )
+  if( vsProblem.length ){
+    return aResult( 1, "", sFileStatus + ": " + vsProblem.join( "; " ) + "\n" )
+  }
+  if( sState === "clear" ){
+    if( !Object.prototype.hasOwnProperty.call( aStatus, sSessionId )){
+      return aResult( 0 )
+    }
+    delete aStatus[ sSessionId ]
+  } else {
+    aStatus[ sSessionId ] = {
+      blocked: sState === "blocked",
+      updatedAt: new Date().toISOString(),
+    }
+  }
+  project.writeJson( sFileStatus, aStatus )
+  return aResult( 0 )
+}
+
+function aWorkClaim( project, vsArg, bRelease ){
+  const [ sKind, sItemId, sSessionId ] = vsArg
+  if( ![ "answer", "thought", "conflict" ].includes( sKind ) ||
+    !/^[0-9a-f]{64}$/.test( sItemId ) ||
+    !/^[A-Za-z0-9._:-]{1,128}$/.test( sSessionId )){
+    return aResult( 2, "", "claim kind, item id or session id is invalid\n" )
+  }
+  const vsProblem = fvsProblemOf( project )
+  if( vsProblem.length ) return aProblem( vsProblem )
+  const sTextClaims = project.sReadOrNull( sFileClaims )
+  const aClaims = sTextClaims === null ? {} : aParsedOrNull( sTextClaims )
+  if( !fbObject( aClaims )) return aResult( 1, "", sFileClaims + ": not a JSON object\n" )
+  const sKey = sKind + ":" + sItemId
+  const aExisting = aClaims[ sKey ]
+  if( bRelease ){
+    if( !aExisting ) return aResult( 0 )
+    if( aExisting.sessionId !== sSessionId ){
+      return aResult( 1, "", "work item is claimed by " + aExisting.sessionId + "\n" )
+    }
+    delete aClaims[ sKey ]
+  } else {
+    if( aExisting ){
+      if( aExisting.sessionId === sSessionId ) return aResult( 0 )
+      return aResult( 1, "", "work item is claimed by " + aExisting.sessionId + "\n" )
+    }
+    const aAvailableIds = sKind === "answer"
+      ? faQuestionOfId( project.sReadOrNull( sFileQuestion ), project.sReadOrNull( sFileHistory ))
+      : aArrayIds( project.sReadOrNull( sKind === "thought" ? sFileThoughts : sFileConflict ))
+    if( !( sItemId in aAvailableIds ) && !aAvailableIds.has?.( sItemId )){
+      return aResult( 2, "", "item id is not present in its source file\n" )
+    }
+    aClaims[ sKey ] = { sessionId: sSessionId, claimedAt: new Date().toISOString() }
+  }
+  project.writeJson( sFileClaims, aClaims )
+  return aResult( 0 )
+}
+
+function aArrayIds( sText ){
+  try {
+    const vaData = JSON.parse( sText || "[]" )
+    return new Set( Array.isArray( vaData ) ? vaData.map(( a ) => a && a.id ) : [] )
+  } catch( xError ){ return new Set() }
+}
+
+function aClaim( project, vsArg ){
+  return aWorkClaim( project, vsArg, false )
+}
+
+function aRelease( project, vsArg ){
+  return aWorkClaim( project, vsArg, true )
+}
+
+function aCount( project, vsArg ){
+  let bNoSync = false
+  let sType = null
+  for( let n = 0; n < vsArg.length; n++ ){
+    if( vsArg[ n ] === "--nosync" && !bNoSync ){
+      bNoSync = true
+    } else if( vsArg[ n ] === "--type" && sType === null && n + 1 < vsArg.length ){
+      sType = vsArg[ ++n ]
+    } else {
+      return aUsage()
+    }
+  }
+  const mType = {
+    c: "conflicts", conflicts: "conflicts",
+    u: "unanswered", unanswered: "unanswered",
+    a: "answered", answered: "answered",
+    s: "superseded", superseded: "superseded",
+  }
+  if( sType !== null && !Object.prototype.hasOwnProperty.call( mType, sType )){
+    return aUsage()
+  }
+
+  if( !bNoSync ){
+    const aRoot = fzGit( project.sRoot, [ "rev-parse", "--show-toplevel" ] )
+    const aBranch = fzGit( project.sRoot, [ "branch", "--show-current" ] )
+    if( aRoot.error || aBranch.error || !/^idd-.+/.test( aBranch.out.trim() )){
+      return aResult( 1, "", "idd count must run from a checked-out IDD data worktree\n" )
+    }
+    const sDataRoot = aRoot.out.trim()
+    const aStatus = fzGit( sDataRoot, [ "status", "--porcelain" ] )
+    if( aStatus.error ) return aResult( 1, "", aStatus.error + "\n" )
+    if( aStatus.out ){
+      return aResult( 1, "", "idd count requires a clean IDD data worktree before sync\n" )
+    }
+    for( const vsArgs of [
+      [ "fetch", "--quiet", "origin", "refs/heads/" + aBranch.out.trim() ],
+      [ "merge", "--ff-only", "FETCH_HEAD" ],
+    ]){
+      const aGit = fzGit( sDataRoot, vsArgs )
+      if( aGit.error ) return aResult( 1, "", "idd count: " + aGit.error + "\n" )
+    }
+  }
+
+  const vsProblem = fvsProblemOf( project )
+  if( vsProblem.length ){
+    return aResult( 1, "", vsProblem.join( "\n" ) + "\n" )
+  }
+  let vaQuestion, aAnswers, vaConflict, vaHistory
+  try {
+    vaQuestion = JSON.parse( project.sRead( sFileQuestion ))
+    aAnswers = project.sReadOrNull( sFileAnswer ) === null
+      ? {} : JSON.parse( project.sRead( sFileAnswer ))
+    vaConflict = project.sReadOrNull( sFileConflict ) === null
+      ? [] : JSON.parse( project.sRead( sFileConflict ))
+    vaHistory = project.sReadOrNull( sFileHistory ) === null
+      ? [] : JSON.parse( project.sRead( sFileHistory ))
+  } catch( xError ){
+    return aResult( 1, "", "idd count: " + xError.message + "\n" )
+  }
+  const aCounts = { conflicts: 0, unanswered: 0, answered: 0, superseded: vaHistory.length }
+  for( const aQuestion of vaQuestion ){
+    const aAccepted = aAnswers[ aQuestion.id ]
+    const vaRejected = vaConflict.filter(( a ) => a.questionId === aQuestion.id )
+    const bConflict = vaRejected.some(( a ) => !aAccepted ||
+      a.choice !== aAccepted.choice || a.note !== aAccepted.note )
+    const bAnswered = !!aAccepted && !!( aAccepted.choice || aAccepted.note.trim())
+    if( bConflict ) aCounts.conflicts++
+    else if( bAnswered ) aCounts.answered++
+    else aCounts.unanswered++
+  }
+  if( sType !== null ) return aResult( 0, String( aCounts[ mType[ sType ]] ) + "\n" )
+  return aResult( 0, Object.entries( aCounts ).map(
+    ([ sName, nCount ]) => sName + ": " + nCount
+  ).join( "\n" ) + "\n" )
+}
+
+function aThoughts( project, vsArg ){
+  const bNoSync = vsArg.length === 1 && vsArg[ 0 ] === "--nosync"
+  if( vsArg.length > 1 || ( vsArg.length === 1 && !bNoSync )){
+    return aUsage()
+  }
+  if( !bNoSync ){
+    const aRoot = fzGit( project.sRoot, [ "rev-parse", "--show-toplevel" ] )
+    const aBranch = fzGit( project.sRoot, [ "branch", "--show-current" ] )
+    if( aRoot.error || aBranch.error ||
+      !/^idd-.+/.test( aBranch.out.trim() )){
+      return aResult(
+        1, "", "idd thoughts must run from a checked-out IDD data worktree\n"
+      )
+    }
+    const sDataRoot = aRoot.out.trim()
+    const sBranch = aBranch.out.trim()
+    const aStatus = fzGit( sDataRoot, [ "status", "--porcelain" ] )
+    if( aStatus.error ) return aResult( 1, "", aStatus.error + "\n" )
+    if( aStatus.out ){
+      return aResult(
+        1, "", "idd thoughts requires a clean IDD data worktree before sync\n"
+      )
+    }
+    for( const vsArgs of [
+      [ "fetch", "--quiet", "origin", "refs/heads/" + sBranch ],
+      [ "merge", "--ff-only", "FETCH_HEAD" ],
+    ] ){
+      const aGit = fzGit( sDataRoot, vsArgs )
+      if( aGit.error ){
+        return aResult( 1, "", "idd thoughts: " + aGit.error + "\n" )
+      }
+    }
+  }
+
+  const vsProblem = fvsProblemOf( project )
+  if( vsProblem.length ) return aProblem( vsProblem )
+  const sTextThoughts = project.sReadOrNull( sFileThoughts )
+  const vaThought = sTextThoughts === null ? [] : JSON.parse( sTextThoughts )
+  if( !vaThought.length ) return aResult( 0, "idd: no thoughts\n" )
+  const sOut = vaThought.map(( aThought ) =>
+    aThought.id + " · " + aThought.createdAt + "\n" + aThought.text
+  ).join( "\n\n" )
+  return aResult( 0, sOut + "\n" )
+}
+
+function aImport( project, vsArg ){
+  const sPage = vsArg[ 0 ]
+  if( fbHoldsQuestion( project )){
+    return aResult( 2, "", sFileQuestion + " already holds questions\n" )
+  }
+  let vaQuestion
+  try {
+    const aPage = JSON.parse( project.sRead( sFilePage ))
+    vaQuestion = fvaQuestionFromPage(
+      fs.readFileSync( path.resolve( project.sRoot, sPage ), "utf8" )
+    ).map(( a ) => ({
+      ...a,
+      branchHash: aPage.branchHash,
+      id: fsQuestionId( aPage.branchHash, a ),
+      createdAt: new Date().toISOString(),
+    }))
+  } catch( xError ){
+    return aResult( 2, "", sPage + ": " + xError.message + "\n" )
+  }
+  project.writeJson( sFileQuestion, vaQuestion )
+  return aResult( 0 )
+}
+
+const aSpec = {
+  "guide": { cArg: 0, fa: aGuide, bNeedsPage: false, bWrites: false },
+  "viewer-url": { cArg: 2, fa: aViewerUrl, bNeedsPage: false, bWrites: false },
+  "init": { cArg: 2, fa: aInit, bNeedsPage: false, bWrites: true },
+  "branch-hash": { cArg: 2, fa: aBranchHash, bNeedsPage: false, bWrites: false },
+  "check": { cArg: 0, fa: aCheck, bNeedsPage: true, bWrites: false, bLocks: true },
+  "build": { cArg: 0, fa: aBuild, bNeedsPage: true, bWrites: false, bLocks: true },
+  "add": { cArg: 0, fa: aAdd, bNeedsPage: true, bWrites: true },
+  "archive": { cArg: 2, fa: aArchive, bNeedsPage: true, bWrites: true },
+  "import": { cArg: 1, fa: aImport, bNeedsPage: false, bWrites: true },
+  "answer": { cArg: 1, fa: aAnswer, bNeedsPage: true, bWrites: true },
+  "clear-pending": { cArg: 2, fa: aClearPending, bNeedsPage: true, bWrites: true },
+  "status": { cArg: 2, fa: aStatus, bNeedsPage: true, bWrites: true },
+  "claim": { cArg: 3, fa: aClaim, bNeedsPage: true, bWrites: true },
+  "release": { cArg: 3, fa: aRelease, bNeedsPage: true, bWrites: true },
+}
+
+function aRun( sRoot, vsArg, fsStdin = () => "" ){
+  const [ sCommand, ...vsRest ] = vsArg
+  if( sCommand === "wait" && vsRest.length >= 1 && vsRest.length <= 2 ){
+    return fzWait( sRoot, vsRest )
+  }
+  if( sCommand === "count" ){
+    const project = new Project( sRoot )
+    if( !project.bExists( sFilePage )){
+      return aResult( 2, "", sFilePage + " does not exist\n" )
+    }
+    return aCount( project, vsRest )
+  }
+  if( sCommand === "thoughts" ){
+    const project = new Project( sRoot )
+    if( !project.bExists( sFilePage )){
+      return aResult( 2, "", sFilePage + " does not exist\n" )
+    }
+    return aThoughts( project, vsRest )
+  }
+  const aCommand = Object.prototype.hasOwnProperty.call( aSpec, sCommand )
+    ? aSpec[ sCommand ] : null
+  if( !aCommand || vsRest.length != aCommand.cArg ){
+    return aUsage()
+  }
+  const project = new Project( sRoot )
+  if( aCommand.bNeedsPage && !project.bExists( sFilePage )){
+    return aResult( 2, "", sFilePage + " does not exist\n" )
+  }
+  if( !aCommand.bWrites && !aCommand.bLocks ){
+    return aCommand.fa( project, vsRest, fsStdin )
+  }
+  return fxWithLock(
+    sRoot,
+    () => aCommand.fa( project, vsRest, fsStdin ),
+    () => aResult(
+      2, "", "the project's files are held by another run\n"
+    )
+  )
+}
+
+module.exports = { aRun }