@hydraharness/harness-host-directory-picker 0.0.0-stage → 0.1.1-rc.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @hydraharness/harness-host-directory-picker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The web GUI host's workspace-directory picker is a capability seam. The abstract `DirectoryPicker` service (`ctx.directoryPicker`) is its Service Definition. Its only method, `capability()`, returns a discriminated union describing how an operator selects a directory. Backends differ in user interaction, not just implementation: `{ kind: 'native', pick(signal) }` opens one native OS chooser on the host display ([`-native`](../directory-picker-native/README.md)); `{ kind: 'browse', list(path?), createDirectory(path, name) }` provides listing and creation operations for an in-app browser, which works for remote clients that cannot reach an OS chooser ([`-browse`](../directory-picker-browse/README.md)). Consumers switch on `capability().kind`; the union derives from the merge-extensible `DirectoryPickerCapabilities` map, and a new backend adds its variant there through declaration merging. For an unknown kind, consumers hide directory picking rather than fail. The capability object must be stable for the service lifetime. Each backend package also has a browser entrypoint that registers the matching interaction in ui-workspace's directory-flow slots, so one composition row selects both the host capability and the client flow. A composition that should choose at runtime mounts [`-auto`](../directory-picker-auto/README.md), which inspects the host once at boot and mounts the matching backend row.
+
+Browse primitives fail with the typed `DirectoryPickerError` (`directory-unreadable` / `directory-exists` / `directory-create-failed`, each carrying the subject `path`), which the consuming gateway maps 1:1 onto wire error codes. `DirectoryEntry` rows carry a host-owned `hidden` flag (POSIX dot convention) so display policy stays client-side; `DirectoryListing.crumbs` is the ancestor chain from the filesystem root, every crumb a jump target. Design rationale, the `ctx.fs` separation, and the policy decisions live in [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md).
+
+## Model Experience
+
+None, as the seam serves the GUI host's directory selection; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No multi-root support** — the browse contract exposes one ancestry chain per listing; per-deployment root scoping (and Windows drive-root enumeration above a drive) waits for a consumer that needs it, per the DirectoryPicker Agent Note.

package/lib/index.js

@@ -0,0 +1,44 @@
+import { Service } from "@hydraharness/cordis";
+//#region lib/types/index.js
+/**
+* Service Definition for the `ctx.directoryPicker` capability seam: how the web-GUI host lets an operator
+* select a workspace directory. Backends differ in interaction shape, not
+* just mechanism, so the service exposes a discriminated capability instead
+* of one method set: a `native` backend opens one OS chooser on the
+* host's display, while a `browse` backend serves listing/creation primitives
+* for an in-app browser (and thereby works for remote clients no OS dialog
+* can reach). Consumers switch on `capability().kind`; the union is
+* merge-extensible, and the documented default for an unknown kind is to
+* hide the picking affordance rather than fail.
+* @module @hydraharness/harness-host-directory-picker
+*/
+/** Typed failure thrown by browse primitives so consumers can map business codes without string matching. */
+var DirectoryPickerError = class extends Error {
+	code;
+	path;
+	/**
+	* @param code - closed business code of the failure.
+	* @param path - the absolute path the failure is about.
+	* @param message - operator-facing description.
+	*/
+	constructor(code, path, message) {
+		super(message);
+		this.code = code;
+		this.path = path;
+		this.name = "DirectoryPickerError";
+	}
+};
+/**
+* Abstract directory-picking service. Subclass, implement `capability()`, and
+* load the subclass as a plugin — it registers as `ctx.directoryPicker` (one
+* implementation per context; loading a second throws, cordis' standard
+* duplicate-service behavior). The capability object must be stable for the
+* service lifetime: consumers may capture it across calls.
+*/
+var DirectoryPicker = class extends Service {
+	constructor(ctx) {
+		super(ctx, "directoryPicker");
+	}
+};
+//#endregion
+export { DirectoryPicker, DirectoryPicker as default, DirectoryPickerError };

package/lib/invariant.js

@@ -0,0 +1,20 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion for the directory-picker seam. @module @hydraharness/harness-host-directory-picker/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-host-directory-picker";
+/** Cordis companion plugin name. */
+const name = "host-directory-picker-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this stateless Service Definition owns the capability
+* vocabulary, while backends and the RPC consumer own observations.
+*/
+const install = () => {};
+/**
+* Register the directory-picker invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Service Definition for the `ctx.directoryPicker` capability seam: how the web-GUI host lets an operator
+ * select a workspace directory. Backends differ in interaction shape, not
+ * just mechanism, so the service exposes a discriminated capability instead
+ * of one method set: a `native` backend opens one OS chooser on the
+ * host's display, while a `browse` backend serves listing/creation primitives
+ * for an in-app browser (and thereby works for remote clients no OS dialog
+ * can reach). Consumers switch on `capability().kind`; the union is
+ * merge-extensible, and the documented default for an unknown kind is to
+ * hide the picking affordance rather than fail.
+ * @module @hydraharness/harness-host-directory-picker
+ */
+import { Context, Service } from '@hydraharness/cordis';
+/** The native interaction: one OS directory chooser on the host display. */
+export interface DirectoryPickerNativeCapability {
+    kind: 'native';
+    /**
+     * Open the chooser and wait for the operator.
+     * @param signal - caller/connection lifetime; abort terminates the chooser.
+     * @returns the chosen absolute path, or null when the operator cancels.
+     */
+    pick(signal: AbortSignal): Promise<string | null>;
+}
+/** One directory row: a listing child or a breadcrumb ancestor. */
+export interface DirectoryEntry {
+    /** Base name shown in a browser row (a root crumb carries its full path). */
+    name: string;
+    /** Absolute host path — clients never join path segments themselves. */
+    path: string;
+    /** Hidden by the host platform's convention (dot-prefixed on POSIX); the client owns whether to show it. */
+    hidden: boolean;
+}
+/** One directory level plus its ancestry, as a browse backend reports it. */
+export interface DirectoryListing {
+    /** Absolute path of the listed directory. */
+    path: string;
+    /** The host account's home directory (breadcrumb "Home" rooting). */
+    home: string;
+    /**
+     * Ancestor chain from the filesystem root to the listed directory
+     * inclusive; every crumb is a jump target (crumb `hidden` is always false).
+     */
+    crumbs: DirectoryEntry[];
+    /** Direct child directories, name-sorted; symlinks to directories included. */
+    entries: DirectoryEntry[];
+    /**
+     * True when the backend cut `entries` at its complete-result bound: the
+     * level has more child directories than reported, and the missing rows are
+     * the name-sorted tail (hidden rows count toward the bound).
+     */
+    truncated: boolean;
+}
+/**
+ * The browse interaction: listing/creation primitives an in-app browser
+ * drives one level at a time. Works for remote clients — nothing renders on
+ * the host display.
+ */
+export interface DirectoryPickerBrowseCapability {
+    kind: 'browse';
+    /**
+     * List one directory level.
+     * @param path - absolute directory to list; absent lists the home directory.
+     * @param signal - caller lifetime; abort stops the scan (a stalled network
+     * directory must not outlive a disconnected caller) and rejects with the
+     * abort reason.
+     * @returns the level's listing with ancestry; backends bound the complete
+     * result, and a cut level reports `truncated`.
+     * @throws {DirectoryPickerError} `directory-unreadable` when the target is not fully
+     * qualified (a wire value must never resolve against the host cwd or, on
+     * Windows, its current drive) or cannot be listed.
+     */
+    list(path?: string, signal?: AbortSignal): Promise<DirectoryListing>;
+    /**
+     * Create one child directory under an existing parent.
+     * @param path - absolute existing parent directory.
+     * @param name - single non-blank path segment (no separators, not `.`/`..`).
+     * @returns the created directory's absolute path.
+     * @throws {DirectoryPickerError} `directory-exists` for an existing child,
+     * `directory-create-failed` for a parent that is not fully qualified or any other failure.
+     */
+    createDirectory(path: string, name: string): Promise<string>;
+}
+/**
+ * Merge-extensible registry of interaction shapes keyed by capability kind: a
+ * new backend declaration-merges its shape here (the entry's `kind` literal
+ * must equal its key) instead of editing this package.
+ */
+export interface DirectoryPickerCapabilities {
+    native: DirectoryPickerNativeCapability;
+    browse: DirectoryPickerBrowseCapability;
+}
+/** Union of interaction shapes a backend can provide, derived from the merge-extensible {@link DirectoryPickerCapabilities} map. */
+export type DirectoryPickerCapability = DirectoryPickerCapabilities[keyof DirectoryPickerCapabilities];
+/** Closed failure vocabulary of the browse primitives (mirrored onto the wire by consumers). */
+export type DirectoryPickerErrorCode = 'directory-unreadable' | 'directory-exists' | 'directory-create-failed';
+/** Typed failure thrown by browse primitives so consumers can map business codes without string matching. */
+export declare class DirectoryPickerError extends Error {
+    readonly code: DirectoryPickerErrorCode;
+    readonly path: string;
+    /**
+     * @param code - closed business code of the failure.
+     * @param path - the absolute path the failure is about.
+     * @param message - operator-facing description.
+     */
+    constructor(code: DirectoryPickerErrorCode, path: string, message: string);
+}
+declare module '@hydraharness/cordis' {
+    interface Context {
+        directoryPicker: DirectoryPicker;
+    }
+}
+/**
+ * Abstract directory-picking service. Subclass, implement `capability()`, and
+ * load the subclass as a plugin — it registers as `ctx.directoryPicker` (one
+ * implementation per context; loading a second throws, cordis' standard
+ * duplicate-service behavior). The capability object must be stable for the
+ * service lifetime: consumers may capture it across calls.
+ */
+export declare abstract class DirectoryPicker extends Service {
+    constructor(ctx: Context);
+    /**
+     * The backend's interaction capability.
+     * @returns the discriminated capability consumers switch on.
+     */
+    abstract capability(): DirectoryPickerCapability;
+}
+export default DirectoryPicker;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned invariant companion for the directory-picker seam. @module @hydraharness/harness-host-directory-picker/invariant */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "host-directory-picker-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the directory-picker invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@hydraharness/harness-host-directory-picker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Abstract workspace-directory picking seam (ctx.directoryPicker) for the Hydra harness web GUI host",
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/host/directory-picker"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  }
 }