@tiphareth/dsh-hardssh 0.1.2-alpha

package/src/protocol.ts

@@ -0,0 +1,114 @@
+/**
+ * Wire contract between the host half (routes.ts) and the browser half
+ * (client/api.ts). Pure types only — imported by both halves, bundled into
+ * each, no runtime identity to share.
+ */
+
+/** The two workspace modes of the plugin. */
+export type WorkspaceMode = 'local' | 'remote'
+
+/** The plugin's mode state (host-owned singleton). */
+export interface WorkspaceState {
+  /** Current mode: local = this machine, remote = an SSH host. */
+  mode: WorkspaceMode
+  /** Active SSH host alias (kept while in local mode so the toggle can return). */
+  alias?: string
+  /** Resolved absolute remote root (the workspace gate prefix). */
+  remoteRoot?: string
+  /** Human label of the remote root ('~' when the default home was resolved). */
+  remoteRootLabel?: string
+}
+
+/** One directory entry (both backends normalize to this shape). */
+export interface WorkspaceEntry {
+  name: string
+  type: 'dir' | 'file' | 'other'
+  size: number
+  mtimeMs: number
+}
+
+/** Directory listing response. */
+export interface DirListing {
+  /** The listed absolute path. */
+  path: string
+  entries: WorkspaceEntry[]
+}
+
+/** File read response (text only; binary/oversize is rejected with an error). */
+export interface FileRead {
+  path: string
+  content: string
+  size: number
+  mtime: number
+}
+
+/** File write response (new mtime for the UI's conflict tracking). */
+export interface FileWriteResult {
+  mtime: number
+}
+
+/** One filename-search hit. */
+export interface SearchHit {
+  /** Absolute path. */
+  path: string
+  /** Path relative to the search root. */
+  rel: string
+  isDir: boolean
+}
+
+/** Filename-search response. */
+export interface SearchView {
+  query: string
+  hits: SearchHit[]
+  truncated: boolean
+}
+
+/** JSON error body used by every route. */
+export interface ApiErrorBody {
+  error: string
+}
+
+/** Route paths the client calls (shared literals). */
+export const WORKSPACE_API_BASE = '/api/dsh-hardssh' as const
+
+export const WORKSPACE_API = {
+  state: WORKSPACE_API_BASE + '/state',
+  tree: WORKSPACE_API_BASE + '/tree',
+  file: WORKSPACE_API_BASE + '/file',
+  search: WORKSPACE_API_BASE + '/search',
+  sshWorkspaces: WORKSPACE_API_BASE + '/ws',
+  sshWorkspaceDir: WORKSPACE_API_BASE + '/ws/dir',
+} as const
+
+/**
+ * One SSH-bound workspace: a local anchor directory (the host-visible
+ * workspace path, which sessions use as their cwd) bound to a directory on
+ * an SSH host. The fs/subprocess seams route by the anchor path: a session
+ * whose cwd is this anchor operates on the REMOTE directory; everything else
+ * stays local.
+ */
+export interface SshWorkspaceRecord {
+  /** Stable id (uuid). */
+  id: string
+  /** Display title (sidebar). */
+  title: string
+  /** SSH host alias (dsh-ssh host store). */
+  alias: string
+  /** Resolved absolute remote root (the remote directory to operate in). */
+  remoteRoot: string
+  /** Local anchor directory (host workspace path / session cwd). */
+  anchorPath: string
+  /** When the record was created. */
+  createdAt: string
+}
+
+/** The ledger of SSH-bound workspaces (persisted by the host). */
+export type SshWorkspaceLedger = SshWorkspaceRecord[]
+
+/** One remote directory entry for the picker tree. */
+export interface RemoteDirEntry {
+  name: string
+  type: 'dir' | 'file' | 'other'
+  size: number
+  mtimeMs: number
+}

package/src/providers/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Registry of every built-in provider. The DSH runtime (and any consumer)
+ * uses this to mount local + ssh providers; third-party providers register
+ * the same way through the base plugin API.
+ *
+ * @module @tiphareth/dsh-hardssh/providers
+ */
+
+import type { WorkspaceProvider } from '../base/model.ts'
+import type { WorkspaceProviderRegistry } from '../base/registry.ts'
+import type { SshEngine } from '../ssh/engine.ts'
+import type { HostStoreView } from '../core.ts'
+import { createSshWorkspaceProvider } from './ssh/provider.ts'
+import { createLocalWorkspaceProvider } from './local/provider.ts'
+
+/** Register both built-in providers. Returns per-provider disposers. */
+export function registerBuiltinProviders(
+  registry: WorkspaceProviderRegistry,
+  deps: { engine?: SshEngine; hosts?: HostStoreView } = {},
+): Array<() => void> {
+  const disposers: Array<() => void> = []
+  // Local first: always available, no external state.
+  disposers.push(registry.register(createLocalWorkspaceProvider()))
+  // SSH requires the engine; when absent (headless / partial load) it is
+  // simply not registered — the base keeps working for local workspaces.
+  if (deps.engine !== undefined) {
+    disposers.push(registry.register(createSshWorkspaceProvider(deps.engine)))
+  }
+  return disposers
+}
+
+/** The canonical provider ids. */
+export const BUILTIN_PROVIDER_IDS = ['local', 'ssh'] as const
+export type BuiltinProviderId = (typeof BUILTIN_PROVIDER_IDS)[number]

package/src/providers/local/provider.ts

@@ -0,0 +1,179 @@
+/**
+ * Local provider — the workspace provider for local-disk workspaces. Direct
+ * Node fs implementation of `WorkspaceFileSystem`, so the local provider is
+ * usable OUTSIDE the dsh harness too (a consumer only needs `base`).
+ *
+ * The DSH runtime later re-wraps this over `dsh-fs-sandbox` / `dsh-fs-local`
+ * for sandbox semantics when running inside the harness; the base contract
+ * stays identical.
+ *
+ * @module @tiphareth/dsh-hardssh/providers/local
+ */
+
+import { constants as fsConstants } from 'node:fs'
+import { access, lstat as fsLstat, mkdir, readFile, readdir, rename, rm, stat as fsStat, writeFile } from 'node:fs/promises'
+import { basename, join, parse as parsePath, resolve as resolvePath } from 'node:path'
+import type {
+  WorkspaceCapabilityMap,
+  WorkspaceConnection,
+  WorkspaceOpenContext,
+  WorkspaceProvider,
+  WorkspaceProviderManifest,
+  WorkspaceRecord,
+} from '../../base/model.ts'
+import type {
+  WorkspaceDirEntry,
+  WorkspaceFileSystem,
+  WorkspaceStat,
+} from '../../base/capability.ts'
+
+/** The local provider manifest. */
+export const localProviderManifest: WorkspaceProviderManifest = {
+  id: 'local',
+  version: '0.1.0',
+  apiVersion: 1,
+  displayName: 'Local disk workspace',
+  capabilities: ['workspace.fs'],
+}
+
+/** One open local workspace connection. */
+export class LocalWorkspaceConnection implements WorkspaceConnection {
+  readonly providerId = 'local'
+
+  constructor(
+    readonly workspaceId: string,
+    private readonly root: string,
+  ) {}
+
+  get<K extends keyof WorkspaceCapabilityMap>(capability: K): WorkspaceCapabilityMap[K] | undefined {
+    if (capability === 'workspace.fs') return new LocalWorkspaceFileSystem(this.root) as unknown as WorkspaceCapabilityMap[K]
+    return undefined
+  }
+
+  status(): 'connecting' | 'ready' | 'degraded' | 'closed' {
+    return 'ready'
+  }
+
+  async close(): Promise<void> {
+    // Nothing to release (no pool, no leases).
+  }
+}
+
+/**
+ * Node-fs implementation of `WorkspaceFileSystem` confined to a root.
+ * Workspace-relative paths (`/src/index.ts`, `src/index.ts`) are resolved
+ * against the root; `..` escapes are rejected; symlinks are not followed
+ * out of the root by the stat path (defense in depth — the contract says
+ * the provider enforces confinement).
+ */
+export class LocalWorkspaceFileSystem implements WorkspaceFileSystem {
+  constructor(private readonly root: string) {}
+
+  /** Resolve a workspace-relative path into an absolute path inside root. */
+  private abs(path: string): string {
+    if (path.startsWith('\\') || path.startsWith('/')) path = path.slice(1)
+    const absolute = resolvePath(this.root, path)
+    const normalized = resolvePath(this.root)
+    if (absolute !== normalized && !absolute.startsWith(normalized + (parsePath(normalized).root === normalized ? '' : '/')) && !absolute.startsWith(normalized + '\\')) {
+      // Allow exact root and descendants only.
+      if (!absolute.startsWith(normalized + '/') && !absolute.startsWith(normalized + '\\')) {
+        throw new Error(`path escapes workspace root: '${path}'`)
+      }
+    }
+    return absolute
+  }
+
+  async stat(path: string, signal?: AbortSignal): Promise<WorkspaceStat | undefined> {
+    const absolute = this.abs(path)
+    try {
+      const info = await fsStat(absolute)
+      return toStat(info)
+    } catch {
+      return undefined
+    }
+  }
+
+  async list(path: string, signal?: AbortSignal): Promise<WorkspaceDirEntry[]> {
+    const absolute = this.abs(path)
+    const names = await readdir(absolute)
+    const entries: WorkspaceDirEntry[] = []
+    for (const name of names) {
+      const child = join(absolute, name)
+      try {
+        const info = await fsLstat(child)
+        entries.push({
+          name,
+          type: info.isDirectory() ? 'dir' : info.isFile() ? 'file' : 'other',
+          size: info.size,
+          mtimeMs: info.mtimeMs,
+        })
+      } catch {
+        // Unreadable entry: skip rather than fail the whole listing.
+      }
+    }
+    return entries
+  }
+
+  async readFile(path: string, signal?: AbortSignal): Promise<Uint8Array> {
+    return readFile(this.abs(path))
+  }
+
+  async writeFile(path: string, data: Uint8Array, signal?: AbortSignal): Promise<void> {
+    await writeFile(this.abs(path), data)
+  }
+
+  async mkdir(path: string, options?: { recursive?: boolean; signal?: AbortSignal }): Promise<void> {
+    await mkdir(this.abs(path), { recursive: options?.recursive ?? false })
+  }
+
+  async rm(path: string, options?: { recursive?: boolean; signal?: AbortSignal }): Promise<void> {
+    await rm(this.abs(path), { recursive: options?.recursive ?? false, force: false })
+  }
+
+  async rename(from: string, to: string, signal?: AbortSignal): Promise<void> {
+    await rename(this.abs(from), this.abs(to))
+  }
+
+  /** Convenience: check the root exists and is readable (for open()). */
+  async accessible(): Promise<boolean> {
+    try {
+      await access(this.root, fsConstants.R_OK)
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+/** Convert fs.StatFs into the uniform WorkspaceStat. */
+function toStat(info: { isDirectory(): boolean; isFile(): boolean; size: number; mtimeMs: number; mode: number }): WorkspaceStat {
+  return {
+    type: info.isDirectory() ? 'dir' : info.isFile() ? 'file' : 'other',
+    size: info.size,
+    mtimeMs: info.mtimeMs,
+    mode: info.mode,
+  }
+}
+
+/** The local provider factory. */
+export function createLocalWorkspaceProvider(): WorkspaceProvider {
+  return {
+    manifest: localProviderManifest,
+    validate(record: WorkspaceRecord): void {
+      if (record.provider.id !== 'local') throw new Error('not a local workspace record')
+      if (record.location.root === '') throw new Error('local workspace record is missing location.root')
+    },
+    async open(record: WorkspaceRecord, context?: WorkspaceOpenContext): Promise<WorkspaceConnection> {
+      const fs = new LocalWorkspaceFileSystem(record.location.root)
+      if (!(await fs.accessible())) {
+        context?.logger?.warn?.('local workspace root is not accessible:', record.location.root)
+      }
+      return new LocalWorkspaceConnection(record.id, record.location.root)
+    },
+  }
+}
+
+/** Helper: title mostly used by record factories. */
+export function localDefaultTitle(root: string): string {
+  return basename(root) || root
+}

package/src/providers/ssh/provider.ts

@@ -0,0 +1,274 @@
+/**
+ * SSH provider — wraps the SSH engine/host store as a generic
+ * `WorkspaceProvider`, so the workspace base can route SSH-bound workspaces
+ * without knowing anything about ssh2. This is the concrete "provider-ssh"
+ * layer: everything SSH lives here (or in the legacy ./ssh, ./remote
+ * modules it adapts), and the base + runtime never import it directly by
+ * type.
+ *
+ * A record with `provider.id === 'ssh'` maps:
+ * - `provider.connectionRef.id` → HostStore alias
+ * - `location.root` → the remote root directory
+ * - `anchor.path` → the local anchor (session-visible)
+ *
+ * @module @tiphareth/dsh-hardssh/providers/ssh
+ */
+
+import type {
+  WorkspaceCapabilityMap,
+  WorkspaceConnection,
+  WorkspaceOpenContext,
+  WorkspaceProvider,
+  WorkspaceProviderManifest,
+  WorkspaceRecord,
+} from '../../base/model.ts'
+import type {
+  WorkspaceFileSystem,
+  WorkspaceProcessRuntime,
+  WorkspaceSearchService,
+  WorkspaceStat,
+  WorkspaceTerminalService,
+  WorkspaceDirEntry,
+  WorkspaceSearchHit,
+} from '../../base/capability.ts'
+import type { SshEngine } from '../../ssh/engine.ts'
+import { RemoteSearchService } from '../../remote-search.ts'
+
+/** The ssh provider manifest. */
+export const sshProviderManifest: WorkspaceProviderManifest = {
+  id: 'ssh',
+  version: '0.1.0',
+  apiVersion: 1,
+  displayName: 'SSH remote workspace',
+  capabilities: ['workspace.fs', 'workspace.process', 'workspace.terminal', 'workspace.search'],
+}
+
+/** One open SSH workspace connection. */
+export class SshWorkspaceConnection implements WorkspaceConnection {
+  readonly providerId = 'ssh'
+
+  constructor(
+    readonly workspaceId: string,
+    private readonly engine: SshEngine,
+    private readonly alias: string,
+    private readonly remoteRoot: string,
+  ) {}
+
+  get<K extends keyof WorkspaceCapabilityMap>(capability: K): WorkspaceCapabilityMap[K] | undefined {
+    switch (capability) {
+      case 'workspace.fs': return this.fs() as WorkspaceCapabilityMap[K]
+      case 'workspace.process': return this.process() as WorkspaceCapabilityMap[K]
+      case 'workspace.terminal': return this.terminal() as WorkspaceCapabilityMap[K]
+      case 'workspace.search': return this.search() as WorkspaceCapabilityMap[K]
+      default: return undefined
+    }
+  }
+
+  private fs(): WorkspaceFileSystem {
+    return new SshWorkspaceFileSystem(this.engine, this.alias, this.remoteRoot)
+  }
+
+  private process(): WorkspaceProcessRuntime {
+    return new SshWorkspaceProcess(this.engine, this.alias, this.remoteRoot)
+  }
+
+  private terminal(): WorkspaceTerminalService {
+    return new SshWorkspaceTerminal(this.engine, this.alias, this.remoteRoot)
+  }
+
+  private search(): WorkspaceSearchService {
+    return new SshWorkspaceSearch(this.engine, this.alias, this.remoteRoot)
+  }
+
+  status(): 'connecting' | 'ready' | 'degraded' | 'closed' {
+    // The engine owns the connection pool; a resolved workspace whose host
+    // is configured is treated as ready (connectivity is verified lazily by
+    // the exec/search calls, which report degraded results).
+    return 'ready'
+  }
+
+  async close(): Promise<void> {
+    // The engine owns the shared connection pool; per-workspace close is a
+    // no-op here (pool invalidation is host-store driven).
+  }
+}
+
+/** POSIX-join a remote root with a relative path, confining to the root. */
+export function joinRemoteRoot(root: string, path: string): string {
+  if (path.startsWith('/')) {
+    // Absolute path must still be under the root? SSH workspaces allow
+    // arbitrary absolute remote paths (the root is the model's own habit,
+    // not a sandbox). Keep absolute paths verbatim for the SSH provider.
+    return root === '/' ? path : path
+  }
+  const base = root === '/' ? '' : root
+  return `${base}/${path}`.replace(/\/{2,}/g, '/')
+}
+
+/** Wrap engine FS calls as the generic WorkspaceFileSystem. */
+export class SshWorkspaceFileSystem implements WorkspaceFileSystem {
+  constructor(
+    private readonly engine: SshEngine,
+    private readonly alias: string,
+    private readonly root: string,
+  ) {}
+
+  private full(path: string): string {
+    return joinRemoteRoot(this.root, path)
+  }
+
+  async stat(path: string, signal?: AbortSignal): Promise<WorkspaceStat | undefined> {
+    const result = await this.engine.stat(this.alias, this.full(path))
+    return { type: result.type, size: result.size, mtimeMs: result.mtimeMs, mode: result.mode }
+  }
+
+  async list(path: string, signal?: AbortSignal): Promise<WorkspaceDirEntry[]> {
+    return this.engine.ls(this.alias, this.full(path))
+  }
+
+  async readFile(path: string, signal?: AbortSignal): Promise<Uint8Array> {
+    const { content } = await this.engine.readFile(this.alias, this.full(path))
+    return content
+  }
+
+  async writeFile(path: string, data: Uint8Array, signal?: AbortSignal): Promise<void> {
+    await this.engine.writeFile(this.alias, this.full(path), Buffer.from(data))
+  }
+
+  async mkdir(path: string, options?: { recursive?: boolean; signal?: AbortSignal }): Promise<void> {
+    await this.engine.mkdir(this.alias, this.full(path))
+  }
+
+  async rm(path: string, options?: { recursive?: boolean; signal?: AbortSignal }): Promise<void> {
+    await this.engine.rm(this.alias, this.full(path), options?.recursive ?? false)
+  }
+
+  async rename(from: string, to: string, signal?: AbortSignal): Promise<void> {
+    await this.engine.rename(this.alias, this.full(from), this.full(to))
+  }
+}
+
+/** Wrap engine exec as the generic WorkspaceProcessRuntime. */
+export class SshWorkspaceProcess implements WorkspaceProcessRuntime {
+  constructor(
+    private readonly engine: SshEngine,
+    private readonly alias: string,
+    private readonly root: string,
+  ) {}
+
+  async exec(command: string, options?: { timeoutMs?: number; cwd?: string; signal?: AbortSignal }): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut?: boolean; durationMs?: number }> {
+    const cwd = options?.cwd !== undefined ? this.full(options.cwd) : this.root
+    // cd into the resolved cwd (relative paths resolved against the root).
+    const result = await this.engine.exec(this.alias, `cd ${quote(cwd)} && ${command}`, options?.timeoutMs)
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode ?? 1,
+      timedOut: result.timedOut,
+      durationMs: result.durationMs,
+    }
+  }
+
+  private full(path: string): string {
+    return joinRemoteRoot(this.root, path)
+  }
+}
+
+/** Wrap engine PTY as the generic WorkspaceTerminalService. */
+export class SshWorkspaceTerminal implements WorkspaceTerminalService {
+  constructor(
+    private readonly engine: SshEngine,
+    private readonly alias: string,
+    private readonly root: string,
+  ) {}
+
+  async openTerminal(cols: number, rows: number): Promise<import('../../base/capability.ts').WorkspaceTerminalHandle> {
+    const session = await this.engine.openShell(this.alias, { cols, rows })
+    let exited = false
+    const exitHandlers = new Set<(event: { exitCode: number }) => void>()
+    const onDataHandlers = new Set<(data: string) => void>()
+    const enc = new TextDecoder()
+    session.onData = (data: Buffer) => {
+      for (const handler of onDataHandlers) handler(enc.decode(data))
+    }
+    session.onExit = (code: number | null) => {
+      exited = true
+      for (const handler of exitHandlers) handler({ exitCode: code ?? -1 })
+    }
+    return {
+      shell: 'ssh',
+      write(data: string) { if (!exited) session.send(data) },
+      resize(c: number, r: number) { session.resize(c, r) },
+      kill() {
+        try { session.signal('KILL') } catch { /* closed */ }
+        try { session.close() } catch { /* closed */ }
+      },
+      onData(handler) {
+        onDataHandlers.add(handler)
+        return { dispose: () => { onDataHandlers.delete(handler) } }
+      },
+      onExit(handler) {
+        exitHandlers.add(handler)
+        return { dispose: () => { exitHandlers.delete(handler) } }
+      },
+    }
+  }
+}
+
+/** Wrap the remote search service as the generic WorkspaceSearchService. */
+export class SshWorkspaceSearch implements WorkspaceSearchService {
+  private readonly service: RemoteSearchService
+
+  constructor(
+    private readonly engine: SshEngine,
+    private readonly alias: string,
+    private readonly root: string,
+  ) {
+    this.service = new RemoteSearchService(engine)
+  }
+
+  async glob(pattern: string, options?: { root?: string; maxDepth?: number; signal?: AbortSignal }): Promise<{ hits: WorkspaceSearchHit[]; truncated: boolean }> {
+    const result = await this.service.glob({ alias: this.alias, root: this.root }, pattern)
+    return {
+      hits: result.hits.map(path => ({ path, rel: path, isDir: false })),
+      truncated: result.truncated,
+    }
+  }
+
+  async grep(fixedPhrase: string, options?: { root?: string; signal?: AbortSignal }): Promise<{ hits: WorkspaceSearchHit[]; truncated: boolean }> {
+    const result = await this.service.grepFixed({ alias: this.alias, root: this.root }, fixedPhrase)
+    return {
+      hits: result.lines.map(line => {
+        const colon = line.indexOf(':')
+        const path = colon >= 0 ? line.slice(0, colon) : line
+        return { path, rel: path, isDir: false }
+      }),
+      truncated: result.truncated,
+    }
+  }
+}
+
+/** The ssh provider factory. */
+export function createSshWorkspaceProvider(engine: SshEngine): WorkspaceProvider {
+  return {
+    manifest: sshProviderManifest,
+    validate(record: WorkspaceRecord): void {
+      if (record.provider.id !== 'ssh') throw new Error('not an ssh workspace record')
+      if (record.provider.connectionRef === undefined || record.provider.connectionRef.id === '') {
+        throw new Error('ssh workspace record is missing provider.connectionRef.id (host alias)')
+      }
+      if (record.location.root === '') throw new Error('ssh workspace record is missing location.root')
+    },
+    async open(record: WorkspaceRecord, context?: WorkspaceOpenContext): Promise<WorkspaceConnection> {
+      const alias = record.provider.connectionRef!.id
+      return new SshWorkspaceConnection(record.id, engine, alias, record.location.root)
+    },
+  }
+}
+
+/** POSIX single-quote a shell argument. */
+function quote(arg: string): string {
+  if (arg === '') return "''"
+  if (/^[a-zA-Z0-9_\-./:=@]+$/.test(arg)) return arg
+  return `'${arg.replace(/'/g, `'\\''`)}'`
+}