dsh-harbor-evolution 0.2.0 → 0.3.1

package/README.md

@@ -1,71 +1,70 @@
 # dsh-harbor-evolution
 
-Cordis bundle for evaluating immutable DeepSeek Harness Candidates with Harbor.
+Installable DeepSeek Harness Plugin + Skill for running stable Harbor evaluation and controlled Agent evolution loops.
+
+The package gives DSH four deterministic Harbor tools and bundles the model- and user-invocable `evolve-agent-with-harbor` Skill. The Skill clarifies the evaluation contract, initializes missing structures, establishes a baseline, diagnoses evidence, limits each iteration to one controlled Candidate change, runs regression evaluation, and produces a Promotion Gate recommendation.
 
 ## Install
 
-Install `harbor-dsh-evolution` into the same Python environment as Harbor, then add this bundle to the DSH profile you actually run. Use `web` for `dsh web`; use `headless` only for the command-line Agent:
+Requirements: Docker, Node.js 22+, pnpm, and [uv](https://docs.astral.sh/uv/). Run this from the business Agent workspace:
 
 ```bash
-uv venv .venv
-uv pip install --python .venv/bin/python harbor-dsh-evolution
-source .venv/bin/activate
-pnpm dlx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add -w dsh-harbor-evolution@0.2.0
+npx --yes dsh-harbor-evolution@latest setup --project-root "$PWD"
 ```
 
-Restart DSH after installation. Launch it from the Agent workspace and expose the two Python executables to the DSH process:
+The setup command installs both required runtimes:
 
-```bash
-cd /absolute/path/to/your-agent-workspace
-HARBOR_BIN=/absolute/path/to/.venv/bin/harbor \
-HARBOR_DSH_BIN=/absolute/path/to/.venv/bin/harbor-dsh \
-pnpm dlx @deepseek-ai/dsh@0.1.0-rc.6 web
-```
+- `harbor-dsh-evolution==0.3.0` in a managed Python environment.
+- `dsh-harbor-evolution@0.3.0` in the selected DSH profile.
 
-In the Web UI, search for the Cordis plugin id `harbor-evolution`. See the [complete local DSH Web quickstart](https://github.com/istarwyh/harbor-self-evolving/blob/main/docs/dsh-web-quickstart.md) for persistent configuration, a first evaluation, Candidate comparison, and troubleshooting.
+It then stores the absolute Harbor executable paths and `projectRoot` in the profile's `harbor-evolution` block and verifies the integration. Existing unrelated profile entries are preserved, and rerunning setup updates the same block.
 
-For development from this repository:
+The default profile is `web`. Use `--profile headless` only when that is the profile you actually run. See all options with:
 
 ```bash
-./hse dsh-install web
+npx --yes dsh-harbor-evolution@latest setup --help
 ```
 
-`-w` is required because the DSH profile directory is its pnpm workspace root.
-
-The bundle inserts one `harbor-evolution` entry and registers this project's model- and user-invocable Skill through the official DSH Skill Registry:
-
-- `evolve-agent-with-harbor`
-
-The Skill guides the Agent through workspace inspection, requirements clarification, safe initialization, baseline evaluation, evidence-based diagnosis, one controlled Candidate change, regression comparison, and a Promotion Gate recommendation. Invoke it explicitly from Web or TUI with:
+Stop any old DSH process and run the exact restart command printed by setup. Then invoke:
 
 ```text
 /evolve-agent-with-harbor
 Inspect this workspace and help me clarify and initialize a stable Harbor self-evolution loop.
 ```
 
-The Agent can also select it automatically when the request matches its catalog description. The Skill orchestrates four model-facing tools:
+The Plugin registers:
 
 - `harbor_candidate_snapshot`
 - `harbor_eval_run`
 - `harbor_eval_result`
 - `harbor_candidate_compare`
 
-The shortest direct evaluation call needs only `candidatePath` and `datasetPath`. Candidate identity defaults to `package.json`, the Job name is generated automatically, and `harbor_eval_run` returns the completed evaluation summary directly. Prefer the Skill for a new project because it will not run or compare Jobs until the material evaluation contract is resolved.
+The shortest direct evaluation call needs `candidatePath` and `datasetPath`. Prefer the Skill for a new project because it will not run or compare Jobs until the material evaluation contract is resolved.
 
-The helper launches a fixed DSH version through `pnpm dlx`, so it does not conflict with a long-running `npx` DSH process. When installed from this monorepo, the bundle automatically discovers the sibling Python virtual environment created by `./hse dsh-install`. Otherwise it uses `HARBOR_BIN` / `HARBOR_DSH_BIN`, then falls back to `PATH`. Override the inserted entry in the profile's `cordis.patch.yml` when the binaries or Python source live elsewhere:
+## What setup writes
+
+The selected profile receives one id-targeted override:
 
 ```yaml
 - id: harbor-evolution
   config:
     projectRoot: /workspace/my-agent
     jobsDir: jobs
-    harborBin: /workspace/venv/bin/harbor
-    harborDshBin: /workspace/venv/bin/harbor-dsh
+    harborBin: /managed/runtime/.venv/bin/harbor
+    harborDshBin: /managed/runtime/.venv/bin/harbor-dsh
     pythonPath: ""
 ```
 
-Keep `pythonPath` empty when using the published PyPI package. Set it only when developing the Python package from a source checkout.
+Keep `pythonPath` empty for the published Python package. `candidatePath`, `datasetPath`, `jobPath`, and `policyPath` are constrained to `projectRoot`.
+
+For source development from the repository:
+
+```bash
+./hse dsh-install-source web
+```
+
+Do not use `dsh plugin add ./packages/dsh-plugin` directly from a fresh checkout. pnpm records a `link:` dependency, and Node resolves imports from the real checkout path. The source installer first runs the package's locked `npm ci`, then links it and installs the local Python Adapter. Normal users should always use the registry-backed setup command above.
 
-This replaces the complete config for the entry, following DSH patch semantics.
+See the [complete DSH Web quickstart](https://github.com/istarwyh/harbor-self-evolving/blob/main/docs/dsh-web-quickstart.md) for UI verification, first evaluation, Candidate comparison, and troubleshooting.
 
-The plugin never mutates the active DSH profile and never deploys a Candidate. Another system updates the Champion only after the external Promotion Gate passes.
+The Plugin never deploys a Candidate or mutates the active Champion. Existing CI/CD remains responsible for building, deploying, and promoting the exact evaluated artifact.

package/bin/dsh-harbor.mjs

@@ -3,14 +3,33 @@
 import process from 'node:process'
 import { snapshotCandidate } from '../lib/candidate.js'
 import { runProcess } from '../lib/process.js'
+import { parseSetupArgs, renderSetupResult, setupIntegration } from '../lib/setup.js'
 
-function usage() {
-  console.error('Usage: dsh-harbor snapshot <candidate-dir> [--id <id>] [--version <version>]')
-  console.error('       dsh-harbor doctor')
+function usage(stream = console.error) {
+  stream('Usage: dsh-harbor setup [options]')
+  stream('       dsh-harbor snapshot <candidate-dir> [--id <id>] [--version <version>]')
+  stream('       dsh-harbor doctor')
+  stream('')
+  stream('Setup options:')
+  stream('  --project-root <path>  Agent workspace (default: current directory)')
+  stream('  --profile <name>       DSH profile (default: web)')
+  stream('  --jobs-dir <path>      Job directory under projectRoot (default: jobs)')
+  stream('  --dsh-home <path>      DSH state directory (default: DSH_HOME or ~/.dsh)')
+  stream('  --runtime-dir <path>   Managed Harbor Python environment')
 }
 
 async function main() {
   const [command, ...args] = process.argv.slice(2)
+  if (command === 'setup') {
+    const options = parseSetupArgs(args)
+    if (options.help) {
+      usage(console.log)
+      return
+    }
+    const result = await setupIntegration(options, { onProgress: message => console.log(message) })
+    console.log(renderSetupResult(result))
+    return
+  }
   if (command === 'doctor') {
     const harbor = await runProcess(process.env.HARBOR_BIN || 'harbor', ['--version'], { timeoutMs: 10000 })
     const plugins = await runProcess(process.env.HARBOR_BIN || 'harbor', ['plugins', 'list'], { timeoutMs: 10000 })
@@ -34,6 +53,6 @@ async function main() {
 }
 
 main().catch(error => {
-  console.error(error.message)
+  console.error(error.result?.stderr?.trim() || error.message)
   process.exitCode = 1
 })

package/lib/setup.js

@@ -0,0 +1,316 @@
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { runProcess } from './process.js'
+
+export const DSH_VERSION = '0.1.0-rc.6'
+
+const packageJson = JSON.parse(
+  await readFile(new URL('../package.json', import.meta.url), 'utf8'),
+)
+
+export const INTEGRATION_VERSION = packageJson.version
+
+function requireValue(args, index, flag) {
+  const value = args[index + 1]
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`)
+  return value
+}
+
+export function parseSetupArgs(args) {
+  const options = {}
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index]
+    if (flag === '--help' || flag === '-h') {
+      options.help = true
+      continue
+    }
+    if (flag === '--profile') options.profile = requireValue(args, index++, flag)
+    else if (flag === '--project-root') options.projectRoot = requireValue(args, index++, flag)
+    else if (flag === '--jobs-dir') options.jobsDir = requireValue(args, index++, flag)
+    else if (flag === '--dsh-home') options.dshHome = requireValue(args, index++, flag)
+    else if (flag === '--runtime-dir') options.runtimeDir = requireValue(args, index++, flag)
+    else if (flag === '--plugin-spec') options.pluginSpec = requireValue(args, index++, flag)
+    else if (flag === '--python-spec') options.pythonSpec = requireValue(args, index++, flag)
+    else throw new Error(`Unknown setup option: ${flag}`)
+  }
+  return options
+}
+
+function executableInVenv(venvDir, name, platform) {
+  return platform === 'win32'
+    ? path.join(venvDir, 'Scripts', `${name}.exe`)
+    : path.join(venvDir, 'bin', name)
+}
+
+function assertSafeProfile(profile) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(profile)) {
+    throw new Error('profile may contain only letters, numbers, dot, underscore, and hyphen')
+  }
+}
+
+function assertJobsDir(projectRoot, jobsDir) {
+  if (!jobsDir) throw new Error('jobsDir cannot be empty')
+  const root = path.resolve(projectRoot)
+  const resolved = path.resolve(root, jobsDir)
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+    throw new Error('jobsDir must stay under projectRoot')
+  }
+}
+
+export function resolveSetupOptions(raw = {}, environment = {}) {
+  const env = environment.env ?? process.env
+  const cwd = environment.cwd ?? process.cwd()
+  const home = environment.home ?? os.homedir()
+  const platform = environment.platform ?? process.platform
+  const profile = raw.profile ?? 'web'
+  const projectRoot = path.resolve(cwd, raw.projectRoot ?? '.')
+  const dataHome = env.XDG_DATA_HOME
+    ? path.resolve(env.XDG_DATA_HOME)
+    : path.join(home, '.local', 'share')
+  const dshHome = path.resolve(raw.dshHome ?? env.DSH_HOME ?? path.join(home, '.dsh'))
+  const runtimeDir = path.resolve(raw.runtimeDir ?? path.join(dataHome, 'harbor-dsh-evolution'))
+  const jobsDir = raw.jobsDir ?? 'jobs'
+  const venvDir = path.join(runtimeDir, '.venv')
+
+  assertSafeProfile(profile)
+  assertJobsDir(projectRoot, jobsDir)
+
+  return {
+    profile,
+    projectRoot,
+    jobsDir,
+    dshHome,
+    runtimeDir,
+    venvDir,
+    pythonBin: executableInVenv(venvDir, 'python', platform),
+    harborBin: executableInVenv(venvDir, 'harbor', platform),
+    harborDshBin: executableInVenv(venvDir, 'harbor-dsh', platform),
+    patchFile: path.join(dshHome, 'profiles', profile, 'cordis.patch.yml'),
+    pluginSpec: raw.pluginSpec ?? `dsh-harbor-evolution@${INTEGRATION_VERSION}`,
+    pythonSpec: raw.pythonSpec ?? `harbor-dsh-evolution==${INTEGRATION_VERSION}`,
+  }
+}
+
+export async function resolveLocalPluginDirectory(pluginSpec, cwd = process.cwd()) {
+  let candidate
+  if (pluginSpec.startsWith('file://')) candidate = fileURLToPath(pluginSpec)
+  else if (pluginSpec.startsWith('file:')) candidate = path.resolve(cwd, pluginSpec.slice(5))
+  else if (!pluginSpec.startsWith('github:') && !pluginSpec.startsWith('git+')) {
+    candidate = path.resolve(cwd, pluginSpec)
+  }
+  if (!candidate) return undefined
+
+  try {
+    const details = await stat(candidate)
+    if (!details.isDirectory()) return undefined
+    const manifest = JSON.parse(await readFile(path.join(candidate, 'package.json'), 'utf8'))
+    return manifest.name === 'dsh-harbor-evolution' ? candidate : undefined
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return undefined
+    throw error
+  }
+}
+
+function quoted(value) {
+  return JSON.stringify(value)
+}
+
+export function renderHarborProfileEntry(config) {
+  return [
+    '- id: harbor-evolution',
+    '  config:',
+    `    projectRoot: ${quoted(config.projectRoot)}`,
+    `    jobsDir: ${quoted(config.jobsDir)}`,
+    `    harborBin: ${quoted(config.harborBin)}`,
+    `    harborDshBin: ${quoted(config.harborDshBin)}`,
+    '    pythonPath: ""',
+  ].join('\n')
+}
+
+export function upsertHarborProfileEntry(source, config) {
+  const entry = renderHarborProfileEntry(config)
+  const lines = source.replace(/\r\n/g, '\n').split('\n')
+  const starts = []
+  for (let index = 0; index < lines.length; index += 1) {
+    if (/^- id:\s*["']?harbor-evolution["']?\s*$/.test(lines[index])) starts.push(index)
+  }
+  if (starts.length > 1) {
+    throw new Error('cordis.patch.yml contains multiple harbor-evolution entries; remove duplicates first')
+  }
+
+  if (starts.length === 1) {
+    const start = starts[0]
+    let end = lines.length
+    for (let index = start + 1; index < lines.length; index += 1) {
+      if (/^- \S/.test(lines[index])) {
+        end = index
+        break
+      }
+    }
+    lines.splice(start, end - start, ...entry.split('\n'))
+    return `${lines.join('\n').replace(/\n+$/g, '')}\n`
+  }
+
+  const emptyArrayIndex = lines.findIndex(line => line.trim() === '[]')
+  const payload = lines.filter(line => line.trim() && !line.trim().startsWith('#'))
+  if (emptyArrayIndex >= 0 && payload.length === 1) {
+    lines.splice(emptyArrayIndex, 1, ...entry.split('\n'))
+    return `${lines.join('\n').replace(/\n+$/g, '')}\n`
+  }
+
+  const current = lines.join('\n').replace(/\n+$/g, '')
+  return `${current ? `${current}\n` : ''}${entry}\n`
+}
+
+async function writeProfilePatch(file, config) {
+  let source
+  try {
+    source = await readFile(file, 'utf8')
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+    source = [
+      '# Harbor Self-Evolving profile overrides.',
+      '# This file is applied after the DSH bundle layers.',
+      '[]',
+      '',
+    ].join('\n')
+  }
+  const updated = upsertHarborProfileEntry(source, config)
+  if (updated === source) return false
+
+  await mkdir(path.dirname(file), { recursive: true })
+  const temporary = `${file}.${process.pid}.tmp`
+  await writeFile(temporary, updated, 'utf8')
+  await rename(temporary, file)
+  return true
+}
+
+async function assertDirectory(directory) {
+  let details
+  try {
+    details = await stat(directory)
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`projectRoot does not exist: ${directory}`)
+    throw error
+  }
+  if (!details.isDirectory()) throw new Error(`projectRoot is not a directory: ${directory}`)
+}
+
+async function requireCommand(run, command) {
+  try {
+    return await run(command, ['--version'], { timeoutMs: 10_000 })
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.cause?.code === 'ENOENT') {
+      throw new Error(`Missing ${command}; install it before running setup`)
+    }
+    throw error
+  }
+}
+
+function processFailure(error) {
+  const detail = error.result?.stderr?.trim() || error.result?.stdout?.trim()
+  return detail ? `${error.message}\n${detail}` : error.message
+}
+
+export async function setupIntegration(raw = {}, dependencies = {}) {
+  const config = resolveSetupOptions(raw, dependencies)
+  const run = dependencies.run ?? runProcess
+  const progress = dependencies.onProgress ?? (() => {})
+  const env = dependencies.env ?? process.env
+  const warnings = []
+
+  const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10)
+  if (nodeMajor < 22) throw new Error(`Node.js 22 or newer is required; found ${process.version}`)
+  await assertDirectory(config.projectRoot)
+
+  progress('1/4 Checking uv, pnpm, and Docker...')
+  await requireCommand(run, 'uv')
+  await requireCommand(run, 'pnpm')
+  try {
+    await run('docker', ['info'], { timeoutMs: 15_000 })
+  } catch (error) {
+    warnings.push(`Docker is not ready; installation can finish, but Harbor Jobs will fail until it is available. ${processFailure(error)}`)
+  }
+
+  const localPluginDir = await resolveLocalPluginDirectory(
+    config.pluginSpec,
+    dependencies.cwd ?? process.cwd(),
+  )
+  if (localPluginDir) {
+    progress('Preparing dependencies for the linked DSH plugin checkout...')
+    await requireCommand(run, 'npm')
+    // Node resolves a symlinked package from its real checkout path. Install
+    // the complete locked graph there so runtime dependencies and host peers
+    // do not disappear behind the profile's `link:` entry.
+    await run('npm', ['ci', '--ignore-scripts'], { cwd: localPluginDir })
+  }
+
+  progress('2/4 Installing the Harbor Python runtime...')
+  await mkdir(config.runtimeDir, { recursive: true })
+  await run('uv', ['venv', '--python', '3.12', '--allow-existing', config.venvDir])
+  await run('uv', [
+    'pip', 'install',
+    '--python', config.pythonBin,
+    '--refresh-package', 'harbor-dsh-evolution',
+    config.pythonSpec,
+  ])
+
+  progress(`3/4 Installing the DSH bundle into profile ${config.profile}...`)
+  try {
+    await run('pnpm', [
+      '--silent', 'dlx', `@deepseek-ai/dsh@${DSH_VERSION}`,
+      'plugin', '--profile', config.profile, 'add', '-w', '--save-exact', config.pluginSpec,
+    ], { env: { ...env, DSH_HOME: config.dshHome } })
+  } catch (error) {
+    throw new Error(processFailure(error))
+  }
+
+  progress('4/4 Saving paths and verifying the integration...')
+  const patchChanged = await writeProfilePatch(config.patchFile, config)
+  const harborVersion = await run(config.harborBin, ['--version'], { timeoutMs: 10_000 })
+  const plugins = await run(config.harborBin, ['plugins', 'list'], { timeoutMs: 10_000 })
+  if (!plugins.stdout.includes('dsh-evolution')) {
+    throw new Error('Harbor installed, but its dsh-evolution plugin entry point was not discovered')
+  }
+  await run(config.harborDshBin, ['--help'], { timeoutMs: 10_000 })
+
+  return {
+    ...config,
+    localPluginDir,
+    patchChanged,
+    harborVersion: harborVersion.stdout.trim() || harborVersion.stderr.trim(),
+    warnings,
+  }
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`
+}
+
+export function renderSetupResult(result) {
+  const startCommand = result.profile === 'web'
+    ? `DSH_HOME=${shellQuote(result.dshHome)} pnpm dlx @deepseek-ai/dsh@${DSH_VERSION} web`
+    : `DSH_HOME=${shellQuote(result.dshHome)} pnpm dlx @deepseek-ai/dsh@${DSH_VERSION} --profile ${shellQuote(result.profile)}`
+  const lines = [
+    '',
+    `Installed Harbor Self-Evolving ${INTEGRATION_VERSION}.`,
+    `DSH profile: ${result.profile}`,
+    `Project root: ${result.projectRoot}`,
+    `Profile config: ${result.patchFile}`,
+    `Harbor: ${result.harborVersion}`,
+  ]
+  for (const warning of result.warnings) lines.push(`Warning: ${warning}`)
+  lines.push(
+    '',
+    'Restart DSH from the Agent workspace:',
+    `cd ${shellQuote(result.projectRoot)}`,
+    startCommand,
+    '',
+    'Then invoke: /evolve-agent-with-harbor',
+  )
+  return lines.join('\n')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-harbor-evolution",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "DeepSeek Harness plugin and bundled Skill for safely evolving Cordis Candidates with Harbor.",
   "type": "module",
   "main": "index.js",