@researai/deepscientist 1.5.2 → 1.5.3

package/README.md

@@ -52,6 +52,28 @@ The default DeepScientist home is:
 
 Use `ds --home <path>` if you want to place the runtime somewhere else.
 
+If you want to use the current working directory directly as the DeepScientist home, use:
+
+```bash
+ds --hero
+```
+
+This is equivalent to launching with `ds --home "$PWD"`.
+
+If you want to install the bundled CLI tree into another base path from a source checkout:
+
+```bash
+bash install.sh --dir /data/DeepScientist
+```
+
+If you already have a populated DeepScientist home and want to move it safely:
+
+```bash
+ds migrate /data/DeepScientist
+```
+
+`ds migrate` stops the managed daemon first, shows the absolute source and target paths, asks for a double confirmation, verifies the copied tree, updates launcher wrappers, and only then removes the old path.
+
 ## Troubleshooting
 
 ```bash

package/bin/ds.js

@@ -13,6 +13,7 @@ const pyprojectToml = fs.readFileSync(path.join(repoRoot, 'pyproject.toml'), 'ut
 const pythonCandidates = process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python'];
 const requiredPythonSpec = parseRequiredPythonSpec(pyprojectToml);
 const minimumPythonVersion = parseMinimumPythonVersion(requiredPythonSpec);
+const launcherWrapperCommands = ['ds', 'ds-cli', 'research', 'resear'];
 const pythonCommands = new Set([
   'init',
   'new',
@@ -46,6 +47,9 @@ Usage:
   ds update
   ds update --check
   ds update --yes
+  ds migrate /data/DeepScientist
+  ds --hero
+  ds --hero doctor
   ds --tui
   ds --both
   ds --host 0.0.0.0 --port 21000
@@ -67,6 +71,7 @@ Launcher flags:
   --stop                Stop the managed daemon
   --restart             Restart the managed daemon
   --home <path>         Use a custom DeepScientist home
+  --hero                Use the current working directory as DeepScientist home
   --quest-id <id>       Open the TUI on one quest directly
 
 Update:
@@ -74,6 +79,10 @@ Update:
   ds update --check     Print structured update status
   ds update --yes       Install the latest npm release immediately
 
+Migration:
+  ds migrate <target>   Move the DeepScientist home/install root to a new absolute path
+  ds migrate <target> --yes --restart
+
 Runtime:
   DeepScientist uses uv to manage a locked local Python runtime.
   If uv is missing, ds bootstraps a local copy under the DeepScientist home automatically.
@@ -384,6 +393,9 @@ function resolveHome(args) {
   if (index >= 0 && index + 1 < args.length) {
     return path.resolve(args[index + 1]);
   }
+  if (args.includes('--hero') || args.includes('--here')) {
+    return process.cwd();
+  }
   if (process.env.DEEPSCIENTIST_HOME) {
     return path.resolve(process.env.DEEPSCIENTIST_HOME);
   }
@@ -554,12 +566,14 @@ function renderLaunchHints({ home, url, bindUrl, pythonSelection }) {
   renderKeyValueRows([
     ['ds --port 21000', 'Change the web port'],
     ['ds --host 0.0.0.0 --port 21000', 'Bind on all interfaces'],
+    ['ds --hero', 'Use the current directory as home'],
     ['ds --both', 'Start web + TUI together'],
     ['ds --tui', 'Start the terminal workspace only'],
     ['ds --no-browser', 'Do not auto-open the browser'],
     ['ds --status', 'Show daemon health as JSON'],
     ['ds --restart', 'Restart the managed daemon'],
     ['ds --stop', 'Stop the managed daemon'],
+    ['ds migrate /data/DeepScientist', 'Move the full home/install root safely'],
     ['ds --help', 'Show the full launcher help'],
   ]);
   console.log('');
@@ -630,6 +644,7 @@ function printLaunchCard({
   console.log(centerText(browserLine, width));
   console.log(centerText(nextStep, width));
   console.log(centerText('Run ds --stop to stop the managed daemon.', width));
+  console.log(centerText('Need to move this installation later? Use ds migrate /new/path.', width));
   console.log('');
   renderLaunchHints({ home, url, bindUrl, pythonSelection });
 }
@@ -894,6 +909,22 @@ Flags:
 `);
 }
 
+function printMigrateHelp() {
+  console.log(`DeepScientist migrate
+
+Usage:
+  ds migrate /absolute/target/path
+  ds migrate /absolute/target/path --yes
+  ds migrate /absolute/target/path --restart
+  ds migrate /absolute/target/path --home /current/source/path
+
+Flags:
+  --yes              Skip the interactive double-confirmation prompt
+  --restart          Start the managed daemon again from the migrated home
+  --home <path>      Override the current DeepScientist source home/root
+`);
+}
+
 function parseUpdateArgs(argv) {
   const args = [...argv];
   if (args[0] === 'update') {
@@ -950,6 +981,40 @@ function parseUpdateArgs(argv) {
   };
 }
 
+function parseMigrateArgs(argv) {
+  const args = [...argv];
+  if (args[0] === 'migrate') {
+    args.shift();
+  }
+  let home = null;
+  let target = null;
+  let yes = false;
+  let restart = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--yes') yes = true;
+    else if (arg === '--restart') restart = true;
+    else if (arg === '--home' && args[index + 1]) home = path.resolve(expandUserPath(args[++index]));
+    else if (arg === '--help' || arg === '-h') return { help: true };
+    else if (arg.startsWith('--')) return null;
+    else if (!target) target = path.resolve(expandUserPath(arg));
+    else return null;
+  }
+
+  if (!target) {
+    return null;
+  }
+
+  return {
+    help: false,
+    home,
+    target,
+    yes,
+    restart,
+  };
+}
+
 function findFirstPositionalArg(args) {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -973,6 +1038,188 @@ function realpathOrSelf(targetPath) {
   }
 }
 
+function isPathEqual(left, right) {
+  return realpathOrSelf(path.resolve(left)) === realpathOrSelf(path.resolve(right));
+}
+
+function isPathInside(candidatePath, parentPath) {
+  const candidate = realpathOrSelf(path.resolve(candidatePath));
+  const parent = realpathOrSelf(path.resolve(parentPath));
+  if (candidate === parent) {
+    return false;
+  }
+  const relative = path.relative(parent, candidate);
+  return Boolean(relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function buildInstalledWrapperScript() {
+  return [
+    '#!/usr/bin/env bash',
+    'set -euo pipefail',
+    'SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+    'HOME_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"',
+    'if [ -z "${DEEPSCIENTIST_HOME:-}" ]; then',
+    '  export DEEPSCIENTIST_HOME="$HOME_DIR"',
+    'fi',
+    'NODE_BIN="${DEEPSCIENTIST_NODE:-node}"',
+    'exec "$NODE_BIN" "$SCRIPT_DIR/ds.js" "$@"',
+    '',
+  ].join('\n');
+}
+
+function buildGlobalWrapperScript({ installDir, home, commandName }) {
+  return [
+    '#!/usr/bin/env bash',
+    'set -euo pipefail',
+    'if [ -z "${DEEPSCIENTIST_HOME:-}" ]; then',
+    `  export DEEPSCIENTIST_HOME="${home}"`,
+    'fi',
+    `exec "${path.join(installDir, 'bin', commandName)}" "$@"`,
+    '',
+  ].join('\n');
+}
+
+function writeExecutableScript(targetPath, content) {
+  ensureDir(path.dirname(targetPath));
+  fs.writeFileSync(targetPath, content, { encoding: 'utf8', mode: 0o755 });
+  fs.chmodSync(targetPath, 0o755);
+}
+
+function repairMigratedInstallWrappers(targetHome) {
+  const installBinDir = path.join(targetHome, 'cli', 'bin');
+  if (!fs.existsSync(installBinDir)) {
+    return;
+  }
+  const content = buildInstalledWrapperScript();
+  for (const commandName of launcherWrapperCommands) {
+    const wrapperPath = path.join(installBinDir, commandName);
+    if (!fs.existsSync(wrapperPath)) {
+      continue;
+    }
+    writeExecutableScript(wrapperPath, content);
+  }
+}
+
+function candidateWrapperPathsForCommand(commandName) {
+  const directories = String(process.env.PATH || '')
+    .split(path.delimiter)
+    .filter(Boolean);
+  const candidates = [];
+  for (const directory of directories) {
+    candidates.push(path.join(directory, commandName));
+    if (process.platform === 'win32') {
+      candidates.push(path.join(directory, `${commandName}.cmd`));
+      candidates.push(path.join(directory, `${commandName}.ps1`));
+    }
+  }
+  return candidates;
+}
+
+function rewriteLauncherWrappersIfPointingAtSource({ sourceHome, targetHome }) {
+  if (process.platform === 'win32') {
+    return [];
+  }
+  const rewritten = [];
+  const sourceInstallDir = path.join(sourceHome, 'cli');
+  const targetInstallDir = path.join(targetHome, 'cli');
+  for (const commandName of launcherWrapperCommands) {
+    for (const candidate of candidateWrapperPathsForCommand(commandName)) {
+      if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
+        continue;
+      }
+      let text = '';
+      try {
+        text = fs.readFileSync(candidate, 'utf8');
+      } catch {
+        continue;
+      }
+      if (!text.includes(sourceInstallDir) && !text.includes(sourceHome)) {
+        continue;
+      }
+      writeExecutableScript(
+        candidate,
+        buildGlobalWrapperScript({
+          installDir: targetInstallDir,
+          home: targetHome,
+          commandName,
+        })
+      );
+      rewritten.push(candidate);
+    }
+  }
+  return rewritten;
+}
+
+function scheduleDeferredSourceCleanup({ sourceHome, targetHome }) {
+  const logPath = path.join(targetHome, 'logs', 'migrate-cleanup.log');
+  ensureDir(path.dirname(logPath));
+  const helperScript = [
+    "const fs = require('node:fs');",
+    "const { setTimeout: sleep } = require('node:timers/promises');",
+    'const parentPid = Number(process.argv[1]);',
+    'const sourceHome = process.argv[2];',
+    'const logPath = process.argv[3];',
+    '(async () => {',
+    '  for (let attempt = 0; attempt < 300; attempt += 1) {',
+    '    try {',
+    '      process.kill(parentPid, 0);',
+    '      await sleep(100);',
+    '      continue;',
+    '    } catch {',
+    '      break;',
+    '    }',
+    '  }',
+    '  try {',
+    '    fs.rmSync(sourceHome, { recursive: true, force: true });',
+    '  } catch (error) {',
+    "    fs.appendFileSync(logPath, `[${new Date().toISOString()}] ${error instanceof Error ? error.message : String(error)}\\n`, 'utf8');",
+    '    process.exit(1);',
+    '  }',
+    '})();',
+  ].join('\n');
+  const child = spawn(process.execPath, ['-e', helperScript, String(process.pid), sourceHome, logPath], {
+    detached: true,
+    stdio: 'ignore',
+    env: process.env,
+  });
+  child.unref();
+}
+
+async function promptMigrationConfirmation({ sourceHome, targetHome }) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('DeepScientist migration needs a TTY for confirmation. Re-run with `--yes` to continue non-interactively.');
+  }
+  console.log('');
+  console.log('DeepScientist home migration');
+  console.log('');
+  console.log(`From: ${sourceHome}`);
+  console.log(`To:   ${targetHome}`);
+  console.log('');
+  console.log('This will stop the managed daemon, copy the full DeepScientist root, verify the copy, update launcher wrappers, and delete the old path after success.');
+  const ask = (question) => new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(String(answer || '').trim());
+    });
+  });
+  const first = await ask('Type YES to continue: ');
+  if (first !== 'YES') {
+    return false;
+  }
+  const second = await ask('Type MIGRATE to confirm old-path deletion after a successful copy: ');
+  return second === 'MIGRATE';
+}
+
+function printMigrationSummary({ sourceHome, targetHome, restart }) {
+  console.log('');
+  console.log('DeepScientist migrate');
+  console.log('');
+  console.log(`Source: ${sourceHome}`);
+  console.log(`Target: ${targetHome}`);
+  console.log(`Restart: ${restart ? 'yes' : 'no'}`);
+}
+
 function pythonMeetsMinimum(probe) {
   if (!probe || typeof probe.major !== 'number' || typeof probe.minor !== 'number') {
     return false;
@@ -1784,6 +2031,9 @@ function normalizePythonCliArgs(args, home) {
       index += 1;
       continue;
     }
+    if (arg === '--hero' || arg === '--here') {
+      continue;
+    }
     normalized.push(arg);
   }
   return ['--home', home, ...normalized];
@@ -2996,6 +3246,135 @@ async function updateMain(rawArgs) {
   process.exit(payload.ok ? 0 : 1);
 }
 
+async function migrateMain(rawArgs) {
+  const options = parseMigrateArgs(rawArgs);
+  if (!options) {
+    printMigrateHelp();
+    process.exit(1);
+  }
+  if (options.help) {
+    printMigrateHelp();
+    process.exit(0);
+  }
+
+  const sourceHome = realpathOrSelf(options.home || resolveHome(rawArgs));
+  const targetHome = path.resolve(options.target);
+  if (!fs.existsSync(sourceHome)) {
+    console.error(`DeepScientist source path does not exist: ${sourceHome}`);
+    process.exit(1);
+  }
+  if (isPathEqual(sourceHome, targetHome)) {
+    console.error('DeepScientist source and target paths are identical. Choose a different migration target.');
+    process.exit(1);
+  }
+  if (isPathInside(targetHome, sourceHome) || isPathInside(sourceHome, targetHome)) {
+    console.error('DeepScientist migration requires two separate sibling paths. Do not nest one path inside the other.');
+    process.exit(1);
+  }
+  if (fs.existsSync(targetHome)) {
+    console.error(`DeepScientist target path already exists: ${targetHome}`);
+    process.exit(1);
+  }
+
+  printMigrationSummary({ sourceHome, targetHome, restart: options.restart });
+  if (!options.yes) {
+    const confirmed = await promptMigrationConfirmation({ sourceHome, targetHome });
+    if (!confirmed) {
+      console.log('DeepScientist migration cancelled.');
+      process.exit(1);
+    }
+  }
+
+  const state = readDaemonState(sourceHome);
+  const configured = readConfiguredUiAddressFromFile(sourceHome);
+  const url = state?.url || browserUiUrl(configured.host, configured.port);
+  const health = await fetchHealth(url);
+  if (state || healthMatchesHome({ health, home: sourceHome })) {
+    await stopDaemon(sourceHome);
+  } else if (health && health.status === 'ok') {
+    console.log(`Skipping daemon stop because ${url} belongs to another DeepScientist home.`);
+  }
+
+  const pythonRuntime = ensurePythonRuntime(sourceHome);
+  const runtimePython = pythonRuntime.runtimePython;
+  const result = runPythonCli(
+    runtimePython,
+    ['--home', sourceHome, 'migrate', targetHome],
+    { capture: true, allowFailure: true }
+  );
+  let payload = null;
+  try {
+    payload = JSON.parse(String(result.stdout || '{}'));
+  } catch {
+    payload = null;
+  }
+  if (result.status !== 0 || !payload || payload.ok !== true) {
+    if (result.stdout) {
+      process.stdout.write(result.stdout);
+      if (!String(result.stdout).endsWith('\n')) {
+        process.stdout.write('\n');
+      }
+    }
+    if (result.stderr) {
+      process.stderr.write(result.stderr);
+      if (!String(result.stderr).endsWith('\n')) {
+        process.stderr.write('\n');
+      }
+    }
+    console.error('DeepScientist migration failed.');
+    process.exit(result.status ?? 1);
+  }
+
+  repairMigratedInstallWrappers(targetHome);
+  const rewrittenWrappers = rewriteLauncherWrappersIfPointingAtSource({ sourceHome, targetHome });
+
+  const sourceContainsCurrentInstall = isPathEqual(repoRoot, path.join(sourceHome, 'cli')) || isPathInside(repoRoot, sourceHome);
+  if (sourceContainsCurrentInstall) {
+    scheduleDeferredSourceCleanup({ sourceHome, targetHome });
+  } else {
+    fs.rmSync(sourceHome, { recursive: true, force: true });
+  }
+
+  let restartMessage = 'Restart skipped.';
+  if (options.restart) {
+    const migratedLauncher = path.join(targetHome, 'cli', 'bin', 'ds.js');
+    if (!fs.existsSync(migratedLauncher)) {
+      restartMessage = `Migration succeeded, but restart was skipped because the migrated launcher is missing: ${migratedLauncher}`;
+    } else {
+      const child = spawn(
+        process.execPath,
+        [migratedLauncher, '--home', targetHome, '--daemon-only', '--no-browser', '--skip-update-check'],
+        {
+          cwd: path.join(targetHome, 'cli'),
+          detached: true,
+          stdio: 'ignore',
+          env: process.env,
+        }
+      );
+      child.unref();
+      restartMessage = 'Managed daemon restart scheduled from the migrated home.';
+    }
+  }
+
+  console.log('');
+  console.log('DeepScientist migration completed.');
+  console.log(`New home: ${targetHome}`);
+  if (payload.summary) {
+    console.log(payload.summary);
+  }
+  if (rewrittenWrappers.length > 0) {
+    console.log(`Updated wrappers: ${rewrittenWrappers.join(', ')}`);
+  }
+  console.log(restartMessage);
+  if (sourceContainsCurrentInstall) {
+    console.log(`Old path cleanup has been scheduled: ${sourceHome}`);
+  } else {
+    console.log(`Old path removed: ${sourceHome}`);
+  }
+  console.log(`Use \`ds --home ${targetHome}\` if you want to override the default explicitly.`);
+  process.exit(0);
+}
+
 async function launcherMain(rawArgs) {
   const options = parseLauncherArgs(rawArgs);
   if (!options) {
@@ -3097,6 +3476,10 @@ async function main() {
     await updateMain(args);
     return;
   }
+  if (positional && positional.value === 'migrate') {
+    await migrateMain(args);
+    return;
+  }
   if (args.length === 0 || args[0] === 'ui' || (!positional && args[0]?.startsWith('--'))) {
     await launcherMain(args);
     return;
@@ -3144,6 +3527,7 @@ module.exports = {
     legacyVenvRootPath,
     resolveUvBinary,
     resolveHome,
+    parseMigrateArgs,
     useEditableProjectInstall,
     compareVersions,
     detectInstallMode,

package/docs/en/00_QUICK_START.md

@@ -39,6 +39,28 @@ If `uv` is missing on your machine, `ds` will bootstrap a local copy automatical
 
 By default, the DeepScientist home is `~/DeepScientist` on macOS and Linux, and `%USERPROFILE%\\DeepScientist` on Windows. You can override it with `ds --home <path>`.
 
+If you want to use the current working directory as the DeepScientist home directly, run:
+
+```bash
+ds --hero
+```
+
+This is equivalent to `ds --home "$PWD"`.
+
+If you install from a source checkout and want another default base path for the bundled CLI tree, use:
+
+```bash
+bash install.sh --dir /data/DeepScientist
+```
+
+If you already have a populated DeepScientist home and need to move it to another path later, use:
+
+```bash
+ds migrate /data/DeepScientist
+```
+
+The migration command prints the absolute source and target paths, stops the managed daemon, asks for a double confirmation, verifies the copied tree, updates launcher wrappers, and removes the old path only after the migration succeeds.
+
 By default, the web UI is served at:
 
 ```text

package/docs/zh/00_QUICK_START.md

@@ -39,6 +39,28 @@ DeepScientist 现在使用 `uv` 管理锁定的本地 Python 运行时。如果
 
 默认情况下，DeepScientist home 在 macOS / Linux 上是 `~/DeepScientist`，在 Windows 上是 `%USERPROFILE%\\DeepScientist`。如果你希望放到别的路径，可以直接使用 `ds --home <path>`。
 
+如果你希望直接把“当前工作目录”作为 DeepScientist home，可以运行：
+
+```bash
+ds --hero
+```
+
+它等价于 `ds --home "$PWD"`。
+
+如果你是从源码仓库安装，并希望把默认的 CLI 安装基路径改到别的位置，可以使用：
+
+```bash
+bash install.sh --dir /data/DeepScientist
+```
+
+如果你已经有一个正在使用的 DeepScientist home，之后又想安全迁移到别的路径，可以使用：
+
+```bash
+ds migrate /data/DeepScientist
+```
+
+`ds migrate` 会先显示当前绝对路径和目标绝对路径，停止托管 daemon，要求二次确认，校验复制结果，并在确认迁移成功后才删除旧路径。
+
 默认情况下，网页会运行在：
 
 ```text