@ccdd/core 3.3.1 → 4.1.0

package/examples/artifact-groups/README.md

@@ -1,60 +0,0 @@
-# Default image tool and Artifact groups
-
-The `effect` document and `preview` image are independent Artifacts. `explosion` is a group referencing both IDs, with no path or type. Tools for the document and image are explicitly registered. This example is a static sample, not an actual VFX asset.
-
-- `preview-review`: Evaluates one image. Only `view_image_preview` is supplied.
-- `explosion-review`: Evaluates the group. `read_effect` and `view_image_preview` are supplied. Tools are not duplicated when `preview` is both a member and a dependency.
-- `explosion-human`: Opens the group's document and image in desktop applications, then accepts a submitted verdict.
-
-In a full Run, both group Critics must wait for the image review to pass because of explicit `deps: ['preview']`. Membership alone does not require prior evaluation. Once both group Critics are GREEN, `explosion` is GREEN while `effect` remains unreviewed.
-
-## Running the example
-
-Install the three v3.1.0 packages on Node 22 LTS (22.19.0 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)
-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@3.1.0 @ccdd/project@3.1.0 @ccdd/default-tools@3.1.0
-
-# Check group member tool readiness without calling a Provider.
-npx ccdd tools check --artifact explosion --for agent
-# Select an individual Artifact for actual image reading.
-npx ccdd tools check --artifact preview --for agent --tool view_image --execute
-
-# Review one Critic; this legacy command skips waiting for prerequisite verdicts.
-npx ccdd run --copy --critic explosion-review --codex-auth-file "$HOME/.codex/auth.json" --wait
-```
-
-Actual Agent review requires authentication and access to a model supporting image input. See the [reviewer guide](../../docs/reviewers.md) for authentication methods. Tool checks do not call a model. The `--execute` output above includes actual image blocks in base64.
-
-If core is already installed, change the first `cp` source to `node_modules/@ccdd/core/examples/artifact-groups`.
-
-Start a full Run with Human review by registering a local notification:
-
-```sh
-npx ccdd run --copy --human-inbox --codex-auth-file "$HOME/.codex/auth.json"
-npx ccdd monitor
-```
-
-Select a project and Run in the monitor, then click the group node in Graph to inspect its members. Claim the Human request, click `{explosion}`, execute each member's `open` tool, and submit a verdict with evidence. Default desktop opening targets macOS; explicitly register an executable on other operating systems.
-
-`view_image` reuses Pi `read` image results. It detects PNG/JPEG/WebP from file content, with a 4MiB limit. GIF, BMP, animated PNG, and text results fail; no automatic conversion or resizing occurs. When registered on a directory Artifact, pass an internal path such as `{"path":"frames/preview.png"}`.
-
-## Using a local source build
-
-To test modified source, prepare three tarballs in the CCDD repository:
-
-```sh
-npm ci
-npm run build
-CCDD_LOCAL_PACKAGES=$(mktemp -d /tmp/ccdd-group-packages.XXXXXX)
-npm pack --ignore-scripts --pack-destination "$CCDD_LOCAL_PACKAGES"
-npm pack --ignore-scripts --workspace @ccdd/project --pack-destination "$CCDD_LOCAL_PACKAGES"
-npm pack --ignore-scripts --workspace @ccdd/default-tools --pack-destination "$CCDD_LOCAL_PACKAGES"
-```
-
-In the same shell, create the new example project from the steps above, then replace the npm version installation with `npm install --ignore-scripts "$CCDD_LOCAL_PACKAGES"/*.tgz`. Subsequent tool checks and review commands are the same. To also run the full test suite and separate installation checks on source fixed to a commit, use `--dry-run` with the [local Release command](../../docs/releases.md#releasing-a-specific-commit-locally).

package/examples/artifact-groups/ccdd.config.ts

@@ -1,37 +0,0 @@
-import { defineConfig } from '@ccdd/core';
-import { agent, human } from '@ccdd/default-tools';
-
-export default defineConfig({
-  artifacts: {
-    effect: { type: 'markdown', path: 'effect.md' },
-    preview: { type: 'image', path: 'preview.png' },
-    explosion: { kind: 'group', members: ['effect', 'preview'] },
-  },
-  artifactTypes: {
-    markdown: {
-      agentTools: { read: agent.text.read() },
-      humanTools: { open: human.desktop.open() },
-    },
-    image: {
-      agentTools: { view_image: agent.image.view() },
-      humanTools: { open: human.desktop.open() },
-    },
-  },
-  critics: [
-    {
-      id: 'preview-review', title: 'Image visibility', target: 'preview', deps: [],
-      profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
-      payload: { instruction: 'Check whether {preview} has a bright center and an orange ring distinguishable from the dark background. Review the image itself; matching the effect specification is outside this review.' },
-    },
-    {
-      id: 'explosion-review', title: 'Match the effect description and preview', target: 'explosion', deps: ['preview'],
-      profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
-      payload: { instruction: 'Observe every member of {explosion} and evaluate whether {preview} matches the static appearance specified in {effect}. Animation timing and actual VFX runtime behavior are outside the scope of this static example.' },
-    },
-    {
-      id: 'explosion-human', title: 'Review the group on the desktop', target: 'explosion', deps: ['preview'],
-      profile: { kind: 'human' },
-      payload: { instruction: 'Open the document and image in {explosion} with their desktop programs, compare them, and submit your verdict.' },
-    },
-  ],
-});

package/examples/custom-text-reader/ccdd.config.ts

@@ -1,64 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { defineConfig, defineTool } from '@ccdd/core';
-
-// This factory defines a tool. It does not read the Artifact or execute an app.
-function customTextReader() {
-  return defineTool({
-    metadata: {
-      description: 'Read the specified line range from {artifactName}.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          startLine: { type: 'integer', minimum: 1 },
-          lineCount: { type: 'integer', minimum: 1, maximum: 80 },
-        },
-        required: ['startLine', 'lineCount'],
-        additionalProperties: false,
-      } as const,
-      resultKinds: ['json'],
-      observation: 'content',
-      artifactKind: 'file',
-    },
-    async execute(context, args) {
-      // Deliberately small teaching example: it accepts files up to 1 MiB.
-      const file = await context.resolvePath();
-      const bytes = await readFile(file, { signal: context.signal });
-      if (bytes.length > 1024 * 1024) throw new Error('This example reader supports files up to 1 MiB.');
-      const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
-      if (text.includes('\0')) throw new Error('This example reader accepts text, not binary data.');
-      const lines = text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
-      const offset = args.startLine - 1;
-      const selected = lines.slice(offset, offset + args.lineCount);
-      const content = selected.join('');
-      if (Buffer.byteLength(content) > 64 * 1024) throw new Error('Select a smaller line range.');
-      const nextOffset = offset + selected.length;
-      return {
-        content: [{ type: 'json', data: {
-          content,
-          startLine: args.startLine,
-          endLine: selected.length ? nextOffset : null,
-          lineCount: selected.length,
-          totalLines: lines.length,
-          nextStartLine: nextOffset < lines.length ? nextOffset + 1 : null,
-        } }],
-        ...(selected.length ? { observation: { kind: 'content' as const } }
-          : lines.length === 0 ? { observation: { kind: 'empty' as const } } : {}),
-      };
-    },
-  });
-}
-
-export default defineConfig(() => ({
-  artifactTypes: {
-    document: { agentTools: { read: customTextReader() } },
-  },
-  artifacts: {
-    why: { type: 'document', path: 'why.md', basis: true },
-    spec: { type: 'document', path: 'spec.md' },
-  },
-  critics: [{
-    id: 'spec-why', title: 'Does Spec match Why?', target: 'spec', deps: ['why'],
-    profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
-    payload: { instruction: 'Read both documents and evaluate whether Spec satisfies the maximum task count in Why.' },
-  }],
-}));

package/examples/generated-artifacts/README.md

@@ -1,55 +0,0 @@
-# Review generated scenario data
-
-This example captures two JSON scenarios as independent generated Artifacts. The scenario files are sample evidence for demonstrating review mechanics, not recorded product tests. Each Human Critic must inspect an overview and every listed detail, then make an actual judgment.
-
-`scenarioSource.prepare` reads a file from the captured project through `context.resolvePath`. It returns structured data directly; CCDD persists the fixed value outside the reviewed workspace. The source does no generation, so it declares `preparation: 'read-only'` and supports `status` and `plan`.
-
-The explicitly registered `overview` and `detail` tools use `context.readData()`. Each call receives a copy of the recorded value, including after worker restart. The full scenario determines identity even when a tool only returns one field. Initial prompts and monitor scope metadata do not contain that data.
-
-## Run the example
-
-Use Node 22 LTS, at least 22.19.0. These APIs require CCDD 3.2.0 or later. From the source repository, build and pack core and project:
-
-```sh
-npm ci
-npm run build
-CCDD_GENERATED_PACKAGES=$(mktemp -d /tmp/ccdd-generated-packages.XXXXXX)
-npm pack --ignore-scripts --pack-destination "$CCDD_GENERATED_PACKAGES"
-npm pack --ignore-scripts --workspace @ccdd/project --pack-destination "$CCDD_GENERATED_PACKAGES"
-
-CCDD_GENERATED_EXAMPLE=$(mktemp -d /tmp/ccdd-generated-example.XXXXXX)
-cp -R examples/generated-artifacts "$CCDD_GENERATED_EXAMPLE/project"
-cd "$CCDD_GENERATED_EXAMPLE/project"
-npm init -y
-npm pkg set type=module
-npm install --ignore-scripts "$CCDD_GENERATED_PACKAGES"/*.tgz
-```
-
-Inspect the current input and execute the two data tools without starting a review:
-
-```sh
-npx ccdd-project plan checkout
-npx ccdd-project tools check --artifact checkout --for human --tool overview --execute
-npx ccdd-project tools check --artifact checkout --for human --tool detail --execute --args '{"id":"summary"}'
-```
-
-These tool diagnostics prepare a new snapshot and report actual tool results. They do not create a verdict or demonstrate that the scenario passes its Critic.
-
-Request both Human reviews and open the monitor:
-
-```sh
-npx ccdd-project verify --all --human-inbox
-npx ccdd-project monitor
-```
-
-Open the printed local address, choose the project and a Human request, and claim it. Execute `overview`, then call `detail` for every returned detail ID. Submit your verdict with a summary and evidence citing those IDs. Repeat for the other scenario. See the [Human reviewer guide](../../docs/reviewers.md#ask-a-person-to-review) for the claim and submission workflow.
-
-The tools are also registered for Agents. To use them, change the desired Critic to an explicitly supported Agent profile and supply credentials as described in the [reviewer guide](../../docs/reviewers.md). An Agent review makes actual Provider calls. Runtime Critics do not support generated Artifact scopes.
-
-## Inspect reuse
-
-After completing real reviews, run `npx ccdd-project status`. Edit a detail in `scenarios/checkout.json` and run `npx ccdd-project plan --all`. Checkout now has changed input; an applicable passing search review can remain reusable because its captured data and Critic definition are unchanged. Changing an unread detail also changes checkout identity. Restoring equivalent checkout data can reuse its applicable historical evidence, subject to the existing latest-verdict and dependency rules.
-
-Changing whitespace or object-key order preserves canonical JSON identity. Array order remains significant. Keep changing scenario data in these source files rather than importing it into shared config: imported config module changes conservatively affect effective Critic definitions.
-
-See [generated Artifact contracts](../../docs/generated-artifacts.md) for identity strategies, canonicalization, size limits, preparation policy, and reopening behavior.

package/examples/generated-artifacts/ccdd.config.ts

@@ -1,86 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { defineArtifactSource, defineConfig, defineDataTool } from '@ccdd/core';
-import type { JsonValue } from '@ccdd/core';
-
-function scenarioData(value: JsonValue) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)
-    || typeof value.name !== 'string' || typeof value.objective !== 'string'
-    || !Array.isArray(value.criteria) || value.criteria.some(item => typeof item !== 'string')
-    || !Array.isArray(value.details) || value.details.some(item => !item || typeof item !== 'object'
-      || Array.isArray(item) || typeof item.id !== 'string' || typeof item.observation !== 'string')) {
-    throw new Error('Expected a scenario with name, objective, criteria, and identified details.');
-  }
-  return value as { name: string; objective: string; criteria: string[]; details: { id: string; observation: string }[] };
-}
-
-const scenarioSource = defineArtifactSource({
-  metadata: {
-    preparation: 'read-only',
-    identity: { kind: 'canonical-data', namespace: 'example/scenario', version: '1' },
-  },
-  async prepare(context) {
-    if (typeof context.params !== 'string') throw new Error('Expected a scenario file path.');
-    const data: JsonValue = JSON.parse(await readFile(await context.resolvePath(context.params), 'utf8'));
-    scenarioData(data);
-    return { data };
-  },
-});
-
-const overview = defineDataTool({
-  metadata: {
-    description: 'Read the objective, criteria, and available detail IDs of {artifactName}.',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-    resultKinds: ['json'],
-    observation: 'content',
-  },
-  execute(context) {
-    const data = scenarioData(context.readData());
-    return {
-      content: [{ type: 'json', data: {
-        name: data.name, objective: data.objective, criteria: data.criteria,
-        detailIds: data.details.map(detail => detail.id),
-      } }],
-      observation: { kind: 'content' },
-    };
-  },
-});
-
-const detail = defineDataTool({
-  metadata: {
-    description: 'Read one identified detail from the captured {artifactName} scenario.',
-    inputSchema: {
-      type: 'object', properties: { id: { type: 'string', minLength: 1 } },
-      required: ['id'], additionalProperties: false,
-    },
-    resultKinds: ['json'],
-    observation: 'content',
-  },
-  execute(context, args) {
-    const found = scenarioData(context.readData()).details.find(item => item.id === args.id);
-    if (!found) throw new Error('Unknown scenario detail.');
-    return { content: [{ type: 'json', data: found }], observation: { kind: 'content' } };
-  },
-});
-
-export default defineConfig({
-  artifactSources: { scenario: scenarioSource },
-  artifactTypes: {
-    scenario: { agentTools: { overview, detail }, humanTools: { overview, detail } },
-  },
-  artifacts: {
-    checkout: { kind: 'generated', type: 'scenario', source: 'scenario', params: 'scenarios/checkout.json' },
-    search: { kind: 'generated', type: 'scenario', source: 'scenario', params: 'scenarios/search.json' },
-  },
-  critics: [
-    {
-      id: 'checkout-review', title: 'Review the checkout scenario', target: 'checkout', deps: [],
-      profile: { kind: 'human' },
-      payload: { instruction: 'Read the overview of {checkout}, then inspect every listed detail. Decide whether the observations satisfy each criterion. Cite detail IDs and explain missing or contradictory evidence.' },
-    },
-    {
-      id: 'search-review', title: 'Review the search scenario', target: 'search', deps: [],
-      profile: { kind: 'human' },
-      payload: { instruction: 'Read the overview of {search}, then inspect every listed detail. Decide whether the observations satisfy each criterion. Cite detail IDs and explain missing or contradictory evidence.' },
-    },
-  ],
-});