@compforge/harness-common 0.5.11 → 0.5.13

package/README.md

@@ -203,3 +203,23 @@ Use `serializeValue` to preserve immutable JSON and reading hints, and `deserial
 with an explicit matching codec to restore runtime behavior. Encoding and decoding are pure.
 Doctor and its Plugins import these contracts directly from `@compforge/harness-common`;
 Observation identity, evidence and rendering remain with their consumers.
+
+## Component tools and Depot
+
+Component optionally declares `tools` and one logical `depot`. `Tool` describes a development
+tool and an optional declared version/constraint. `Depot.bins` groups `Bin` declarations with
+repository-relative paths and `dependencies`, `output` or `cache` kinds. Metadata does not change
+Component identity, prove physical existence or authorize deletion. Discovery, preparation,
+usage protection and reclamation belong to consumers. See [the shared contract](../../../docs/component-depot.md).
+
+## Endpoint
+
+`Endpoint` describes a network access address: optional lowercase `scheme`, `host`, explicit
+`port`, and optional `secure`. It is independent of the Service, DataSource or resource behind
+that address. IPv6 hosts are unbracketed. Credentials, paths, query parameters, execution
+locations and timeouts are not part of this contract.
+
+`secure: true` requires encrypted transport; the protocol determines whether it uses direct
+TLS or protocol-specific negotiation. Omission makes no encryption requirement. HTTPS/WSS/TLS
+endpoints require `secure: true`. This declaration does not assert connectivity, trust-policy
+approval or authorization. Toolbox owns URL projection, validation and network probing.

package/dist/access/endpoint.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A network access address, independent of the Service, DataSource or resource behind it.
+ * @spec Endpoint contains no credentials, resource path, query or execution location.
+ * @spec secure requires encrypted transport; the scheme determines how it is established.
+ * It does not assert reachability, trust-policy approval or application authorization.
+ */
+export interface Endpoint {
+    /** Lowercase URI scheme without a colon; protocol metadata, not a health assertion. */
+    readonly scheme?: string;
+    /** Hostname or IP literal; IPv6 literals have no surrounding brackets. */
+    readonly host: string;
+    readonly port: number;
+    /** Omission makes no encryption requirement; HTTPS/WSS/TLS endpoints require true. */
+    readonly secure?: boolean;
+}

package/dist/access/endpoint.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export * from "./system/forge.js";
 export * from "./system/repository.js";
 export * from "./system/pull-request.js";
 export * from "./system/component.js";
+export * from "./system/tool.js";
+export * from "./system/depot.js";
 export * from "./system/host.js";
 export * from "./system/environment.js";
 export * from "./system/service.js";
@@ -20,3 +22,4 @@ export * from "./system/resource.js";
 export * from "./json.js";
 export * from "./summary.js";
 export * from "./value.js";
+export type { Endpoint } from "./access/endpoint.js";

package/dist/index.js

@@ -8,6 +8,8 @@ export * from "./system/forge.js";
 export * from "./system/repository.js";
 export * from "./system/pull-request.js";
 export * from "./system/component.js";
+export * from "./system/tool.js";
+export * from "./system/depot.js";
 export * from "./system/host.js";
 export * from "./system/environment.js";
 export * from "./system/service.js";

package/dist/system/component.d.ts

@@ -1,5 +1,9 @@
+import type { Depot } from "./depot.js";
+import type { Tool } from "./tool.js";
 import type { Repository } from "./repository.js";
-/** A buildable component within a repository; one repository may own many. */
+/** A buildable component within a repository; one repository may own many.
+ * @spec language, tools and depot are optional declarations, not Component identity or runtime evidence.
+ */
 export interface Component {
     readonly repository: Repository;
     readonly name: string;
@@ -7,6 +11,10 @@ export interface Component {
     readonly description?: string;
     /** Optional implementation language, supplied by consumers; not part of identity. */
     readonly language?: string;
+    /** Omitted means undeclared; an empty list declares no tools. */
+    readonly tools?: readonly Tool[];
+    /** Logical content declaration, resolved separately in each checkout. */
+    readonly depot?: Depot;
 }
 /** Derive the tool ecosystem from language; unknown mappings return undefined.
  * Package manager discovery and execution remain consumer responsibilities.

package/dist/system/depot.d.ts

@@ -0,0 +1,17 @@
+/** A recoverable content unit within a Depot, usually one directory.
+ * @spec path is a normalized repository-relative POSIX path, never checkout-absolute.
+ * @rule A declaration alone does not authorize deletion or prove exclusive ownership.
+ * @see {@link component://docs/component-depot.md}
+ */
+export interface Bin {
+    readonly path: string;
+    readonly kind: "dependencies" | "output" | "cache";
+}
+/** The optional logical container for a Component's recoverable supporting content.
+ * @spec A Component has at most one Depot per checkout; missing contents do not remove its declaration.
+ * @spec Consumers own discovery, preparation, usage protection and reclamation.
+ * @see {@link component://docs/component-depot.md}
+ */
+export interface Depot {
+    readonly bins: readonly Bin[];
+}

package/dist/system/depot.js

@@ -0,0 +1 @@
+export {};

package/dist/system/tool.d.ts

@@ -0,0 +1,8 @@
+/** A development tool declared for a Component, such as pnpm, uv or Vite.
+ * @spec A declaration does not prove installation or select an executable.
+ */
+export interface Tool {
+    readonly name: string;
+    /** Declared version or constraint, not an observed installed version. */
+    readonly version?: string;
+}

package/dist/system/tool.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-common",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
   "type": "module",
   "scripts": {