@compforge/harness-common 0.5.11 → 0.5.12

package/README.md

@@ -203,3 +203,11 @@ 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).

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";

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.12",
   "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
   "type": "module",
   "scripts": {