@ccdd/core 2.0.2 → 3.0.0

package/dist/src/tools/contracts.d.ts

@@ -11,6 +11,8 @@ export interface ToolMetadata {
     observation: 'content' | 'none';
     artifactKind?: 'file' | 'directory' | 'any';
     timeoutMs?: number;
+    /** Project-relative runtime files or directories whose bytes affect this tool. */
+    executionPaths?: string[];
 }
 export interface ToolContext {
     artifactId: string;
@@ -20,6 +22,8 @@ export interface ToolContext {
     tmpDir: string;
     signal: AbortSignal;
     resolvePath(path?: string): Promise<string>;
+    /** Resolve only paths explicitly registered in metadata.executionPaths. */
+    resolveExecutionPath?(path: string): Promise<string>;
 }
 export type ToolContent = {
     type: 'text';
@@ -61,10 +65,19 @@ export interface ArtifactToolsConfig {
     agentTools?: Record<string, ToolDefinition<any>>;
     humanTools?: Record<string, ToolDefinition<any>>;
 }
+export interface EnvironmentRequirement {
+    description: string;
+    /** Project-relative Node script; a zero exit status confirms readiness. */
+    script: string;
+    timeoutMs?: number;
+    /** Additional project files or directories used by the check. */
+    inputs?: string[];
+}
 export interface Config {
     artifacts: Record<string, ArtifactEntryDefinition>;
     artifactTypes: Record<string, ArtifactToolsConfig>;
     critics: CriticDefinition[];
+    envRequirements?: Record<string, EnvironmentRequirement>;
 }
 export type ConfigFactory = () => Config | Promise<Config>;
 export interface ConfigManifest {
@@ -78,6 +91,15 @@ export interface ConfigManifest {
         agentTools: Record<string, ToolMetadata>;
         humanTools: Record<string, ToolMetadata>;
     }>;
+    envRequirements?: Record<string, EnvironmentRequirement>;
+    environmentInputs?: {
+        path: string;
+        hash: string;
+    }[];
+    executionInputs?: {
+        path: string;
+        hash: string;
+    }[];
 }
 type Properties<S> = S extends {
     properties: infer P;

package/examples/artifact-groups/README.md

@@ -10,7 +10,7 @@ In a full Run, both group Critics must wait for the image review to pass because
 
 ## Running the example
 
-Install the three v2.0.2 packages on Node 24 or later. The following command works after npm publication; before that, use the local source build below. Start in the CCDD source repository and copy the example into a new project outside it.
+Install the three v3.0.0 packages on Node 24 or later. The following command works after npm publication; before that, use the local source build below. Start in the CCDD source repository and copy the example into a new project outside it.
 
 ```sh
 CCDD_EXAMPLE_ROOT=$(mktemp -d /tmp/ccdd-groups.XXXXXX)
@@ -18,7 +18,7 @@ cp -R examples/artifact-groups "$CCDD_EXAMPLE_ROOT/project"
 cd "$CCDD_EXAMPLE_ROOT/project"
 npm init -y
 npm pkg set type=module
-npm install --ignore-scripts @ccdd/core@2.0.2 @ccdd/project@2.0.2 @ccdd/default-tools@2.0.2
+npm install --ignore-scripts @ccdd/core@3.0.0 @ccdd/project@3.0.0 @ccdd/default-tools@3.0.0
 
 # Check group member tool readiness without calling a Provider.
 npx ccdd tools check --artifact explosion --for agent

package/examples/custom-text-reader/README.md

@@ -2,7 +2,7 @@
 
 This example directly registers `{ metadata, execute }` without the default tool library. `customTextReader()` creates a definition; actual file reading occurs when an Agent calls `read_spec` or `read_why`.
 
-Each project must include its own dependencies. Copy this folder into a new project outside the repository, then install core and Project. The commands below work after npm v2.0.2 publication; before that, use the local tarballs described below. The example is included in the source repository and the core package's `examples/custom-text-reader`. It does not rely on CCDD installed in a parent repository.
+Each project must include its own dependencies. Copy this folder into a new project outside the repository, then install core and Project. The commands below work after npm v3.0.0 publication; before that, use the local tarballs described below. The example is included in the source repository and the core package's `examples/custom-text-reader`. It does not rely on CCDD installed in a parent repository.
 
 ```sh
 # Copy the example from the CCDD source repository.
@@ -10,13 +10,13 @@ cp -R examples/custom-text-reader /tmp/ccdd-custom-reader
 cd /tmp/ccdd-custom-reader
 npm init -y
 npm pkg set type=module
-npm install --ignore-scripts @ccdd/core@2.0.2 @ccdd/project@2.0.2
+npm install --ignore-scripts @ccdd/core@3.0.0 @ccdd/project@3.0.0
 npx ccdd tools check --artifact spec --for agent --tool read
 npx ccdd tools check --artifact spec --for agent --tool read --execute --args '{"startLine":1,"lineCount":20}'
 npx ccdd run --copy --critic spec-why --codex-auth-file "$HOME/.codex/auth.json" --wait
 ```
 
-This example installs core and Project without the default tool library. Alternatively, in the source repository run `npm run release:npm -- --commit <40-character SHA> --dry-run` to verify and generate matching `ccdd-core-2.0.2.tgz` and `ccdd-project-2.0.2.tgz` files, then install with `npm install --ignore-scripts <core.tgz> <project.tgz>`. This local verification requires no GitHub authentication. If CCDD is already installed, change the first `cp` source to `node_modules/@ccdd/core/examples/custom-text-reader`.
+This example installs core and Project without the default tool library. Alternatively, in the source repository run `npm run release:npm -- --commit <40-character SHA> --dry-run` to verify and generate matching `ccdd-core-3.0.0.tgz` and `ccdd-project-3.0.0.tgz` files, then install with `npm install --ignore-scripts <core.tgz> <project.tgz>`. This local verification requires no GitHub authentication. If CCDD is already installed, change the first `cp` source to `node_modules/@ccdd/core/examples/custom-text-reader`.
 
 The tool omits `preflight`. The default check distinguishes confirmed registration from unverified execution; `--execute` actually reads the file. Agent review requires valid Provider authentication.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccdd/core",
-  "version": "2.0.2",
+  "version": "3.0.0",
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
   "repository": { "type": "git", "url": "git+https://github.com/lhj6102/ccdd.git" },
   "description": "Artifact, Critic, relationship and tool definitions for CCDD",