@ccdd/default-tools 3.3.0 → 4.0.0

package/README.md

@@ -1,100 +1,62 @@
-# CCDD default tools
-
-CCDD 3.1.1 supports Node.js 22 LTS (22.19.0 or later). Install published versions with `npm install --ignore-scripts @ccdd/core @ccdd/default-tools`. Install `@ccdd/project` as well to use the project CLI.
-
-Optional tool implementations for `@ccdd/core`. This library does not register tools automatically. Import a factory and explicitly put its returned definition in your repository's `ccdd.config.ts`:
-
-```ts
-import { defineConfig } from '@ccdd/core';
-import { agent, human } from '@ccdd/default-tools';
-
-export default defineConfig(() => ({
-  artifactTypes: {
-    markdown: {
-      agentTools: { read: agent.text.read() },
-      humanTools: { open: human.desktop.open() },
-    },
-    code: {
-      agentTools: { list: agent.files.list(), read: agent.files.read() },
-      humanTools: { open: human.desktop.open() },
-    },
-  },
-  artifacts: {
-    why: { type: 'markdown', path: 'why.md', basis: true },
-    spec: { type: 'markdown', path: 'spec.md' },
-  },
-  critics: [{
-    id: 'spec-matches-why', title: 'Spec matches Why', target: 'spec', deps: ['why'],
-    profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
-    payload: { instruction: 'Read both Artifacts and evaluate whether Spec satisfies Why.' },
-  }],
-}));
+# @ccdd/default-tools
+
+Optional common view scripts for CCDD 4. Use Node 22 LTS, at least 22.19.0. Install `@ccdd/core@^4`, `@ccdd/project@^4` and `@ccdd/default-tools@^4`. Installation and imports register no tools.
+
+Declare each view explicitly in the owning folder's `ccdd.json`:
+
+```json
+{
+  "name": "document",
+  "basis": true,
+  "views": {
+    "agentTools": {
+      "read": {
+        "metadata": {
+          "description": "Read UTF-8 lines from {artifactName}.",
+          "inputSchema": {
+            "type": "object",
+            "properties": { "path": { "type": "string" }, "startLine": { "type": "integer", "minimum": 1 }, "lineCount": { "type": "integer", "minimum": 1, "maximum": 500 } },
+            "required": ["path"],
+            "additionalProperties": false
+          },
+          "resultKinds": ["json"],
+          "observation": "content",
+          "executionPaths": ["node_modules/@ccdd/default-tools/dist", "node_modules/@ccdd/core/dist"]
+        },
+        "script": { "command": "ccdd-view", "args": ["read"] }
+      }
+    }
+  }
+}
 ```
 
-Factories perform no I/O. Each returns `{ metadata, execute, preflight }`; CCDD connects its Artifact and validates call arguments before execution. Descriptions may contain `{artifactName}`. `description` and `timeoutMs` can be supplied to every factory.
+The shared execution paths are relative to the workspace root. Install dependencies there before evaluation. The runner resolves the nearest installed `ccdd-view` executable and supplies the standard version 1 JSON request on stdin. Stdout is a ToolResult. See the [complete JSON example](examples/document/ccdd.json).
 
-- `agent.text.read()` reads a file Artifact. Arguments: optional `startLine` (default 1), `lineCount` (default 80, maximum 500).
-- `agent.files.read()` reads a file inside a directory Artifact; additionally requires an internal `path`.
-- `agent.files.list()` lists a directory Artifact or internal `path`; optional `offset` and `limit` (maximum 200).
-- `agent.image.view()` returns an actual image block from a file Artifact (`{}`) or an internal file in a directory Artifact (`{path: 'frames/preview.png'}`). Register it with the key `view_image`.
-- `human.desktop.open()` opens a file or folder with macOS's default application. A directory Artifact accepts an optional internal `path`. Other platforms require an explicit `command`.
+| Fixed operation | Reviewer arguments | Result |
+| --- | --- | --- |
+| `read` | `path`, optional `startLine`, `lineCount` | UTF-8 line data; default 80, maximum 500 lines. |
+| `list` | optional `path`, `offset`, `limit` | Directory entries and logical mounts; maximum 200 entries. |
+| `image` | `path` | Native PNG/JPEG/WebP image block. |
+| `open` | optional `path` | Desktop launch receipt. |
 
-Agent tools invoke a packaged Node CLI directly, without a shell or a global executable installation. Reads preserve UTF-8 and LF/CRLF, return complete lines, and bound returned text to 64 KiB. Results contain paging information. Invalid UTF-8, binary content, oversized individual lines, symlinks and paths outside the Artifact fail explicitly. Only returned text or a truly empty file counts as content observation; listing and reading beyond EOF do not.
+Paths are logical paths inside the bound Artifact and may pass through children or mounts. They resolve to existing canonical paths before reading or launching. No mount folder, symlink or workspace copy is created. Invalid paths, symlink file traversal and unsupported files fail explicitly.
 
-## Images
+Reads preserve UTF-8 and LF/CRLF, return complete lines and cap text at 64 KiB. Invalid UTF-8, binary content and oversized individual lines fail. Content reads and truly empty files count as observations; listings and reads beyond EOF do not. Images use the existing packaged Pi read adapter without a Provider call, and validate actual bytes, format and the 4 MiB limit. GIF/BMP/animated PNG are rejected, with no automatic conversion.
 
-`agent.image.view()` is included in v1.1.0. The [image and group example](../../examples/artifact-groups/README.md) includes GitHub Release installation and tool verification instructions.
+Register a Human tool with `"script":{"command":"ccdd-view","args":["open"]}` and `resultKinds:["launch"]`, `observation:"none"`. The default desktop opener uses macOS. Other platforms can provide fixed launcher options as a JSON argv value:
 
-```ts
-// Register this type in ccdd.config.ts.
-image: {
-  agentTools: { view_image: agent.image.view() },
-  humanTools: { open: human.desktop.open() },
-}
+```json
+{"command":"ccdd-view","args":["open","{\"command\":\"/usr/bin/xdg-open\",\"args\":[\"{artifactPath}\"]}"]}
 ```
 
-A `preview` Artifact of this type exposes `view_image_preview` to Agents and `open_preview` to Humans. The image CLI reuses Pi Agent Core 0.85.1's `createReadTool()` with a filesystem adapter exposing only the bound file. It makes no LLM call, starts no Agent session and provides no general filesystem or shell access. The package pins this Pi dependency directly; Pi types are not exposed through the public CCDD tool definition.
+The options are configuration, never reviewer arguments. A successful launch does not prove the person observed content or complete a review. Applications must not write into the workspace. Human review remains local, with a live monitoring worker.
 
-Image contents, rather than filename extensions, determine support. A successful result requires a PNG/JPEG/WebP image block of at most 4MiB and produces a content observation for that leaf. Text-only results, GIF, BMP and animated PNG are rejected. No image processor is installed: the tool does not resize or convert unsupported input. Preflight checks availability and shape without rendering; use `--execute` to verify the actual image result. Agent reviews need a model supporting image input.
+The package also retains optional script-author helpers such as `agent.text.read()`, `agent.files.read()`, `agent.image.view()`, `human.desktop.open()` and `human.project.open()`. They return metadata/execute contracts that a user script may wrap; they are not configuration registration APIs. Core's `defineTool` is likewise an optional authoring/type helper. CCDD never imports those functions during discovery.
 
 ```sh
-ccdd tools check --artifact preview --for agent --tool view_image --execute
-ccdd tools check --artifact frames --for agent --tool view_image --execute --args '{"path":"preview.png"}'
+ccdd-project tools check --artifact document --for agent --tool read --execute --args '{"path":"notes.md"}'
 ```
 
-Artifact groups are configured in the core as `{kind:'group',members:[ID,...]}`. Tools stay registered on individual Artifact types, and shared leaf members receive one tool binding per operation. `tools check --artifact GROUP` preflights the member tools; execution explicitly selects a leaf.
-
-## Desktop opening
-
-Human tools launch a desktop program and return a launch receipt, never decoded file contents. A successful launcher exit does not prove the person read the file and does not complete a review. Input snapshots are managed and retained by CCDD. Launchers should return after opening the application; avoid a wait-for-editor-exit flag. Preparation checks executable availability without launching the application.
-
-```ts
-human.desktop.open({ app: 'TextEdit' }); // macOS
-human.desktop.open({ command: '/path/to/viewer', args: ['--read-only', '{artifactPath}'] });
-```
-
-`args` are fixed repository configuration and require a standalone `{artifactPath}` token; without `args`, an explicit command receives the Artifact path as its only argument. Reviewers cannot supply a command, argv or environment. The process receives only a small desktop environment allowlist, excluding Provider secrets and `NODE_OPTIONS`. CCDD configuration and custom executables are trusted repository code, not an OS sandbox.
-
-The package contains no runtime import from CCDD and owns no Broker state. Its peer dependency supplies only the shared public tool contract; custom tools may implement that same contract without installing this library.
-
-## Bundled project applications
-
-`human.project.open({ runtime: 'tools/blender', executable: 'blender' })` opens an
-Artifact with a portable application included in the project. `runtime` is a
-project-relative directory and `executable` is relative to it. Optional fixed
-`args` must include `{artifactPath}`; the default passes the Artifact path alone.
-The complete runtime directory participates in the tool's input identity, including
-supported internal relative symlinks. Reviewers cannot choose a different program.
-
-The actual application is launched with isolated writable home/config/cache
-directories in the review output. After successful process launch and the brief
-startup handoff, the reviewer owns the desktop session; it remains open after the
-tool host exits. A launch receipt does not prove rendered content or review
-completion. The immutable input copy remains available for the application.
-
-Use project `envRequirements` for external prerequisites that cannot be bundled.
-See [remote Human review](../../docs/remote-human-review.md) for the full workflow.
-
 ## License
 
-Licensed under the [MIT License](LICENSE).
+[MIT](LICENSE).

package/dist/script.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import type { ScriptToolRequest, ToolResult } from '@ccdd/core';
+/** Standard language-neutral tool entry point. Fixed argv selects the operation. */
+export declare function scriptRequest(operation: string, input: ScriptToolRequest, options?: Record<string, unknown>): Promise<ToolResult>;

package/dist/script.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { readdir } from 'node:fs/promises';
+import { resolveScopePath } from '@ccdd/core';
+import { readerRequest, scopedTarget, objectArguments, internalPath } from './reader.js';
+import { imageRequest } from './image.js';
+import { imageContent } from './image-result.js';
+import { human } from './index.js';
+/** Standard language-neutral tool entry point. Fixed argv selects the operation. */
+export async function scriptRequest(operation, input, options = {}) {
+    if (input.version !== 1 || !input.context || !input.args || Array.isArray(input.args))
+        throw new Error('Expected a version 1 CCDD script request.');
+    const { context, args } = input;
+    if (!Object.hasOwn(context.scope, context.artifactId) || context.scope[context.artifactId].path !== context.artifactPath)
+        throw new Error('Invalid Artifact scope.');
+    const logical = internalPath(args.path), resolved = resolveScopePath(context.scope, context.artifactId, logical);
+    const root = context.scope[resolved.artifactId].path;
+    const target = await scopedTarget(root, true, resolved.path);
+    if (operation === 'read') {
+        objectArguments(args, ['path', 'startLine', 'lineCount']);
+        if (!logical)
+            throw new Error('read requires a file path inside the Artifact.');
+        const data = await readerRequest({ operation: 'read', root: target, directory: false, args: { ...(args.startLine === undefined ? {} : { startLine: args.startLine }), ...(args.lineCount === undefined ? {} : { lineCount: args.lineCount }) } });
+        return { content: [{ type: 'json', data: { ...data, artifactId: context.artifactId, resolvedArtifactId: resolved.artifactId, path: logical } }],
+            ...(typeof data.lineCount === 'number' && data.lineCount > 0 ? { observation: { kind: 'content' } } : data.totalLines === 0 ? { observation: { kind: 'empty' } } : {}) };
+    }
+    if (operation === 'list') {
+        objectArguments(args, ['path', 'offset', 'limit']);
+        const offset = args.offset ?? 0, limit = args.limit ?? 200;
+        if (!Number.isSafeInteger(offset) || Number(offset) < 0 || !Number.isSafeInteger(limit) || Number(limit) < 1 || Number(limit) > 200)
+            throw new Error('Invalid listing pagination.');
+        const entries = (await readdir(target, { withFileTypes: true })).map(entry => ({ name: entry.name, kind: entry.isDirectory() ? 'directory' : entry.isFile() ? 'file' : entry.isSymbolicLink() ? 'symlink' : 'other' }));
+        if (!resolved.path)
+            for (const name of Object.keys(context.scope[resolved.artifactId].mounts))
+                entries.push({ name, kind: 'mount' });
+        entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+        const selected = entries.slice(Number(offset), Number(offset) + Number(limit)).map(entry => ({ ...entry, path: logical ? `${logical}/${entry.name}` : entry.name }));
+        return { content: [{ type: 'json', data: { artifactId: context.artifactId, path: logical, entries: selected, totalEntries: entries.length, nextOffset: Number(offset) + selected.length < entries.length ? Number(offset) + selected.length : null } }] };
+    }
+    if (operation === 'image') {
+        objectArguments(args, ['path']);
+        if (!logical)
+            throw new Error('image requires a file path inside the Artifact.');
+        return { content: [imageContent(await imageRequest({ operation: 'view_image', root: target, directory: false, args: {} }))], observation: { kind: 'content' } };
+    }
+    if (operation === 'open') {
+        objectArguments(args, ['path']);
+        const tool = human.desktop.open(options);
+        return tool.execute({ ...context, signal: new AbortController().signal, artifactDirectory: true,
+            resolvePath: async (name = '') => { const entry = resolveScopePath(context.scope, context.artifactId, name); return scopedTarget(context.scope[entry.artifactId].path, true, entry.path); } }, args);
+    }
+    throw new Error('Select read, list, image or open.');
+}
+try {
+    let text = '';
+    for await (const chunk of process.stdin) {
+        text += chunk;
+        if (Buffer.byteLength(text) > 8 * 1024 * 1024)
+            throw new Error('Script request exceeds 8 MiB.');
+    }
+    const result = await scriptRequest(process.argv[2], JSON.parse(text), process.argv[3] ? JSON.parse(process.argv[3]) : {});
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : 'Artifact tool failed.'}\n`);
+    process.exitCode = 1;
+}
+//# sourceMappingURL=script.js.map

package/dist/script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.js","sourceRoot":"","sources":["../src/script.ts"],"names":[],"mappings":"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"}

package/examples/README.md

@@ -0,0 +1,3 @@
+# Explicit registration
+
+Copy `document/ccdd.json` into a real Artifact folder and adapt its name and Critic. Install the package at the workspace root. All paths in `metadata.executionPaths` are relative to that root. `ccdd-view` resolves from the nearest installed `node_modules/.bin`, then PATH. The caller supplies `path` to select a document or image inside this Artifact, a contained Artifact or a mount. Importing or installing the package registers no tools.

package/examples/document/ccdd.json

@@ -0,0 +1,139 @@
+{
+  "name": "document",
+  "views": {
+    "agentTools": {
+      "read": {
+        "metadata": {
+          "description": "Inspect {artifactName} with read.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "path"
+            ]
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "node_modules/@ccdd/core/dist",
+            "node_modules/@ccdd/default-tools/dist"
+          ]
+        },
+        "script": {
+          "command": "ccdd-view",
+          "args": [
+            "read"
+          ]
+        }
+      },
+      "list": {
+        "metadata": {
+          "description": "Inspect {artifactName} with list.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "none",
+          "executionPaths": [
+            "node_modules/@ccdd/core/dist",
+            "node_modules/@ccdd/default-tools/dist"
+          ]
+        },
+        "script": {
+          "command": "ccdd-view",
+          "args": [
+            "list"
+          ]
+        }
+      },
+      "image": {
+        "metadata": {
+          "description": "Inspect {artifactName} with image.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "path"
+            ]
+          },
+          "resultKinds": [
+            "image"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "node_modules/@ccdd/core/dist",
+            "node_modules/@ccdd/default-tools/dist"
+          ]
+        },
+        "script": {
+          "command": "ccdd-view",
+          "args": [
+            "image"
+          ]
+        }
+      }
+    },
+    "humanTools": {
+      "open": {
+        "metadata": {
+          "description": "Inspect {artifactName} with open.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "resultKinds": [
+            "launch"
+          ],
+          "observation": "none",
+          "executionPaths": [
+            "node_modules/@ccdd/core/dist",
+            "node_modules/@ccdd/default-tools/dist"
+          ]
+        },
+        "script": {
+          "command": "ccdd-view",
+          "args": [
+            "open"
+          ]
+        }
+      }
+    }
+  },
+  "critics": [
+    {
+      "id": "review",
+      "title": "Review the document",
+      "profile": {
+        "kind": "human"
+      },
+      "payload": {
+        "instruction": "Read {document} and assess whether its requirements are clear and verifiable."
+      }
+    }
+  ]
+}

package/package.json

@@ -1,20 +1,48 @@
 {
   "name": "@ccdd/default-tools",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "license": "MIT",
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
-  "repository": { "type": "git", "url": "git+https://github.com/lhj6102/ccdd.git", "directory": "packages/default-tools" },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lhj6102/ccdd.git",
+    "directory": "packages/default-tools"
+  },
   "description": "Explicitly registered Agent CLI and Human desktop Artifact tools for CCDD",
   "type": "module",
-  "engines": { "node": "^22.19.0" },
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "engines": {
+    "node": "^22.19.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "types": "./dist/index.d.ts",
-  "files": ["dist/", "LICENSE", "README.md"],
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md",
+    "examples/"
+  ],
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json",
     "prepack": "npm run build"
   },
-  "peerDependencies": { "@ccdd/core": ">=3.0.0 <4" },
-  "dependencies": { "@earendil-works/pi-agent-core": "0.85.1" },
-  "devDependencies": { "@ccdd/core": "file:../.." }
+  "peerDependencies": {
+    "@ccdd/core": ">=4.0.0 <5"
+  },
+  "dependencies": {
+    "@earendil-works/pi-agent-core": "0.85.1"
+  },
+  "devDependencies": {
+    "@ccdd/core": "file:../.."
+  },
+  "bin": {
+    "ccdd-view": "./dist/script.js"
+  }
 }