@tiphareth/dsh-hardssh 0.1.2

package/src/base/plugin.ts

@@ -0,0 +1,170 @@
+/**
+ * Plugin registration / distribution — the extension contract that lets ANY
+ * third-party plugin (not just SSH) contribute workspace capability.
+ *
+ * Two plugin kinds share one manifest+activate shape:
+ * - **Provider plugins** register `WorkspaceProvider`s (local, ssh, docker,
+ *   wsl, cloud devbox, …) through the plugin context.
+ * - **Feature plugins** attach provider-agnostic features (indexing, audit
+ *   tools, diagnostics, UI) to workspaces that expose the capabilities they
+ *   need — without importing any provider implementation.
+ *
+ * DSH-specific surfaces (agent tools, routes, prompt sections, client
+ * entries) are contributed through the runtime bridge, never through this
+ * core contract, so `base` stays free of Cordis/React.
+ *
+ * @module @tiphareth/dsh-hardssh/base/plugin
+ */
+
+import type { WorkspaceProvider, WorkspaceRecord } from './model.ts'
+import type { WorkspaceRegistry } from './registry.ts'
+
+/** A disposable registration handle. */
+export interface Disposable {
+  dispose(): void
+}
+
+/** Static plugin identity, readable before any plugin code executes. */
+export interface WorkspacePluginManifest {
+  /** Stable plugin id (dotted, reverse-dns style recommended). */
+  id: string
+  version: string
+  /** Compatibility gate; aligned with the base API major. */
+  apiVersion: number
+  displayName: string
+  /** What this plugin contributes (for capability gating / UI). */
+  contributes?: {
+    providers?: string[]
+    features?: string[]
+    clientEntries?: string[]
+  }
+}
+
+/** Context handed to a plugin's `activate`. */
+export interface WorkspacePluginContext {
+  /** Register one provider; returns a disposer. */
+  registerProvider(provider: WorkspaceProvider): Disposable
+  /** Register one provider-agnostic feature. */
+  registerFeature(feature: WorkspaceFeature): Disposable
+  /** The shared workspace registry (list / watch workspaces). */
+  workspaces: WorkspaceRegistry
+  /** Fired when a workspace record changes (for feature lifecycle). */
+  onWorkspaceChange(listener: (workspace: WorkspaceRecord) => void): Disposable
+}
+
+/** A provider-agnostic feature attached to compatible workspaces. */
+export interface WorkspaceFeature {
+  id: string
+  /** True when this feature wants the given workspace (capability gating). */
+  supports(input: {
+    workspace: WorkspaceRecord
+    capabilities: ReadonlySet<string>
+  }): boolean
+  /** Called once per compatible workspace while the feature is active. */
+  activate(context: WorkspaceFeatureContext): void | Promise<void>
+  deactivate?(): void | Promise<void>
+}
+
+/** Feature context: per-workspace connection + lifecycle. */
+export interface WorkspaceFeatureContext {
+  workspace: WorkspaceRecord
+  /** Open connection; undefined only if the provider failed to open. */
+  connection: import('./model.ts').WorkspaceConnection | undefined
+  /** Mark the feature unusable for this workspace (degrades gracefully). */
+  unavailable(): void
+}
+
+/** The full plugin shape: static manifest + activate. */
+export interface WorkspacePlugin {
+  readonly manifest: WorkspacePluginManifest
+  activate(context: WorkspacePluginContext): void | Promise<void>
+  deactivate?(): void | Promise<void>
+}
+
+/**
+ * Registry of loaded plugins (provider + feature plugins together). Keeps
+ * the workspace registry and plugin lifecycle in one place.
+ */
+export class WorkspacePluginHost {
+  private readonly plugins = new Map<string, WorkspacePlugin>()
+  private readonly features = new Set<WorkspaceFeature>()
+  /** Per-plugin disposers collected from activate (provider/feature/workspace listeners). */
+  private readonly pluginDisposers = new Map<string, Array<() => void>>()
+
+  constructor(
+    private readonly registries: {
+      workspaces: WorkspaceRegistry
+    },
+  ) {}
+
+  /** Load a plugin: validate manifest, run activate. Throws on failure. */
+  async load(plugin: WorkspacePlugin): Promise<void> {
+    if (this.plugins.has(plugin.manifest.id)) {
+      throw new Error(`plugin '${plugin.manifest.id}' already loaded`)
+    }
+    if (plugin.manifest.apiVersion !== 1) {
+      throw new Error(`plugin '${plugin.manifest.id}' apiVersion ${plugin.manifest.apiVersion} is not supported (need 1)`)
+    }
+    const disposers: Array<() => void> = []
+    await plugin.activate({
+      registerProvider: (provider) => {
+        const disposer = this.registerProvider(provider)
+        disposers.push(disposer)
+        return { dispose: disposer }
+      },
+      registerFeature: (feature) => {
+        // Track contributions by plugin so unload tears them down.
+        const disposer = () => { this.features.delete(feature) }
+        disposers.push(disposer)
+        this.features.add(feature)
+        return { dispose: disposer }
+      },
+      workspaces: this.registries.workspaces,
+      onWorkspaceChange: (listener) => {
+        const disposer = this.registries.workspaces.subscribe(listener)
+        disposers.push(disposer)
+        return { dispose: disposer }
+      },
+    })
+    this.pluginDisposers.set(plugin.manifest.id, disposers)
+    this.plugins.set(plugin.manifest.id, plugin)
+  }
+
+  /** Unload a plugin, disposing every contribution (providers, features, listeners). */
+  async unload(id: string): Promise<void> {
+    const plugin = this.plugins.get(id)
+    if (plugin === undefined) return
+    await plugin.deactivate?.()
+    const disposers = this.pluginDisposers.get(id) ?? []
+    for (const dispose of disposers) {
+      try { dispose() } catch { /* disposer isolation */ }
+    }
+    this.pluginDisposers.delete(id)
+    this.plugins.delete(id)
+  }
+
+  private registerProvider(provider: WorkspaceProvider): () => void {
+    // The registry returns a disposer on register; a same-version duplicate
+    // no-ops, so the disposer may be a no-op too — unload still runs it.
+    let disposed = false
+    this.registries.workspaces.register(provider)
+    return () => {
+      if (disposed) return
+      disposed = true
+      this.registries.workspaces.unregister?.(provider.manifest.id)
+    }
+  }
+
+  /** Active features (for a runtime to wire up per-workspace surfaces). */
+  featuresFor(workspace: WorkspaceRecord, capabilities: ReadonlySet<string>): WorkspaceFeature[] {
+    return [...this.features].filter(feature => feature.supports({ workspace, capabilities }))
+  }
+}
+
+/**
+ * Minimal capability set surface used by the DSH runtime to decide which
+ * features apply to a workspace. Computed from the provider manifest.
+ */
+export function capabilitiesOf(provider: WorkspaceProvider): ReadonlySet<string> {
+  return new Set(provider.manifest.capabilities)
+}

package/src/base/registry.ts

@@ -0,0 +1,109 @@
+/**
+ * Workspace provider registry — the single place providers register and are
+ * looked up by id. The registry is provider-agnostic: SSH, local, and any
+ * future provider all register here, and the switch layer resolves
+ * workspaces through the registry without knowing which provider backs them.
+ *
+ * Registration is idempotent per (id, version, apiVersion): re-registering
+ * the same provider is a no-op / reuse; registering a different or
+ * incompatible implementation with the same id is an error.
+ *
+ * @module @tiphareth/dsh-hardssh/base/registry
+ */
+
+import type { WorkspaceProvider, WorkspaceProviderManifest } from './model.ts'
+
+/** Fired when a provider registers (for surface mounts / cache invalidation). */
+export type ProviderListener = (provider: WorkspaceProvider) => void
+
+/** Duplicate / incompatible registration error. */
+export class ProviderRegistrationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ProviderRegistrationError'
+  }
+}
+
+/** In-memory provider registry (process-wide singleton by default). */
+export class WorkspaceProviderRegistry {
+  private readonly providers = new Map<string, WorkspaceProvider>()
+  private readonly listeners = new Set<ProviderListener>()
+
+  /** Register a provider. Throws on id collision with an incompatible impl. */
+  register(provider: WorkspaceProvider): () => void {
+    const id = provider.manifest.id
+    const existing = this.providers.get(id)
+    if (existing !== undefined) {
+      const same = existing.manifest.version === provider.manifest.version
+        && existing.manifest.apiVersion === provider.manifest.apiVersion
+      if (!same) {
+        throw new ProviderRegistrationError(
+          `provider '${id}' already registered (${existing.manifest.version}, api ${existing.manifest.apiVersion}); refusing incompatible duplicate`,
+        )
+      }
+      // Same version: reuse. No-op.
+      return () => { /* already registered */ }
+    }
+    this.providers.set(id, provider)
+    const disposer = () => { this.providers.delete(id) }
+    for (const listener of [...this.listeners]) {
+      try { listener(provider) } catch { /* listener isolation */ }
+    }
+    return disposer
+  }
+
+  /** Look up a provider by id. */
+  get(id: string): WorkspaceProvider | undefined {
+    return this.providers.get(id)
+  }
+
+  /** Unregister a provider by id (no-op when absent or different version). */
+  unregister(id: string): void {
+    if (!this.providers.has(id)) return
+    this.providers.delete(id)
+  }
+
+  /** All registered providers. */
+  list(): WorkspaceProvider[] {
+    return [...this.providers.values()]
+  }
+
+  /** Subscribe to registrations. Returns a disposer. */
+  subscribe(listener: ProviderListener): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /** True when a provider id is registered. */
+  has(id: string): boolean {
+    return this.providers.has(id)
+  }
+
+  /** Static identity of a registered provider (for manifests / UI). */
+  manifestOf(id: string): WorkspaceProviderManifest | undefined {
+    return this.providers.get(id)?.manifest
+  }
+}
+
+/** The process-wide shared registry. */
+export const globalWorkspaceRegistry = new WorkspaceProviderRegistry()
+
+/**
+ * Workspace registry surface used by plugins: list / watch workspace records
+ * and register providers. Implemented by the runtime over the ledger + the
+ * provider registry.
+ */
+export interface WorkspaceRegistry {
+  /** All known workspace records (provider-agnostic). */
+  listWorkspaces(): Promise<import('./model.ts').WorkspaceRecord[]>
+  /** Subscribe to workspace record changes. Returns a disposer. */
+  subscribe(listener: (workspace: import('./model.ts').WorkspaceRecord) => void): () => void
+  /** Register a provider (idempotent same-version; throws on conflict). */
+  register(provider: WorkspaceProvider): void
+  /** Unregister a provider by id (no-op when absent). */
+  unregister?(providerId: string): void
+  /** Look up a provider by id. */
+  provider(id: string): WorkspaceProvider | undefined
+  /** All registered providers. */
+  providers(): WorkspaceProvider[]
+}

package/src/base/router.ts

@@ -0,0 +1,43 @@
+/**
+ * Generic workspace routing — the switch-layer contracts. A `WorkspaceRouter`
+ * decides, for a session cwd or a namespaced target key, which workspace
+ * (and thus which provider connection) owns the operation. The switch
+ * facades (`switch-fs.ts` / `switch-subprocess.ts` in the runtime layer)
+ * consume this router and never branch on provider identity.
+ *
+ * @module @tiphareth/dsh-hardssh/base/router
+ */
+
+import type { WorkspaceConnection } from './model.ts'
+import type { WorkspaceNamespaceCodec, WorkspaceRoute } from './namespace.ts'
+
+/** One resolved routing decision: the owning workspace connection + raw key. */
+export interface WorkspaceResolution {
+  /** Open connection to the owning workspace (ready or degraded). */
+  connection: WorkspaceConnection
+  /** The raw (un-namespaced) target key for the connection's backend. */
+  rawKey: string
+}
+
+/**
+ * Route resolver contract. Implementations combine the ledger's anchor index
+ * (cwd → workspace) with the namespace codec (explicit key → workspace).
+ */
+export interface WorkspaceRouter {
+  /** Resolve an explicit namespaced key; undefined = unrouteable (fail closed). */
+  fromNamespace(key: string): WorkspaceResolution | undefined
+  /** Resolve a session cwd to its workspace (undefined = local / unbound). */
+  fromAnchor(cwd: string | undefined): WorkspaceConnection | undefined
+  /** The namespace codec this router uses (for the switch facade to encode). */
+  codec: WorkspaceNamespaceCodec
+  /** Map a route back to a resolution (used by the switch to re-encode child keys). */
+  resolveRoute(route: WorkspaceRoute): WorkspaceResolution | undefined
+}
+
+/** Convenience base: default codec wiring plus helper for resolution lookup. */
+export abstract class BaseWorkspaceRouter implements WorkspaceRouter {
+  abstract readonly codec: WorkspaceNamespaceCodec
+  abstract fromNamespace(key: string): WorkspaceResolution | undefined
+  abstract fromAnchor(cwd: string | undefined): WorkspaceConnection | undefined
+  abstract resolveRoute(route: WorkspaceRoute): WorkspaceResolution | undefined
+}

package/src/client/api.ts

@@ -0,0 +1,196 @@
+/**
+ * Browser-side API clients: the /api/dsh-hardssh route family (SSH workspace
+ * CRUD, remote dir browsing, workspace file ops) plus the two /api/dsh-ssh
+ * endpoints the config dialog needs (host create + test). Plain fetch, same
+ * origin 鈥?the only data path the panel components use.
+ */
+
+import { HttpApiError, buildQuery, readJson } from '../client-http.ts'
+import {
+  WORKSPACE_API,
+  type DirListing,
+  type FileRead,
+  type FileWriteResult,
+  type RemoteDirEntry,
+  type SearchView,
+  type SshWorkspaceRecord,
+} from '../protocol.ts'
+
+/** Error carrying the route's JSON error message and stable code/status. */
+export class WorkspaceApiError extends HttpApiError {
+  constructor(
+    message: string,
+    code?: string,
+    status?: number,
+  ) {
+    super(message, code, status)
+    this.name = 'WorkspaceApiError'
+  }
+}
+
+/** The workspace route family client. */
+export class WorkspaceApi {
+  /** List the SSH-bound workspaces. */
+  async listWorkspaces(): Promise<SshWorkspaceRecord[]> {
+    const response = await fetch(WORKSPACE_API.sshWorkspaces)
+    const body = await readJson<{ workspaces: SshWorkspaceRecord[] }>(response)
+    return body.workspaces
+  }
+
+  /** Create one SSH-bound workspace. */
+  async createWorkspace(input: { title: string; alias: string; remoteRoot: string }): Promise<SshWorkspaceRecord> {
+    const response = await fetch(WORKSPACE_API.sshWorkspaces, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(input),
+    })
+    const body = await readJson<{ workspace: SshWorkspaceRecord }>(response)
+    return body.workspace
+  }
+
+  /** Rename one SSH-bound workspace. */
+  async renameWorkspace(id: string, title: string): Promise<SshWorkspaceRecord> {
+    const response = await fetch(WORKSPACE_API.sshWorkspaces + '/item' + buildQuery({ id }), {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ title }),
+    })
+    const body = await readJson<{ workspace: SshWorkspaceRecord }>(response)
+    return body.workspace
+  }
+
+  /** Delete one SSH-bound workspace. */
+  async deleteWorkspace(id: string): Promise<void> {
+    const response = await fetch(WORKSPACE_API.sshWorkspaces + '/item' + buildQuery({ id }), {
+      method: 'DELETE',
+    })
+    await readJson<{ ok: true }>(response)
+  }
+
+  /** List the configured SSH hosts (from the shared dsh-ssh store). */
+  async listHosts(): Promise<Array<{ alias: string; host: string; port: number; user: string }>> {
+    const response = await fetch(WORKSPACE_API.sshWorkspaces + '/hosts')
+    const body = await readJson<{ hosts: Array<{ alias: string; host: string; port: number; user: string }> }>(response)
+    return body.hosts
+  }
+
+  /** Browse a remote directory (for the workspace picker). */
+  async listRemoteDir(alias: string, path?: string): Promise<{ path: string; entries: RemoteDirEntry[] }> {
+    const response = await fetch(WORKSPACE_API.sshWorkspaceDir + buildQuery({ alias, path }))
+    const body = await readJson<{ path: string; entries: RemoteDirEntry[] }>(response)
+    return body
+  }
+
+  async list(root: string, path: string): Promise<DirListing> {
+    const response = await fetch(WORKSPACE_API.tree + buildQuery({ root, path }))
+    const body = await readJson<{ listing: DirListing }>(response)
+    return body.listing
+  }
+
+  async read(root: string, path: string): Promise<FileRead> {
+    const response = await fetch(WORKSPACE_API.file + buildQuery({ root, path }))
+    const body = await readJson<{ file: FileRead }>(response)
+    return body.file
+  }
+
+  async write(root: string, path: string, content: string, expectedMtime?: number): Promise<FileWriteResult> {
+    const response = await fetch(WORKSPACE_API.file, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ root, path, content, expectedMtime }),
+    })
+    const body = await readJson<{ result: FileWriteResult }>(response)
+    return body.result
+  }
+
+  async search(root: string, queryText: string): Promise<SearchView> {
+    const response = await fetch(WORKSPACE_API.search + buildQuery({ root, query: queryText }))
+    const body = await readJson<{ search: SearchView }>(response)
+    return body.search
+  }
+}
+
+/** The two /api/dsh-ssh endpoints the config dialog needs (host create/test). */
+export interface SshHostPayload {
+  alias?: string
+  host: string
+  port?: number
+  user: string
+  auth?: {
+    kind: 'key' | 'password'
+    keyPath?: string
+    passphrase?: string
+    password?: string
+  }
+  description?: string
+}
+
+export interface SshHostSummary {
+  alias: string
+  host: string
+  port: number
+  user: string
+  auth: 'key' | 'password'
+  keyReady: boolean
+  description?: string
+  createdAt: number
+  updatedAt: number
+}
+
+export interface TestResult {
+  ok: boolean
+  latencyMs?: number
+  error?: string
+}
+
+const HOSTS_API = '/api/dsh-ssh/hosts'
+const TEST_API = '/api/dsh-ssh/test'
+
+export class SshHostsApi {
+  async list(): Promise<SshHostSummary[]> {
+    const response = await fetch(HOSTS_API)
+    const body = await readJson<{ hosts: SshHostSummary[] }>(response)
+    return body.hosts
+  }
+
+  async create(payload: SshHostPayload): Promise<SshHostSummary> {
+    const response = await fetch(HOSTS_API, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    const body = await readJson<{ host: SshHostSummary }>(response)
+    return body.host
+  }
+
+  /** Update an existing host (PATCH /api/dsh-ssh/hosts?alias=鈥?. The payload
+   *  may carry only the fields being changed; omitted auth keeps the stored
+   *  secret. */
+  async update(alias: string, payload: SshHostPayload): Promise<SshHostSummary> {
+    const response = await fetch(`${HOSTS_API}?alias=${encodeURIComponent(alias)}`, {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    const body = await readJson<{ host: SshHostSummary }>(response)
+    return body.host
+  }
+
+  /** Delete a host (DELETE /api/dsh-ssh/hosts?alias=鈥?. */
+  async remove(alias: string): Promise<void> {
+    const response = await fetch(`${HOSTS_API}?alias=${encodeURIComponent(alias)}`, {
+      method: 'DELETE',
+    })
+    await readJson<{ ok: true }>(response)
+  }
+
+  async test(alias: string): Promise<TestResult> {
+    const response = await fetch(TEST_API, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ alias }),
+    })
+    const body = await readJson<{ result: TestResult }>(response)
+    return body.result
+  }
+}

package/src/client/css-modules.d.ts

@@ -0,0 +1,5 @@
+/* Minimal CSS Modules declaration (mirrors the other packages). */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}