@hippo-digital/hippocampus 1.0.0-rc.1

package/scripts/sync-project-context.js

@@ -0,0 +1,236 @@
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+const readline = require('readline')
+const { spawnSync } = require('child_process')
+const { createContextOrExit } = require('../lib/context')
+const ctx = createContextOrExit()
+const { projectInboxDir, projectImportsDir, manifestsDir, projectManifestPath } = ctx.paths
+
+const supportedExtensions = new Set(['.pptx', '.pdf'])
+
+async function main () {
+  const args = parseArgs(process.argv.slice(2))
+  const sourceDir = path.resolve(args.source || projectInboxDir)
+
+  fs.mkdirSync(sourceDir, { recursive: true })
+  fs.mkdirSync(projectImportsDir, { recursive: true })
+  fs.mkdirSync(manifestsDir, { recursive: true })
+
+  const manifest = readManifest()
+  const files = listFiles(sourceDir)
+  const supported = files.filter((file) => supportedExtensions.has(path.extname(file).toLowerCase()))
+  const unsupported = files.filter((file) => !supportedExtensions.has(path.extname(file).toLowerCase()))
+  const knownHashes = new Map(manifest.artefacts.map((item) => [item.sha256, item]))
+  const existingIds = new Set(manifest.artefacts.map((item) => item.id))
+  const imported = []
+  const alreadyKnown = []
+
+  for (const file of supported) {
+    const sha256 = hashFile(file)
+    const known = knownHashes.get(sha256)
+    if (known) {
+      known.sourcePath = relative(file)
+      alreadyKnown.push(known)
+      continue
+    }
+
+    const id = uniqueId(kebab(path.basename(file, path.extname(file))), existingIds)
+    existingIds.add(id)
+    const draftPath = path.join(projectImportsDir, `${id}.json`)
+    const reviewPath = path.join(projectImportsDir, `${id}.review.md`)
+
+    if (!args.dryRun) {
+      const result = spawnSync(process.execPath, [
+        path.join(ctx.package.scriptsDir, 'import-project-context.js'),
+        `--document=${file}`,
+        `--context-id=${id}`,
+        `--title=${path.basename(file, path.extname(file))}`,
+        `--output-dir=${projectImportsDir}`
+      ], {
+        cwd: ctx.root,
+        stdio: 'inherit'
+      })
+
+      if (result.status !== 0) {
+        manifest.artefacts.push({
+          id,
+          sourcePath: relative(file),
+          sha256,
+          type: path.extname(file).slice(1).toLowerCase(),
+          status: 'failed',
+          importedAt: new Date().toISOString()
+        })
+        writeManifest(manifest)
+        throw new Error(`Import failed for ${relative(file)}`)
+      }
+    }
+
+    const item = {
+      id,
+      sourcePath: relative(file),
+      sha256,
+      type: path.extname(file).slice(1).toLowerCase(),
+      status: args.dryRun ? 'new' : 'imported',
+      draftPath: relative(draftPath),
+      reviewPath: relative(reviewPath),
+      importedAt: args.dryRun ? null : new Date().toISOString(),
+      promotedAt: null
+    }
+    manifest.artefacts.push(item)
+    imported.push(item)
+  }
+
+  const promotable = manifest.artefacts.filter((item) => {
+    if (item.status === 'promoted') return false
+    if (!item.draftPath) return false
+    return fs.existsSync(path.join(ctx.root, item.draftPath))
+  })
+
+  manifest.updatedAt = new Date().toISOString()
+  if (!args.dryRun) writeManifest(manifest)
+
+  report({ sourceDir, files, supported, unsupported, imported, alreadyKnown, promotable, dryRun: args.dryRun })
+
+  if (args.dryRun || args.noPromote || !promotable.length) return
+
+  const shouldPromote = args.yes || await confirm('Promote imported, unpromoted project context drafts now?')
+  if (!shouldPromote) return
+
+  for (const item of promotable) {
+    const result = spawnSync('npm', [
+      'run',
+      'promote:project-context-draft',
+      '--',
+      `--draft=${item.draftPath}`
+    ], {
+      cwd: ctx.root,
+      stdio: 'inherit'
+    })
+
+    if (result.status !== 0) {
+      item.status = 'failed'
+      item.failedAt = new Date().toISOString()
+      writeManifest(manifest)
+      throw new Error(`Promotion failed for ${item.draftPath}`)
+    }
+
+    item.status = 'promoted'
+    item.promotedAt = new Date().toISOString()
+  }
+
+  manifest.updatedAt = new Date().toISOString()
+  writeManifest(manifest)
+  console.log(`Promotion manifest updated at ${relative(projectManifestPath)}`)
+}
+
+function parseArgs (args) {
+  const parsed = {}
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (!arg.startsWith('--')) continue
+    const [rawKey, value] = arg.slice(2).split('=', 2)
+    const key = camelCase(rawKey)
+    if (value !== undefined) {
+      parsed[key] = value
+    } else if (args[index + 1] && !args[index + 1].startsWith('--')) {
+      parsed[key] = args[index + 1]
+      index++
+    } else {
+      parsed[key] = true
+    }
+  }
+  return parsed
+}
+
+function readManifest () {
+  if (!fs.existsSync(projectManifestPath)) {
+    return {
+      version: 1,
+      updatedAt: null,
+      artefacts: []
+    }
+  }
+  return JSON.parse(fs.readFileSync(projectManifestPath, 'utf8'))
+}
+
+function writeManifest (manifest) {
+  fs.writeFileSync(projectManifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
+function listFiles (dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name.startsWith('.')) return []
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) return listFiles(fullPath)
+    if (entry.isFile()) return [fullPath]
+    return []
+  })
+}
+
+function hashFile (file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')
+}
+
+function report ({ sourceDir, files, supported, unsupported, imported, alreadyKnown, promotable, dryRun }) {
+  console.log(`Project context inbox: ${relative(sourceDir)}`)
+  console.log(`Files found: ${files.length}`)
+  console.log(`Supported files: ${supported.length}`)
+  console.log(`New imports${dryRun ? ' found' : ' created'}: ${imported.length}`)
+  console.log(`Already known: ${alreadyKnown.length}`)
+  console.log(`Unsupported files: ${unsupported.length}`)
+  console.log(`Unpromoted drafts: ${promotable.length}`)
+
+  if (imported.length) {
+    console.log('New project context drafts:')
+    for (const item of imported) console.log(`- ${item.id}: ${item.reviewPath}`)
+  }
+
+  if (promotable.length) {
+    console.log('Promotable drafts:')
+    for (const item of promotable) console.log(`- ${item.id}: ${item.draftPath}`)
+  }
+}
+
+function confirm (question) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return Promise.resolve(false)
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  })
+
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close()
+      resolve(/^y(es)?$/i.test(answer.trim()))
+    })
+  })
+}
+
+function uniqueId (baseId, existingIds) {
+  if (!existingIds.has(baseId)) return baseId
+  let index = 2
+  while (existingIds.has(`${baseId}-${index}`)) index++
+  return `${baseId}-${index}`
+}
+
+function kebab (value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function camelCase (value) {
+  return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
+}
+
+function relative (file) {
+  return path.relative(ctx.root, file)
+}
+
+main().catch((error) => {
+  console.error(error.message)
+  process.exit(1)
+})

package/scripts/sync-research-artefacts.js

@@ -0,0 +1,294 @@
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+const readline = require('readline')
+const { spawnSync } = require('child_process')
+const { createContextOrExit } = require('../lib/context')
+const ctx = createContextOrExit()
+const { researchInboxDir, researchImportsDir, researchManifestsDir, researchManifestPath } = ctx.paths
+const { extensions } = require('./lib/artefact-text')
+
+// Word and Excel are where most of this team's research actually lives:
+// discussion guides, scenario maps, personas, insight and design-action
+// trackers. Limiting the inbox to decks and PDFs skipped most of the corpus.
+const supportedExtensions = new Set(Object.keys(extensions))
+
+async function main () {
+  const args = parseArgs(process.argv.slice(2))
+  const sourceDir = path.resolve(args.source || researchInboxDir)
+  const date = args.date || new Date().toISOString().slice(0, 10)
+
+  fs.mkdirSync(sourceDir, { recursive: true })
+  fs.mkdirSync(researchImportsDir, { recursive: true })
+  fs.mkdirSync(researchManifestsDir, { recursive: true })
+
+  const manifest = readManifest()
+  const files = listFiles(sourceDir)
+  const supported = files.filter((file) => supportedExtensions.has(path.extname(file).toLowerCase()))
+  const unsupported = files.filter((file) => !supportedExtensions.has(path.extname(file).toLowerCase()))
+  const knownHashes = new Map(manifest.artefacts.map((item) => [item.sha256, item]))
+  const existingIds = new Set(manifest.artefacts.map((item) => item.id))
+  const imported = []
+  const alreadyKnown = []
+
+  for (const file of supported) {
+    const sha256 = hashFile(file)
+    const known = knownHashes.get(sha256)
+    if (known) {
+      known.sourcePath = relative(file)
+      alreadyKnown.push(known)
+      continue
+    }
+
+    const id = uniqueId(kebab(path.basename(file, path.extname(file))), existingIds)
+    existingIds.add(id)
+    const round = roundFor(file, sourceDir, args)
+    const draftPath = path.join(researchImportsDir, `${id}.json`)
+    const reviewPath = path.join(researchImportsDir, `${id}.review.md`)
+
+    if (!args.dryRun) {
+      const result = spawnSync(process.execPath, [
+        path.join(ctx.package.scriptsDir, 'import-research-deck.js'),
+        `--deck=${file}`,
+        `--round-id=${round.id}`,
+        `--artefact-id=${id}`,
+        `--title=${round.title}`,
+        `--date=${dateFor(file, date) || date}`,
+        `--date-derived=${dateFor(file, null) ? 'true' : 'false'}`,
+        `--output-dir=${researchImportsDir}`
+      ], {
+        cwd: ctx.root,
+        stdio: 'inherit'
+      })
+
+      if (result.status !== 0) {
+        manifest.artefacts.push({
+          id,
+          sourcePath: relative(file),
+          sha256,
+          type: path.extname(file).slice(1).toLowerCase(),
+          status: 'failed',
+          importedAt: new Date().toISOString()
+        })
+        writeManifest(manifest)
+        throw new Error(`Import failed for ${relative(file)}`)
+      }
+    }
+
+    const item = {
+      id,
+      roundId: round.id,
+      sourcePath: relative(file),
+      sha256,
+      type: path.extname(file).slice(1).toLowerCase(),
+      status: args.dryRun ? 'new' : 'imported',
+      draftPath: relative(draftPath),
+      reviewPath: relative(reviewPath),
+      importedAt: args.dryRun ? null : new Date().toISOString(),
+      promotedAt: null
+    }
+    manifest.artefacts.push(item)
+    imported.push(item)
+  }
+
+  const promotable = manifest.artefacts.filter((item) => {
+    if (item.status === 'promoted') return false
+    if (!item.draftPath) return false
+    return fs.existsSync(path.join(ctx.root, item.draftPath))
+  })
+
+  manifest.updatedAt = new Date().toISOString()
+  if (!args.dryRun) writeManifest(manifest)
+
+  report({ sourceDir, files, supported, unsupported, imported, alreadyKnown, promotable, dryRun: args.dryRun })
+
+  if (args.dryRun || args.noPromote || !promotable.length) return
+
+  const shouldPromote = args.yes || await confirm('Promote imported, unpromoted research drafts now?')
+  if (!shouldPromote) return
+
+  for (const item of promotable) {
+    const result = spawnSync('npm', [
+      'run',
+      'promote:research-draft',
+      '--',
+      `--draft=${item.draftPath}`
+    ], {
+      cwd: ctx.root,
+      stdio: 'inherit'
+    })
+
+    if (result.status !== 0) {
+      item.status = 'failed'
+      item.failedAt = new Date().toISOString()
+      writeManifest(manifest)
+      throw new Error(`Promotion failed for ${item.draftPath}`)
+    }
+
+    item.status = 'promoted'
+    item.promotedAt = new Date().toISOString()
+  }
+
+  manifest.updatedAt = new Date().toISOString()
+  writeManifest(manifest)
+  console.log(`Promotion manifest updated at ${relative(researchManifestPath)}`)
+}
+
+/**
+ * A research round is a piece of fieldwork, not a file. Twelve scenario maps from
+ * round 16 belong to one round; naming the round after each file would invent
+ * twelve of them.
+ *
+ * This team already encodes the round in the folder name - "Round 16 - Patient
+ * Search in FHIR" - so that is what is read, with an explicit --round-id winning
+ * and the filename left as the last resort for a loose artefact.
+ */
+function roundFor (file, sourceDir, args) {
+  if (args.roundId) return { id: kebab(args.roundId), title: args.roundTitle || args.roundId }
+
+  // The round number is the stable key. Two artefacts filed at different depths,
+  // or one loose file that only mentions "Round 12" in its name, still land in the
+  // same round rather than inventing a second one.
+  const segments = path.relative(sourceDir, file).split(path.sep)
+  const folder = segments.slice(0, -1).find((segment) => /^round\s*\d+\b/i.test(segment))
+  if (folder) {
+    const number = folder.match(/^round\s*(\d+)/i)[1]
+    return { id: `round-${number}`, title: folder.replace(/\s*[-\u2013]\s*/, ' \u2013 ').trim() }
+  }
+
+  const named = path.basename(file, path.extname(file)).match(/\bround\s*(\d+)\b/i)
+  if (named) return { id: `round-${named[1]}`, title: `Round ${named[1]}` }
+
+  const base = path.basename(file, path.extname(file))
+  return { id: kebab(base), title: base }
+}
+
+/**
+ * Copying a shared drive resets every modification date, so file mtimes are not
+ * evidence dates. A date written into the file or folder name is, and a research
+ * round has to carry a real one.
+ */
+function dateFor (file, fallback) {
+  const haystack = file.replace(/\\/g, '/')
+  const iso = haystack.match(/(20\d{2})[-_](0[1-9]|1[0-2])[-_](0[1-9]|[12]\d|3[01])/)
+  if (iso) return `${iso[1]}-${iso[2]}-${iso[3]}`
+
+  const compact = haystack.match(/\b(20\d{2})(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\b/)
+  if (compact) return `${compact[1]}-${compact[2]}-${compact[3]}`
+
+  const month = haystack.match(/\b(20\d{2})[-_](0[1-9]|1[0-2])\b/)
+  if (month) return `${month[1]}-${month[2]}-01`
+
+  return fallback
+}
+
+function parseArgs (args) {
+  const parsed = {}
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (!arg.startsWith('--')) continue
+    const [rawKey, value] = arg.slice(2).split('=', 2)
+    const key = camelCase(rawKey)
+    if (value !== undefined) {
+      parsed[key] = value
+    } else if (args[index + 1] && !args[index + 1].startsWith('--')) {
+      parsed[key] = args[index + 1]
+      index++
+    } else {
+      parsed[key] = true
+    }
+  }
+  return parsed
+}
+
+function readManifest () {
+  if (!fs.existsSync(researchManifestPath)) {
+    return {
+      version: 1,
+      updatedAt: null,
+      artefacts: []
+    }
+  }
+  return JSON.parse(fs.readFileSync(researchManifestPath, 'utf8'))
+}
+
+function writeManifest (manifest) {
+  fs.writeFileSync(researchManifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
+function listFiles (dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name.startsWith('.')) return []
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) return listFiles(fullPath)
+    if (entry.isFile()) return [fullPath]
+    return []
+  })
+}
+
+function hashFile (file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')
+}
+
+function report ({ sourceDir, files, supported, unsupported, imported, alreadyKnown, promotable, dryRun }) {
+  console.log(`Research inbox: ${relative(sourceDir)}`)
+  console.log(`Files found: ${files.length}`)
+  console.log(`Supported files: ${supported.length}`)
+  console.log(`New imports${dryRun ? ' found' : ' created'}: ${imported.length}`)
+  console.log(`Already known: ${alreadyKnown.length}`)
+  console.log(`Unsupported files: ${unsupported.length}`)
+  console.log(`Unpromoted drafts: ${promotable.length}`)
+
+  if (imported.length) {
+    console.log('New research drafts:')
+    for (const item of imported) console.log(`- ${item.id}: ${item.reviewPath}`)
+  }
+
+  if (promotable.length) {
+    console.log('Promotable drafts:')
+    for (const item of promotable) console.log(`- ${item.id}: ${item.draftPath}`)
+  }
+}
+
+function confirm (question) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return Promise.resolve(false)
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  })
+
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close()
+      resolve(/^y(es)?$/i.test(answer.trim()))
+    })
+  })
+}
+
+function uniqueId (baseId, existingIds) {
+  if (!existingIds.has(baseId)) return baseId
+  let index = 2
+  while (existingIds.has(`${baseId}-${index}`)) index++
+  return `${baseId}-${index}`
+}
+
+function kebab (value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function camelCase (value) {
+  return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
+}
+
+function relative (file) {
+  return path.relative(ctx.root, file)
+}
+
+main().catch((error) => {
+  console.error(error.message)
+  process.exit(1)
+})