@aipoch/open-science 0.0.0-stage → 1.0.2

package/installation-startup.cjs

@@ -0,0 +1,205 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type, @typescript-eslint/no-require-imports */
+// Keep this bootstrap free of application/native addon imports. It runs before spawning the backend.
+const { createHash, randomUUID } = require('node:crypto')
+const {
+  mkdirSync,
+  existsSync,
+  realpathSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  rmSync
+} = require('node:fs')
+const { dirname, join, resolve } = require('node:path')
+const { homedir } = require('node:os')
+
+function installationRootForEntry(entryPath) {
+  // AppImage mount directories change on every launch; coordinate the stable outer image.
+  if (
+    process.platform === 'linux' &&
+    process.env.APPIMAGE &&
+    process.env.APPDIR &&
+    resolve(entryPath).startsWith(resolve(process.env.APPDIR) + '/')
+  )
+    return existsSync(process.env.APPIMAGE)
+      ? realpathSync(process.env.APPIMAGE)
+      : resolve(process.env.APPIMAGE)
+  let existing = resolve(entryPath),
+    suffix = ''
+  while (!existsSync(existing)) {
+    suffix = join(existing.slice(dirname(existing).length + 1), suffix)
+    existing = dirname(existing)
+  }
+  const entry = resolve(realpathSync(existing), suffix)
+  let cursor = dirname(entry)
+  while (dirname(cursor) !== cursor) {
+    if (cursor.endsWith(join('Contents', 'Resources'))) return dirname(dirname(cursor))
+    if (cursor.endsWith('/resources') || cursor.endsWith('\\resources')) return dirname(cursor)
+    cursor = dirname(cursor)
+  }
+  const backend = dirname(entry)
+  return dirname(backend).endsWith('/out') || dirname(backend).endsWith('\\out')
+    ? dirname(dirname(backend))
+    : dirname(backend)
+}
+const REGISTRATION_NAME = /^([\da-f-]{36})\.(json|sqlite)$/
+const MAX_REAPED_PER_PASS = 200
+// Caller MUST hold the coordinator lock: registrations are only created, probed and reclaimed under
+// it, so a free kernel lock here means the owner is gone and nobody can re-open the file meanwhile.
+// The pair is removed json first, so a reader never sees a registration without its lifetime lock.
+function reapStaleRegistrations(directory, DatabaseSync = require('node:sqlite').DatabaseSync) {
+  const ids = new Set()
+  for (const name of readdirSync(directory)) {
+    const match = REGISTRATION_NAME.exec(name)
+    if (match) ids.add(match[1])
+  }
+  let reaped = 0
+  for (const id of ids) {
+    if (reaped >= MAX_REAPED_PER_PASS) break
+    const lock = join(directory, `${id}.sqlite`)
+    let probe
+    try {
+      probe = new DatabaseSync(lock)
+      probe.exec('PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE')
+    } catch {
+      // Held by a live process (or unreadable right now): never delete it.
+      try {
+        probe?.close()
+      } catch {
+        // Already closed or never opened.
+      }
+      continue
+    }
+    // Close before unlinking: Windows cannot remove an open file.
+    probe.close()
+    try {
+      rmSync(join(directory, `${id}.json`), { force: true })
+      rmSync(lock, { force: true })
+      reaped += 1
+    } catch {
+      // Best effort: the next pass retries.
+    }
+  }
+  return reaped
+}
+function protectInstallationStartup(entryPath, configRoot, stateRoot) {
+  // Loading node:sqlite emits an experimental warning on Node 22; ordinary CLI commands
+  // must not load it and contaminate their machine-readable output.
+  let DatabaseSync
+  try {
+    ;({ DatabaseSync } = require('node:sqlite'))
+  } catch (cause) {
+    throw new Error(
+      `Open-Science startup requires Node.js 22.13 or newer (node:sqlite is unavailable on ${process.version}).`,
+      { cause }
+    )
+  }
+  const root = installationRootForEntry(entryPath)
+  const key = createHash('sha256')
+    .update(process.platform === 'win32' ? root.toLowerCase() : root)
+    .digest('hex')
+  const directory = join(
+    stateRoot ??
+      process.env.OPEN_SCIENCE_INSTALLATION_STATE_ROOT ??
+      (process.env.OPEN_SCIENCE_E2E_STORAGE_ROOT
+        ? join(process.env.OPEN_SCIENCE_E2E_STORAGE_ROOT, 'installations')
+        : join(homedir(), '.open-science', 'installations')),
+    key
+  )
+  mkdirSync(directory, { recursive: true, mode: 0o700 })
+  const coordinator = new DatabaseSync(join(directory, 'coordinator.sqlite'))
+  let lease
+  let identity
+  try {
+    coordinator.exec('PRAGMA busy_timeout = 1500; PRAGMA journal_mode = MEMORY; BEGIN EXCLUSIVE')
+    if (existsSync(join(directory, 'update-in-progress.json')))
+      throw new Error('Installation update requires recovery before starting Open-Science.')
+    reapStaleRegistrations(directory, DatabaseSync)
+    let owner
+    const helperFlags = [
+      '--open-science-artifact-mcp',
+      '--open-science-notebook-mcp',
+      '--open-science-reviewer-mcp-proxy',
+      '--open-science-skill-import-mcp',
+      '--open-science-skill-runtime-mcp',
+      '--open-science-plan-mcp'
+    ]
+    if (
+      helperFlags.some((flag) => process.argv.includes(flag)) &&
+      process.env.OPEN_SCIENCE_INSTALLATION_OWNER
+    ) {
+      const candidate = JSON.parse(process.env.OPEN_SCIENCE_INSTALLATION_OWNER)
+      const tokenHash = createHash('sha256').update(String(candidate.token)).digest('hex')
+      for (const name of readdirSync(directory).filter((name) =>
+        /^[\da-f-]{36}\.json$/.test(name)
+      )) {
+        let registration
+        try {
+          registration = JSON.parse(readFileSync(join(directory, name), 'utf8'))
+        } catch {
+          continue
+        }
+        if (
+          registration.pid !== candidate.pid ||
+          registration.generation !== candidate.generation ||
+          registration.configRoot !== candidate.configRoot ||
+          registration.helperTokenHash !== tokenHash
+        )
+          continue
+        const probe = new DatabaseSync(join(directory, name.replace(/\.json$/, '.sqlite')))
+        try {
+          probe.exec('PRAGMA busy_timeout = 0; BEGIN EXCLUSIVE')
+        } catch (error) {
+          if (error.errcode === 5 || error.errcode === 6)
+            owner = {
+              pid: candidate.pid,
+              generation: candidate.generation,
+              configRoot: candidate.configRoot
+            }
+          else throw error
+        } finally {
+          probe.close()
+        }
+      }
+      if (!owner) throw new Error('The runtime helper installation capability is no longer valid.')
+      configRoot = owner.configRoot
+    }
+    const id = randomUUID()
+    identity = Object.freeze({
+      pid: process.pid,
+      generation: id,
+      configRoot,
+      installationRoot: root
+    })
+    lease = new DatabaseSync(join(directory, `${id}.sqlite`))
+    lease.exec('PRAGMA busy_timeout = 1500; PRAGMA journal_mode = MEMORY; BEGIN EXCLUSIVE')
+    writeFileSync(
+      join(directory, `${id}.json`),
+      JSON.stringify({
+        pid: process.pid,
+        generation: id,
+        configRoot,
+        ...(owner ? { role: 'helper', owner } : {})
+      }),
+      { flag: 'wx', mode: 0o600 }
+    )
+  } catch (error) {
+    lease?.close()
+    throw error
+  } finally {
+    coordinator.close()
+  }
+  let released = false
+  return {
+    identity,
+    isHeld: () => !released,
+    release() {
+      if (!released) {
+        released = true
+        lease.close()
+      }
+    }
+  }
+}
+
+module.exports = { installationRootForEntry, protectInstallationStartup, reapStaleRegistrations }

package/locate-app.mjs

@@ -0,0 +1,95 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+
+import { access, readFile, realpath } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const cliDir = dirname(fileURLToPath(import.meta.url))
+const repositoryRoot = resolve(cliDir, '../..')
+const require = createRequire(import.meta.url)
+
+const exists = async (path) => {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const isCurrentCli = async (candidate) => {
+  if (!process.argv[1]) return false
+  try {
+    return (await realpath(candidate)) === (await realpath(process.argv[1]))
+  } catch {
+    return false
+  }
+}
+
+// Standalone discovery follows current packaging defaults. Legacy/custom/mixed layouts require
+// an explicit binding; public Linux commands may be CLI wrappers and are never desktop candidates.
+const defaultInstalledCandidates = (env = process.env) => {
+  if (process.platform === 'win32') {
+    return [env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'Programs'), env.PROGRAMFILES]
+      .filter(Boolean)
+      .map((root) => join(root, 'Open-Science', 'open-science.exe'))
+  }
+  if (process.platform === 'darwin') {
+    return ['/Applications', env.HOME && join(env.HOME, 'Applications')]
+      .filter(Boolean)
+      .map((root) => join(root, 'Open-Science.app', 'Contents', 'MacOS', 'Open-Science'))
+  }
+  return ['/opt/Open-Science/open-science']
+}
+
+const locateDevelopmentApp = async () => {
+  const mainEntry = join(repositoryRoot, 'out', 'main', 'index.js')
+  const webEntry = join(repositoryRoot, 'out', 'web', 'index.html')
+  const electronModule = join(repositoryRoot, 'node_modules', 'electron')
+  if (!(await exists(mainEntry)) || !(await exists(webEntry)) || !(await exists(electronModule))) {
+    return undefined
+  }
+  const electronPath = require(electronModule)
+  if (!(await exists(electronPath))) return undefined
+  return {
+    command: electronPath,
+    args: [repositoryRoot],
+    packaged: false,
+    repositoryRoot
+  }
+}
+
+export const locateApp = async ({ appPath, env = process.env } = {}) => {
+  const explicit = appPath ?? env.OPEN_SCIENCE_APP_PATH
+  if (explicit) {
+    const command = resolve(explicit)
+    if (!(await exists(command))) throw new Error(`Open-Science executable not found: ${command}`)
+    return { command, args: [], packaged: true, repositoryRoot }
+  }
+
+  const development = await locateDevelopmentApp()
+  if (development) return development
+
+  for (const candidate of defaultInstalledCandidates(env)) {
+    if ((await exists(candidate)) && !(await isCurrentCli(candidate))) {
+      return { command: candidate, args: [], packaged: true, repositoryRoot }
+    }
+  }
+
+  // When run from a packaged build's resources dir there is no package.json next to the CLI, so fall
+  // back to the product name rather than letting the read mask the real "could not locate" message.
+  let productName = 'Open-Science'
+  try {
+    productName =
+      JSON.parse(await readFile(join(repositoryRoot, 'package.json'), 'utf8')).productName ??
+      productName
+  } catch {
+    // No package.json alongside the CLI (packaged): keep the default product name.
+  }
+  throw new Error(
+    `Could not locate ${productName}. Run "npm run build" in the repository, install the app, or pass --app-path / set OPEN_SCIENCE_APP_PATH to its executable.`
+  )
+}
+
+export { repositoryRoot }

package/locate-backend.mjs

@@ -0,0 +1,63 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+import { access, readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import { currentRuntimeTarget, runtimePackageName } from './runtime-package.mjs'
+
+export async function locateBackend({ required = true } = {}) {
+  if (process.versions.electron)
+    throw new Error(
+      'The CLI requires ordinary Node.js. Reinstall the desktop command-line launcher.'
+    )
+  const here = dirname(fileURLToPath(import.meta.url))
+  for (const root of [here, join(here, '../..')]) {
+    const entry = join(root, 'out/backend/index.cjs')
+    try {
+      await access(entry)
+    } catch {
+      continue
+    }
+    return {
+      command: process.execPath,
+      entry,
+      development: root !== here
+    }
+  }
+  const manifest = JSON.parse(await readFile(join(here, 'package.json'), 'utf8'))
+  // Only the registry entry package opts in; desktop launchers and source checkouts keep their paths.
+  if (manifest.optionalDependencies?.[runtimePackageName({ id: 'darwin-arm64' })]) {
+    const name = runtimePackageName(currentRuntimeTarget())
+    let packageFile
+    try {
+      packageFile = createRequire(import.meta.url).resolve(`${name}/package.json`)
+    } catch (error) {
+      if (error.code !== 'MODULE_NOT_FOUND') throw error
+      if (!required) return { development: false }
+      throw new Error(
+        `Missing ${name}@${manifest.version}. Reinstall @aipoch/open-science with npm --include=optional.`
+      )
+    }
+    const native = JSON.parse(await readFile(packageFile, 'utf8'))
+    if (native.name !== name || native.version !== manifest.version)
+      throw new Error(
+        `Open-Science native package version mismatch: expected ${name}@${manifest.version}. Reinstall the package.`
+      )
+    const entry = join(dirname(packageFile), 'out/backend/index.cjs')
+    await access(entry)
+    return { command: process.execPath, entry, development: false }
+  }
+  if (!required) {
+    // Profile initialization/offline login also work with a lightweight CLI or desktop launcher.
+    // Only a real source checkout selects the development profile without a built backend.
+    try {
+      await access(join(here, '../../src/main/node-entry.ts'))
+      return { development: true }
+    } catch {
+      return { development: false }
+    }
+  }
+  throw new Error(
+    'The standalone Node backend is missing. Install the standalone Open-Science package, or run npm run build:backend in the repository.'
+  )
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@aipoch/open-science",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "Node.js SDK and CLI for the Open-Science local daemon",
+  "type": "module",
+  "exports": {
+    "./browser-import": {
+      "types": "./browser-import.d.ts",
+      "import": "./browser-import.mjs"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    }
+  },
+  "bin": {
+    "open-science": "./cli.mjs"
+  },
+  "files": [
+    "*.mjs",
+    "*.cjs",
+    "*.d.ts",
+    "LICENSE",
+    "README.md",
+    "CLI.md",
+    "BROWSER_IMPORT.md"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aipoch/open-science.git",
+    "directory": "packages/open-science"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@aipoch/open-science-darwin-arm64": "1.0.2",
+    "@aipoch/open-science-darwin-x64": "1.0.2",
+    "@aipoch/open-science-linux-x64-gnu": "1.0.2",
+    "@aipoch/open-science-linux-arm64-gnu": "1.0.2",
+    "@aipoch/open-science-win32-x64": "1.0.2"
+  }
+}

package/runtime-control.mjs

@@ -0,0 +1,51 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { candidateConfigRoots, readWebToken } from './config-root.mjs'
+
+// Discovery records are hints. A live authenticated response from the same generation is authority.
+export async function requestExistingRuntimeWeb(options, fetch = globalThis.fetch) {
+  for (const configRoot of candidateConfigRoots({ override: options.configRoot })) {
+    let record
+    try {
+      record = JSON.parse(await readFile(join(configRoot, 'runtime-owner.json'), 'utf8'))
+    } catch {
+      continue
+    }
+    if (
+      record.schemaVersion !== 1 ||
+      !Number.isSafeInteger(record.pid) ||
+      record.pid < 1 ||
+      !Number.isSafeInteger(record.port) ||
+      record.port < 1 ||
+      record.port > 65535 ||
+      !['node', 'electron'].includes(record.host) ||
+      typeof record.generation !== 'string'
+    )
+      continue
+    let response
+    try {
+      response = await fetch(
+        `http://127.0.0.1:${record.port}${options.credentialStore !== undefined ? '/owner' : `/web/start?port=${options.port ?? 44100}`}`,
+        {
+          method: options.credentialStore !== undefined ? 'GET' : 'POST',
+          headers: {
+            authorization: `Bearer ${await readWebToken(configRoot)}`,
+            'x-open-science-runtime-generation': record.generation
+          },
+          signal: AbortSignal.timeout(30_000)
+        }
+      )
+      if (!response.ok) continue
+      const result = await response.json()
+      if (result.generation !== record.generation || result.pid !== record.pid) continue
+    } catch {
+      continue
+    }
+    if (options.credentialStore !== undefined)
+      throw new Error(
+        'Open-Science is already running. Stop it before selecting a credential store.'
+      )
+    return configRoot
+  }
+}

package/runtime-package.mjs

@@ -0,0 +1,19 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+
+// This is the published native support set, shared by packing and runtime discovery.
+export const runtimeTargets = [
+  { id: 'darwin-arm64', os: 'darwin', cpu: 'arm64' },
+  { id: 'darwin-x64', os: 'darwin', cpu: 'x64' },
+  { id: 'linux-x64-gnu', os: 'linux', cpu: 'x64', libc: 'glibc' },
+  { id: 'linux-arm64-gnu', os: 'linux', cpu: 'arm64', libc: 'glibc' },
+  { id: 'win32-x64', os: 'win32', cpu: 'x64' }
+]
+export const runtimePackageName = (target) => `@aipoch/open-science-${target.id}`
+export function currentRuntimeTarget(platform = process.platform, arch = process.arch) {
+  const target = runtimeTargets.find((item) => item.os === platform && item.cpu === arch)
+  if (!target || (platform === 'linux' && !process.report.getReport().header.glibcVersionRuntime))
+    throw new Error(
+      `Open-Science has no native npm package for ${platform}/${arch}. Linux requires glibc.`
+    )
+  return target
+}