@aipoch/open-science 1.0.1 → 1.0.2

package/CLI.md

@@ -8,7 +8,29 @@ defines the 1.x contract for commands, machine-readable output and exit codes.
 
 ## Installation
 
-### Standalone Node package
+### From npm
+
+Install the published [standalone CLI](https://www.npmjs.com/package/@aipoch/open-science)
+with Node.js **22.13.0 or later**:
+
+```bash
+npm install --global @aipoch/open-science
+open-science start --no-open
+open-science url
+```
+
+The registry package installs the matching native backend, Web UI and resources through npm
+optional dependencies. It runs without Electron or an installed desktop app. Supported targets
+are macOS ARM64/x64, glibc Linux ARM64/x64 and Windows x64; musl Linux and Windows ARM64 are not
+supported. Do not omit optional dependencies. If startup reports a missing native package, run
+`npm install --global @aipoch/open-science --include=optional`.
+
+Open the printed authenticated URL to configure an Agent runtime, model provider and optional
+Python/R Notebook runtime, or follow [First-run setup (Codex)](#first-run-setup-codex) from the
+terminal. See the [standalone runtime guide](https://github.com/aipoch/open-science/blob/main/docs/standalone-runtime.md#linux-prerequisites)
+for Linux credential storage and sandbox prerequisites.
+
+### Locally built standalone tarball
 
 Install the target-specific standalone tarball built with `npm run pack:backend`, using ordinary
 Node >=22.13.0. It includes the backend, Web UI, resources and native dependencies; Electron and
@@ -54,25 +76,58 @@ not require a separate Node.js installation.
 If the launcher directory is not yet on PATH, the Settings panel shows the line to add. Open a new
 terminal after updating PATH. Choose **Uninstall command** in the same panel to remove the launcher.
 
-### From npm
+### From a source checkout
 
-The lightweight CLI/SDK package requires Node.js 22.5 or later. It controls an existing service.
-To start an independent service, install the standalone artifact (Node >=22.13.0); the lightweight
-package alone does not contain backend resources.
-Install it globally after the package is published:
+Replace `open-science` in the examples below with:
 
 ```bash
-npm install --global @aipoch/open-science
-open-science --help
+node packages/open-science/cli.mjs
 ```
 
-### From a source checkout
+## Local information and help
 
-Replace `open-science` in the examples below with:
+These commands work without starting or connecting to the service:
 
 ```bash
-node packages/open-science/cli.mjs
-```
+open-science --version
+open-science -v
+open-science version --json
+open-science help
+open-science help run
+open-science paths --json
+open-science paths --profile /absolute/path/to/profile
+```
+
+`--version`, `-v`, and `version` print the invoked CLI's application version, including any
+nightly suffix. `version --json` prints `{ "version": "..." }`. Source checkouts use the root
+application version; installed distributions use their own release metadata. This is not the
+version of a running service. The version flags are standalone commands, not options for `run`,
+`start`, or other commands.
+
+`help` is equivalent to `--help`; `help <command>` is equivalent to `<command> --help`.
+For example, `help project` lists Project commands. Unknown command names and unsupported
+arguments fail with the existing usage-error exit code `2`.
+
+`paths` prints human-readable locations; `paths --json` prints one object with:
+
+| Field                  | Meaning                                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `cliPath`              | The CLI implementation file used by this invocation.                                     |
+| `nodePath`             | The Node executable running the CLI.                                                     |
+| `startupConfigRoot`    | The configuration directory selected by the installation's default or explicit override. |
+| `discoveryConfigRoots` | Ordered candidate configuration directories searched for an existing service.            |
+
+Source checkouts default to `~/.open-science-project` for startup; installations default to
+`~/.open-science`. Without an override, service discovery checks the development directory first,
+then the production directory. `--config-root` (or `--profile`) takes precedence over
+`OPEN_SCIENCE_CONFIG_ROOT`, then `OPEN_SCIENCE_STORAGE_ROOT`; an override selects a single
+absolute directory for both startup and discovery. Paths are reported even when they do not exist.
+The output does not identify an active service or a research-data directory, which may differ.
+
+These commands do not create profiles, modify settings, read credentials, or print authenticated
+URLs. Successful queries exit `0`; missing or invalid version metadata produces an error rather
+than a fallback version. `paths` accepts only the profile, JSON, and help options; `version`
+accepts only JSON and help options, and `help` accepts only one optional command name and help flags.
 
 ## Service lifecycle
 
@@ -106,7 +161,7 @@ open-science url
 `open-science url` is the only command that intentionally prints an authenticated browser URL. Normal
 human-readable, JSON, and JSONL output never includes the local token.
 
-Use `--port <port>` to override `OPEN_SCIENCE_WEB_PORT`, or the default port of `44100` when neither is set. `start` discovers the standalone
+Use `--port <port>` to override `OPEN_SCIENCE_WEB_PORT`, or the default port of `44100` when neither is set. `start` discovers the matching npm platform package, the standalone
 Node entry bundled beside the CLI, or `out/backend/index.cjs` in a source checkout. Build the
 source entry with `npm run build:backend` and Web UI with `npm run build:web` first.
 `--app-path` and `OPEN_SCIENCE_APP_PATH` no longer select a hidden Electron backend.
@@ -166,7 +221,7 @@ nonzero CLI error codes.
 
 ## First-run setup (Codex)
 
-Install the standalone artifact or a desktop package containing the ordinary Node backend first.
+Install the npm package, a standalone artifact or a desktop package containing the ordinary Node backend first.
 `init` creates a configuration directory only; `--profile` selects an absolute configuration directory.
 
 ```bash
@@ -249,9 +304,23 @@ open-science runtime list --json
 ## Upgrading installations
 
 Stop the backend before upgrading an installation, then restart it with the same profile.
+For a global npm installation:
+
+```bash
+open-science stop
+npm install --global @aipoch/open-science@latest
+open-science start --no-open
+```
+
+Stop every profile started by that installation before updating it; use `--config-root` for
+custom profiles. To uninstall, stop those services and run
+`npm uninstall --global @aipoch/open-science`. Research data and credentials are retained.
+See [release compatibility](https://github.com/aipoch/open-science/blob/main/docs/compatibility.md)
+before downgrading; reinstalling an older package does not undo data migrations.
+
 Use the installation channel that owns the CLI: Homebrew for a Formula, the new downloaded
 package for deb/rpm or a local npm tarball, or a verified new Release archive in a new directory
-with PATH/the symlink updated. npm registry publication remains deferred.
+with PATH/the symlink updated.
 The desktop update UI discovers and downloads packages. Automatic replacement remains closed for
 macOS ZIP, Linux AppImage and Debian until each channel passes complete installed-package
 acceptance. Windows automatic installation remains disabled; artifact checks and same-version copy tests do not certify a cross-version upgrade.

package/README.md

@@ -1,10 +1,88 @@
 # @aipoch/open-science
 
-Node.js SDK and command-line client for an Open-Science daemon running on the local machine.
+[AIPOCH Open-Science](https://github.com/aipoch/open-science) is an open-source, local-first,
+model-agnostic AI research workbench. Use scientific Agents, Python and R Notebooks, and
+scientific data connectors to turn research questions into reports, tables and figures.
+
+This package provides the **standalone CLI, local Web UI and Node.js SDK**. npm installs the
+matching platform package with the backend and resources; the desktop app is not required.
+
+## Install
+
+Install [Node.js](https://nodejs.org/) **22.13.0 or later**, then run:
+
+```bash
+npm install --global @aipoch/open-science
+open-science --help
+```
+
+Supported platforms are macOS Apple Silicon/Intel, Linux ARM64/x64 with glibc, and Windows x64.
+Linux musl (including Alpine) and Windows ARM64 are not supported by the published native packages.
+Keep npm optional dependencies enabled: they contain the platform runtime. If startup reports a
+missing native package, reinstall with `npm install --global @aipoch/open-science --include=optional`.
+
+Linux also needs working credential storage and Notebook sandbox prerequisites; see the
+[Linux setup requirements](https://github.com/aipoch/open-science/blob/main/docs/standalone-runtime.md#linux-prerequisites).
+Python/R and an Agent runtime/model provider are configured separately during setup.
+For installations that include Node itself, see the
+[Homebrew and Release archive options](https://github.com/aipoch/open-science/blob/main/docs/standalone-runtime.md).
+
+## Get started
+
+Start the local service and request its browser URL:
+
+```bash
+open-science start --no-open
+open-science url
+```
+
+Open the printed URL, complete the setup checks, configure an Agent runtime and model provider,
+and create your first research project. Set up a Python or R Notebook runtime if your work needs
+code execution. The URL contains a local authentication token; keep it private.
+For setup from the terminal, follow the
+[CLI first-run guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md#first-run-setup-codex).
+
+After setup, submit a task from the terminal:
+
+```bash
+open-science doctor --json
+open-science project create "First research" --json
+open-science run --project "First research" --prompt "Draft a research plan for comparing two analysis methods." --wait --jsonl
+```
+
+Confirm `ready: true` in the doctor output before submitting work. The CLI accepts a Project ID
+or an exact, unambiguous name; SDK calls use IDs. Closing the browser does not stop the service:
+
+```bash
+open-science status --json
+open-science stop
+```
+
+Stopping the service affects all connected clients. For automated tasks, review the
+[permissions and output options](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md)
+and the safety guidance below.
+
+## Update or uninstall
+
+Stop services started by this installation before replacing it. Use the same `--config-root`
+when stopping and restarting a custom profile.
+
+```bash
+open-science stop
+npm install --global @aipoch/open-science@latest
+open-science start --no-open
+```
+
+To uninstall, stop the service and run `npm uninstall --global @aipoch/open-science`.
+Uninstalling the npm package retains research data and credentials. Review
+[release compatibility](https://github.com/aipoch/open-science/blob/main/docs/compatibility.md)
+before changing versions; replacing program files does not reverse data migrations.
 
 ## Documentation
 
-- [CLI guide](./CLI.md) - installation, daemon lifecycle, task automation, artifacts, and exit codes
+- [CLI guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/CLI.md) - installation, daemon lifecycle, task automation, artifacts, and exit codes
+- [Product overview](https://github.com/aipoch/open-science#readme) - research workflows, screenshots and desktop downloads
+- [Report an issue](https://github.com/aipoch/open-science/issues) - bugs and feature requests
 - [Release compatibility](https://github.com/aipoch/open-science/blob/main/docs/compatibility.md) - stable interfaces, versioning, and data upgrades
 - [Intended use](https://github.com/aipoch/open-science/blob/main/docs/usage-scope.md) and [known limitations](https://github.com/aipoch/open-science/blob/main/docs/known-limitations.md) - workflow precautions, data disclosure, and execution boundaries
 
@@ -25,19 +103,28 @@ Node.js SDK and command-line client for an Open-Science daemon running on the lo
 ## Browser-held package import
 
 Use `@aipoch/open-science/browser-import` to send a downloaded `.science` Blob to the desktop app.
-See the [browser integration guide](./BROWSER_IMPORT.md) for the click flow, API, security contract,
+See the [browser integration guide](https://github.com/aipoch/open-science/blob/main/packages/open-science/BROWSER_IMPORT.md) for the click flow, API, security contract,
 limits, and browser requirements. The desktop never downloads the online package URL.
 
 ## SDK quick start
 
+Install the package in your Node.js project (a global CLI install does not make it importable):
+
+```bash
+npm install @aipoch/open-science
+```
+
+Start and configure the local service as above. Save the example in an `.mjs` file and run it
+with Node.js. It creates a Project and uses its ID for subsequent requests:
+
 ```js
 import { connectToOpenScience } from '@aipoch/open-science'
 
 const client = await connectToOpenScience()
+const project = await client.createProject({ name: 'Evidence review' })
 const run = await client.startRun({
-  project: '<project-id-or-exact-name>',
+  project: project.id,
   prompt: 'Summarize the evidence.',
-  cwd: '/absolute/path/to/research',
   permissionProfile: 'auto',
   permissionPrompts: 'none' // Deny requests that would require a human; keep existing permission rules.
 })
@@ -55,8 +142,8 @@ await client.updateSessionConfiguration(run.sessionId, {
   memoryEnabled: false
 })
 
-const defaults = await client.getProjectSessionDefaults('systematic-review')
-await client.updateProjectSessionDefaults('systematic-review', {
+const defaults = await client.getProjectSessionDefaults(project.id)
+await client.updateProjectSessionDefaults(project.id, {
   expectedUpdatedAt: defaults.updatedAt,
   patch: { permissionProfile: 'auto' }
 })
@@ -142,7 +229,7 @@ const progress = (async () => {
 })()
 
 const observedRun = await client.startRun({
-  project: '<project-id-or-exact-name>',
+  project: project.id,
   prompt: 'Summarize the evidence.',
   permissionProfile: 'auto'
 })

package/cli.mjs

@@ -5,14 +5,19 @@
 import { randomUUID } from 'node:crypto'
 import { closeSync, createWriteStream, existsSync, openSync, realpathSync } from 'node:fs'
 import { chmod, lstat, mkdir, readFile, readlink, rename, rm, stat } from 'node:fs/promises'
-import { dirname, join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 import { text as readStreamText } from 'node:stream/consumers'
 import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 
-import { findServiceState, readWebToken, resolveConfigRoot } from './config-root.mjs'
+import {
+  candidateConfigRoots,
+  findServiceState,
+  readWebToken,
+  resolveConfigRoot
+} from './config-root.mjs'
 import { codexLoginCommand } from './codex-login.mjs'
 import { connectToOpenScience, OpenScienceApiError } from './index.mjs'
 import { locateBackend } from './locate-backend.mjs'
@@ -27,6 +32,9 @@ const MAX_DOWNLOAD_SYMLINK_HOPS = 40
 const usage = `Usage: open-science <command> [options]
 
 Commands:
+  version     Print the local application version (also --version or -v)
+  help [command]  Show general or command help
+  paths       Show local CLI, Node and configuration discovery paths
   init        Create the local CLI configuration directory
   start       Start the headless backend and localhost web UI
   stop        Gracefully stop the backend
@@ -109,6 +117,7 @@ Options:
   --no-sandbox           Disable Chromium's process sandbox (security risk; start only)
   --force                Sign in again even when Codex credentials already exist
   --json                 Emit one machine-readable result
+  -v, --version          Print the local application version and exit
   -h, --help             Show this help`
 
 // Flags that take a value, mapped to their camelCase option key (explicit so new hyphenated flags
@@ -186,6 +195,9 @@ const GROUP_COMMANDS = new Set([
 // Project create, update, and session-defaults intentionally remain unbounded because their
 // positional Project names may contain multiple unquoted words.
 const POSITIONAL_LIMITS = new Map([
+  ['version', 0],
+  ['help', 1],
+  ['paths', 0],
   ['doctor', 0],
   ['runtime list', 0],
   ['runtime install', 1],
@@ -255,7 +267,17 @@ const assertPositionalLimit = (command, subcommand, positionals) => {
 
 export const parseCliArgs = (argv) => {
   const args = [...argv]
-  const command = args.shift()
+  const requestedCommand = args.shift()
+  const command =
+    requestedCommand === '--version' || requestedCommand === '-v' ? 'version' : requestedCommand
+  const localOptions =
+    command === 'version'
+      ? ['--json', '--help', '-h']
+      : command === 'paths'
+        ? ['--json', '--help', '-h', '--config-root', '--profile']
+        : command === 'help'
+          ? ['--help', '-h']
+          : undefined
   const subcommand =
     (GROUP_COMMANDS.has(command) && args[0] && !args[0].startsWith('-')) ||
     (command === 'run' && (args[0] === 'status' || args[0] === 'cancel'))
@@ -270,6 +292,9 @@ export const parseCliArgs = (argv) => {
   const positionals = []
   while (args.length > 0) {
     const arg = args.shift()
+    if (localOptions && arg.startsWith('-') && !localOptions.includes(arg)) {
+      throw new CliUsageError(`Unknown option for ${command}: ${arg}`)
+    }
     if (arg.startsWith('--credential-store=')) {
       if (options.credentialStore !== undefined)
         throw new CliUsageError('Specify --credential-store only once.')
@@ -347,6 +372,10 @@ export const parseCliArgs = (argv) => {
     ...(positionals.length ? { positionals } : {}),
     options
   }
+  if (localOptions) {
+    assertPositionalLimit(command, subcommand, positionals)
+    return parsed
+  }
   // Help is local: it must not require execution-only options or a running backend.
   if (options.help) return parsed
   if (options.port !== undefined) {
@@ -1749,14 +1778,55 @@ ${commands.join('\n')}
 Run "open-science --help" for the complete option reference.`
 }
 
+const readCliMetadata = async () => {
+  const here = dirname(fileURLToPath(import.meta.url))
+  // Source SDK metadata has its own version; installed CLI manifests carry the release version.
+  const development =
+    basename(here) === 'open-science' &&
+    basename(dirname(here)) === 'packages' &&
+    existsSync(join(here, '../../src/main/node-entry.ts'))
+  const manifestPath = join(development ? join(here, '../..') : here, 'package.json')
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  if (
+    manifest.name !== (development ? 'open-science' : '@aipoch/open-science') ||
+    typeof manifest.version !== 'string' ||
+    !/^\d+\.\d+\.\d+(?:-[\da-zA-Z.-]+)?(?:\+[\da-zA-Z.-]+)?$/.test(manifest.version)
+  ) {
+    throw new Error(`Invalid Open-Science CLI metadata: ${manifestPath}`)
+  }
+  return { version: manifest.version, development }
+}
+
+const pathsCommand = async (options) => {
+  const { development } = await readCliMetadata()
+  const paths = {
+    cliPath: fileURLToPath(import.meta.url),
+    nodePath: process.execPath,
+    startupConfigRoot: resolveConfigRoot({
+      packaged: !development,
+      override: options.configRoot
+    }),
+    discoveryConfigRoots: candidateConfigRoots({ override: options.configRoot })
+  }
+  console.log(
+    options.json
+      ? JSON.stringify(paths)
+      : `CLI: ${paths.cliPath}\nNode: ${paths.nodePath}\nStartup configuration: ${paths.startupConfigRoot}\nService discovery (in order):\n${paths.discoveryConfigRoots.map((root) => `  ${root}`).join('\n')}`
+  )
+}
+
 export const runCli = async (argv = process.argv.slice(2)) => {
   const parsed = parseCliArgs(argv)
   const { command, options } = parsed
-  if (options.help || !command || command === '-h' || command === '--help') {
-    console.log(commandHelp(command))
+  if (options.help || !command || command === 'help' || command === '-h' || command === '--help') {
+    console.log(commandHelp(command === 'help' ? parsed.positionals?.[0] : command))
     return
   }
-  if (command === 'init') await initCommand(options)
+  if (command === 'version') {
+    const { version } = await readCliMetadata()
+    console.log(options.json ? JSON.stringify({ version }) : version)
+  } else if (command === 'paths') await pathsCommand(options)
+  else if (command === 'init') await initCommand(options)
   else if (command === 'start') await startCommand(options)
   else if (command === 'stop') await stopCommand(options)
   else if (command === 'status') await statusCommand(options)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipoch/open-science",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Node.js SDK and CLI for the Open-Science local daemon",
   "type": "module",
   "exports": {
@@ -38,10 +38,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@aipoch/open-science-darwin-arm64": "1.0.1",
-    "@aipoch/open-science-darwin-x64": "1.0.1",
-    "@aipoch/open-science-linux-x64-gnu": "1.0.1",
-    "@aipoch/open-science-linux-arm64-gnu": "1.0.1",
-    "@aipoch/open-science-win32-x64": "1.0.1"
+    "@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"
   }
 }