@cleocode/contracts 2026.5.130 → 2026.5.131

package/src/tools/__tests__/composite.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Contract-shape tests for the composite meta-tool contracts (T11484).
+ *
+ * The RUNTIME for `module-relocation` / `add-workspace-package` is deferred to
+ * epic T11456 (the TOOLS canonical structure that supplies their correct home,
+ * category enum, descriptor schema, and registry — see composite.ts header).
+ * These tests lock the CONTRACT surface that ships now: the breakage-class and
+ * wiring-point SoT arrays, and that the input/result shapes are constructible.
+ *
+ * @epic T11480
+ * @task T11484
+ */
+
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import {
+  ADD_WORKSPACE_PACKAGE_WIRING_POINTS,
+  type AddWorkspacePackageInput,
+  type AddWorkspacePackageResult,
+  MODULE_RELOCATION_BREAKAGE_CLASSES,
+  type ModuleRelocationInput,
+  type ModuleRelocationResult,
+} from '../composite.js';
+
+describe('module-relocation contract (DHQ-032)', () => {
+  it('enumerates exactly the seven breakage classes', () => {
+    expect([...MODULE_RELOCATION_BREAKAGE_CLASSES]).toEqual([
+      'relative-import-depth',
+      'barrels',
+      'js-form-and-dynamic-import',
+      'mirror-test-dirs',
+      'deprecations-yml',
+      'doc-comments',
+      'cross-package-importers',
+    ]);
+    expect(new Set(MODULE_RELOCATION_BREAKAGE_CLASSES).size).toBe(7);
+  });
+
+  it('has a constructible input + result shape', () => {
+    const input: ModuleRelocationInput = {
+      fromPath: 'packages/core/src/a.ts',
+      toPath: 'packages/core/src/sub/a.ts',
+      repoRoot: '/repo',
+    };
+    expect(input.fromPath).toBe('packages/core/src/a.ts');
+
+    const result: ModuleRelocationResult = {
+      toPath: input.toPath,
+      shimLeft: false,
+      dryRun: true,
+      classes: [{ class: 'barrels', files: ['packages/core/src/index.ts'], edits: 1 }],
+      filesTouched: ['packages/core/src/index.ts'],
+    };
+    expect(result.classes[0]?.class).toBe('barrels');
+    expectTypeOf(result.classes).items.toHaveProperty('class');
+  });
+});
+
+describe('add-workspace-package contract (DHQ-027)', () => {
+  it('enumerates exactly the six wiring points', () => {
+    expect([...ADD_WORKSPACE_PACKAGE_WIRING_POINTS]).toEqual([
+      'deps',
+      'tsconfig-refs',
+      'build-mjs-buildpkg',
+      'inline-maps',
+      'boundary-entry',
+      'private-no-readme',
+    ]);
+    expect(new Set(ADD_WORKSPACE_PACKAGE_WIRING_POINTS).size).toBe(6);
+  });
+
+  it('has a constructible input + result shape', () => {
+    const input: AddWorkspacePackageInput = {
+      packageName: '@cleocode/foo',
+      repoRoot: '/repo',
+      consumers: ['@cleocode/core'],
+    };
+    expect(input.packageName).toBe('@cleocode/foo');
+
+    const result: AddWorkspacePackageResult = {
+      packageName: input.packageName,
+      packageDir: 'packages/foo',
+      dryRun: true,
+      points: [{ point: 'deps', files: ['packages/core/package.json'] }],
+    };
+    expect(result.points[0]?.point).toBe('deps');
+    expectTypeOf(result.points).items.toHaveProperty('point');
+  });
+});

package/src/tools/atomic.ts

@@ -0,0 +1,274 @@
+/**
+ * Atomic-tool primitive contracts — the canonical I/O shapes for the CORE SDK
+ * tool layer (E3 · T11403 · SG-PACKAGE-ARCH).
+ *
+ * A **tool primitive** is the smallest stateless unit of side-effecting work an
+ * agent can perform — read a file, write a file, run a shell command, search,
+ * fetch a URL, edit a notebook cell. Each primitive is a PURE function of its
+ * typed input (no session/loop/global coupling); composing primitives into
+ * multi-step capabilities is the job of the SKILLS layer (`packages/skills`),
+ * not the tool layer. The implementations live in `packages/core/src/tools/*`
+ * (T11405-T11407) behind a single deny-first guardrail chokepoint; this module
+ * is their shared contract so `core`, `mcp-adapter`, `caamp`, and `cleo-os`
+ * agree on one shape and never redefine it.
+ *
+ * This is a NEW submodule (`@cleocode/contracts/tools/atomic`) kept separate
+ * from the squatted `contracts/src/tools/index.ts` (query/derivation helpers —
+ * see the E3 inventory note `e3-tools-inventory`). Types-only — no runtime
+ * logic (Gate 10 `contracts-purity`).
+ *
+ * @epic T11390
+ * @task T11403
+ * @saga T11387
+ */
+
+// ---------------------------------------------------------------------------
+// Taxonomy
+// ---------------------------------------------------------------------------
+
+/**
+ * The atomic tool classes. Each class groups primitives that share a side-effect
+ * surface and therefore a guardrail policy (fs → path allowlist, shell → command
+ * denylist, net → egress policy, …).
+ */
+export const TOOL_CLASSES = ['fs', 'shell', 'search', 'net', 'notebook'] as const;
+
+/** One of the canonical {@link TOOL_CLASSES}. */
+export type ToolClass = (typeof TOOL_CLASSES)[number];
+
+/**
+ * Descriptor for a single registered tool primitive. The registry of these is
+ * the SoT for "what atomic tools exist", consumed by the guardrail chokepoint
+ * and (optionally) by the MCP adapter's tool catalog (T11411).
+ */
+export interface ToolPrimitiveDescriptor {
+  /** Stable primitive name (e.g. `readFileText`, `executeShell`). */
+  readonly name: string;
+  /** The side-effect class this primitive belongs to. */
+  readonly class: ToolClass;
+  /** One-line statement of the single responsibility this primitive owns. */
+  readonly responsibility: string;
+  /**
+   * Whether the primitive is a pure function of its input with no
+   * session/loop/global state coupling. Atomic primitives MUST be `true`;
+   * the flag exists so the guardrail + lints can reject stateful drift.
+   */
+  readonly stateless: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// fs primitives
+// ---------------------------------------------------------------------------
+
+/** Input for reading a file's text content. */
+export interface ReadFileInput {
+  /** Absolute path to read. */
+  readonly path: string;
+  /** Text encoding. Defaults to `utf8` in the implementation. */
+  readonly encoding?: 'utf8' | 'utf-8' | 'ascii' | 'latin1';
+}
+
+/** Result of a text read. */
+export interface ReadFileResult {
+  /** Absolute path that was read. */
+  readonly path: string;
+  /** File contents as text. */
+  readonly content: string;
+}
+
+/** Input for an atomic (tmp-then-rename) file write. */
+export interface WriteFileInput {
+  /** Absolute path to write. */
+  readonly path: string;
+  /** Content to write. */
+  readonly content: string;
+  /** Create parent directories if missing. Defaults to `true`. */
+  readonly createDirs?: boolean;
+}
+
+/** Result of a file write. */
+export interface WriteFileResult {
+  /** Absolute path that was written. */
+  readonly path: string;
+  /** Number of bytes written. */
+  readonly bytesWritten: number;
+}
+
+/** Input for an existence check. */
+export interface PathExistsInput {
+  /** Absolute path to test. */
+  readonly path: string;
+}
+
+/** Result of an existence check. */
+export interface PathExistsResult {
+  /** Whether the path exists. */
+  readonly exists: boolean;
+  /** What kind of entry it is, when it exists. */
+  readonly kind?: 'file' | 'directory' | 'other';
+}
+
+// ---------------------------------------------------------------------------
+// shell primitives
+// ---------------------------------------------------------------------------
+
+/** Input for a shell-command execution. */
+export interface ExecuteShellInput {
+  /** Executable to run (NOT a shell string — args are passed separately). */
+  readonly command: string;
+  /** Arguments passed to {@link ExecuteShellInput.command}. */
+  readonly args?: readonly string[];
+  /** Working directory. Defaults to `process.cwd()` in the implementation. */
+  readonly cwd?: string;
+  /** Extra environment variables merged over the inherited environment. */
+  readonly env?: Readonly<Record<string, string>>;
+  /** Hard timeout in milliseconds; the process is killed when exceeded. */
+  readonly timeoutMs?: number;
+}
+
+/** Result of a shell-command execution. */
+export interface ExecuteShellResult {
+  /** Captured standard output. */
+  readonly stdout: string;
+  /** Captured standard error. */
+  readonly stderr: string;
+  /** Process exit code (0 = success). `null` when killed by signal/timeout. */
+  readonly code: number | null;
+}
+
+/** Input for a `git` invocation (a constrained {@link ExecuteShellInput}). */
+export interface RunGitInput {
+  /** Git arguments (e.g. `['status', '--porcelain']`). */
+  readonly args: readonly string[];
+  /** Repository working directory. */
+  readonly cwd?: string;
+  /** Hard timeout in milliseconds. */
+  readonly timeoutMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// search / net / notebook primitives
+// ---------------------------------------------------------------------------
+
+/** Input for a content/path search primitive. */
+export interface SearchInput {
+  /** Pattern to search for (literal or regex per {@link SearchInput.isRegex}). */
+  readonly pattern: string;
+  /** Root directory to search under. */
+  readonly root: string;
+  /** Treat {@link SearchInput.pattern} as a regular expression. */
+  readonly isRegex?: boolean;
+  /** Cap on returned matches. */
+  readonly maxResults?: number;
+}
+
+/** A single search match. */
+export interface SearchMatch {
+  /** Absolute path of the matching file. */
+  readonly path: string;
+  /** 1-based line number of the match. */
+  readonly line: number;
+  /** The matching line's text. */
+  readonly text: string;
+}
+
+/** Result of a search. */
+export interface SearchResult {
+  /** Matches in deterministic (path, line) order. */
+  readonly matches: readonly SearchMatch[];
+  /** Whether {@link SearchInput.maxResults} truncated the results. */
+  readonly truncated: boolean;
+}
+
+/** Input for an outbound HTTP fetch primitive. */
+export interface FetchInput {
+  /** Absolute URL to fetch. */
+  readonly url: string;
+  /** HTTP method. Defaults to `GET`. */
+  readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+  /** Request headers. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Request body (already serialized). */
+  readonly body?: string;
+  /** Hard timeout in milliseconds. */
+  readonly timeoutMs?: number;
+}
+
+/** Result of an HTTP fetch. */
+export interface FetchResult {
+  /** HTTP status code. */
+  readonly status: number;
+  /** Response headers. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** Response body as text. */
+  readonly body: string;
+}
+
+/** Input for a notebook-cell edit primitive. */
+export interface NotebookEditInput {
+  /** Absolute path to the `.ipynb` file. */
+  readonly path: string;
+  /** 0-based index of the cell to edit. */
+  readonly cellIndex: number;
+  /** New source for the cell. */
+  readonly source: string;
+}
+
+/** Result of a notebook-cell edit. */
+export interface NotebookEditResult {
+  /** Absolute path that was edited. */
+  readonly path: string;
+  /** The cell index that changed. */
+  readonly cellIndex: number;
+}
+
+// ---------------------------------------------------------------------------
+// Canonical primitive registry (the SoT for "what atomic tools exist")
+// ---------------------------------------------------------------------------
+
+/**
+ * The canonical atomic-tool primitives. Implementations in
+ * `packages/core/src/tools/*` register against these names; the MCP adapter
+ * (T11411) may derive its catalog from this list rather than hand-listing.
+ */
+export const ATOMIC_TOOL_PRIMITIVES: readonly ToolPrimitiveDescriptor[] = [
+  { name: 'readFileText', class: 'fs', responsibility: 'Read a file as text', stateless: true },
+  { name: 'readJson', class: 'fs', responsibility: 'Read + parse a JSON file', stateless: true },
+  {
+    name: 'writeFileAtomic',
+    class: 'fs',
+    responsibility: 'Atomically write a file (tmp-then-rename)',
+    stateless: true,
+  },
+  {
+    name: 'pathExists',
+    class: 'fs',
+    responsibility: 'Test path existence + kind',
+    stateless: true,
+  },
+  {
+    name: 'executeShell',
+    class: 'shell',
+    responsibility: 'Run a command with explicit cwd/env/timeout',
+    stateless: true,
+  },
+  { name: 'runGit', class: 'shell', responsibility: 'Run a git subcommand', stateless: true },
+  {
+    name: 'search',
+    class: 'search',
+    responsibility: 'Search content/paths under a root',
+    stateless: true,
+  },
+  {
+    name: 'fetch',
+    class: 'net',
+    responsibility: 'Perform an outbound HTTP request',
+    stateless: true,
+  },
+  {
+    name: 'notebookEdit',
+    class: 'notebook',
+    responsibility: 'Replace a notebook cell source',
+    stateless: true,
+  },
+] as const;

package/src/tools/composite.ts

@@ -0,0 +1,173 @@
+/**
+ * Composite meta-tool contracts — typed I/O shapes for repo-structure
+ * velocity-multiplier tools (T11484 · DHQ-027/032 · E-CORE-SELF-TOOLING).
+ *
+ * A **composite tool** COMPOSES atomic primitives (`@cleocode/contracts/tools/
+ * atomic` — fs/shell/search) plus repo-structure knowledge into one guarded,
+ * deterministic, multi-step operation that runs WITHOUT an LLM and returns a
+ * typed result. Per the TOOL-vs-SKILL discriminator (T11456 epic), that makes
+ * these TOOLs (typed return, no agent reasoning), NOT skills (`packages/skills`
+ * markdown capabilities).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PLACEMENT STATUS (read before implementing the runtime)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * These are the CONTRACTS ONLY. The runtime implementations are intentionally
+ * DEFERRED to epic **T11456** (TOOLS canonical structure), because a composite
+ * tool cannot be CORRECTLY placed/named/registered until T11456 lands:
+ *
+ *   - The atomic-tool boundary (`ATOMIC_TOOL_BOUNDARY` in `boundary.ts`, CI
+ *     Gate 11) restricts `packages/core/src/tools/` to ATOMIC, STATELESS
+ *     primitives (the 5 `TOOL_CLASSES`: fs/shell/search/net/notebook). These
+ *     composites are multi-step and repo-structure-aware — NOT atomic primitives
+ *     — so that home is wrong for them.
+ *   - `packages/skills/` (the boundary's `skillsHome`) holds agent-facing
+ *     SKILL.md markdown, not executable TS — also wrong.
+ *   - T11456 defines the missing structure these tools NEED: a closed
+ *     `ToolCategory` enum (it reserves `vcs`/`workflow`/`agent` — the categories
+ *     these compose), strict `<scope>_<category>_<operation>` naming, a
+ *     `ToolDescriptor` zod schema, and a `ToolRegistry` with project>global>core
+ *     precedence. Authoring the runtime + a category BEFORE that epic would
+ *     force a placement T11456 must then rework.
+ *
+ * Shipping the contracts now is the sound, additive, non-blocked unit: it pins
+ * the I/O shape (and enumerates every breakage/wiring class each tool owns) so
+ * the T11456 registry has a stable surface to register against. Types-only — no
+ * runtime logic (CI Gate 10 `contracts-purity`).
+ *
+ * @epic T11480
+ * @task T11484
+ * @see T11456 — TOOLS canonical structure (runtime home + registry + naming)
+ */
+
+// ---------------------------------------------------------------------------
+// module-relocation (DHQ-032)
+// ---------------------------------------------------------------------------
+
+/**
+ * The seven breakage classes a module relocation MUST repair atomically. A
+ * naive `git mv` fixes none of these; leaving any one unrepaired is a red build.
+ * The runtime asserts each class is handled and reports per-class edit counts.
+ */
+export const MODULE_RELOCATION_BREAKAGE_CLASSES = [
+  /** Relative-import depth (`../` vs `../../`) of the moved file's own imports. */
+  'relative-import-depth',
+  /** Barrel (`index.ts`) re-exports that referenced the old path. */
+  'barrels',
+  /** `.js`-suffixed specifiers AND dynamic `import()` specifiers. */
+  'js-form-and-dynamic-import',
+  /** The mirrored `__tests__/` directory for the moved module. */
+  'mirror-test-dirs',
+  /** `deprecations.yml` entries that pointed at the old path. */
+  'deprecations-yml',
+  /** Doc comments / `@see` / `@module` references to the old path. */
+  'doc-comments',
+  /** Cross-package importers that consumed the module via its package path. */
+  'cross-package-importers',
+] as const;
+
+/** One of the {@link MODULE_RELOCATION_BREAKAGE_CLASSES}. */
+export type ModuleRelocationBreakageClass = (typeof MODULE_RELOCATION_BREAKAGE_CLASSES)[number];
+
+/** Input for the `module-relocation` composite tool. */
+export interface ModuleRelocationInput {
+  /** Absolute (or repo-root-relative) path of the module to move. */
+  readonly fromPath: string;
+  /** Destination path for the module. */
+  readonly toPath: string;
+  /** Repository root the operation is scoped to. */
+  readonly repoRoot: string;
+  /**
+   * Leave a re-export shim at {@link ModuleRelocationInput.fromPath} that
+   * re-exports from the new location (for a deprecation cycle) instead of
+   * rewriting every importer. Defaults to `false` (rewrite importers).
+   */
+  readonly leaveShim?: boolean;
+  /** Preview the edit plan without writing. Defaults to `false`. */
+  readonly dryRun?: boolean;
+}
+
+/** Per-class summary of the edits a relocation made (or would make). */
+export interface ModuleRelocationClassReport {
+  /** Which breakage class this entry summarises. */
+  readonly class: ModuleRelocationBreakageClass;
+  /** Repo-relative files edited for this class. */
+  readonly files: readonly string[];
+  /** Total number of edits applied across {@link ModuleRelocationClassReport.files}. */
+  readonly edits: number;
+}
+
+/** Result of a `module-relocation` run. */
+export interface ModuleRelocationResult {
+  /** The module's new path. */
+  readonly toPath: string;
+  /** Whether a re-export shim was left at the old path. */
+  readonly shimLeft: boolean;
+  /** Whether this was a dry-run (no writes performed). */
+  readonly dryRun: boolean;
+  /** Per-breakage-class edit report (one entry per class, even when empty). */
+  readonly classes: readonly ModuleRelocationClassReport[];
+  /** Total repo-relative files touched across every class. */
+  readonly filesTouched: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// add-workspace-package (DHQ-027)
+// ---------------------------------------------------------------------------
+
+/**
+ * The six wiring points a new workspace leaf MUST be threaded through. Missing
+ * any one yields a package that does not build, is not type-resolved, or is
+ * accidentally published. The runtime wires all six and reports each.
+ */
+export const ADD_WORKSPACE_PACKAGE_WIRING_POINTS = [
+  /** `dependencies` / `devDependencies` of consuming packages. */
+  'deps',
+  /** The three `tsconfig` references: root refs, build tsconfig, path mapping. */
+  'tsconfig-refs',
+  /** The `buildPkg(...)` entry in the root `build.mjs` topological wave plan. */
+  'build-mjs-buildpkg',
+  /** esbuild/tsc inline source-map wiring for the new leaf. */
+  'inline-maps',
+  /** The `BOUNDARY_REGISTRY` entry in `packages/contracts/src/boundary.ts`. */
+  'boundary-entry',
+  /** `private: true` + no published README (internal-leaf publish hygiene). */
+  'private-no-readme',
+] as const;
+
+/** One of the {@link ADD_WORKSPACE_PACKAGE_WIRING_POINTS}. */
+export type AddWorkspacePackageWiringPoint = (typeof ADD_WORKSPACE_PACKAGE_WIRING_POINTS)[number];
+
+/** Input for the `add-workspace-package` composite tool. */
+export interface AddWorkspacePackageInput {
+  /** Scoped package name, e.g. `@cleocode/foo`. */
+  readonly packageName: string;
+  /** Directory under `packages/` to create (defaults to the unscoped name). */
+  readonly dirName?: string;
+  /** Repository root the operation is scoped to. */
+  readonly repoRoot: string;
+  /** Packages that should depend on the new leaf (wires the `deps` point). */
+  readonly consumers?: readonly string[];
+  /** Preview the wiring plan without writing. Defaults to `false`. */
+  readonly dryRun?: boolean;
+}
+
+/** Per-point summary of how a wiring point was satisfied. */
+export interface AddWorkspacePackageWiringReport {
+  /** Which wiring point this entry summarises. */
+  readonly point: AddWorkspacePackageWiringPoint;
+  /** Repo-relative files created or edited for this point. */
+  readonly files: readonly string[];
+}
+
+/** Result of an `add-workspace-package` run. */
+export interface AddWorkspacePackageResult {
+  /** The created package's name. */
+  readonly packageName: string;
+  /** Repo-relative directory of the new leaf. */
+  readonly packageDir: string;
+  /** Whether this was a dry-run (no writes performed). */
+  readonly dryRun: boolean;
+  /** Per-wiring-point report (one entry per point, even when empty). */
+  readonly points: readonly AddWorkspacePackageWiringReport[];
+}