@ckeditor/ckeditor5-dev-agents 0.0.1 → 62.4.0

package/dist/commands/resolvefinding.d.ts

@@ -0,0 +1,72 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { Finding } from "../types.js";
+export type ResolveFindingOptions = {
+	/**
+	* `reject`: the finding is wrong. A decision records why, so it is not reported again while the content stays
+	* the same. `dismiss`: the finding is dropped without a decision, so it may be reported again once the judged content
+	* changes, for example when its fix is reverted.
+	*/
+	action: "reject" | "dismiss";
+	/**
+	* The short ID of the finding from the report, or a prefix of it.
+	*/
+	id: string;
+	/**
+	* Why the finding is wrong. Required to reject it.
+	*/
+	reason?: string;
+	/**
+	* Continue when reverting the fix also undoes other fixes that changed the same files.
+	*/
+	force: boolean;
+	/**
+	* An absolute path to the directory with `tasks/` and `targets/`.
+	*/
+	configPath: string;
+	/**
+	* An absolute path to a directory inside the checkout.
+	*/
+	cwd: string;
+	targets: Array<string>;
+	tasks: Array<string>;
+};
+export type ResolvedFinding = {
+	action: "reject" | "dismiss";
+	target: string;
+	finding: Finding;
+	/**
+	* The path of the decision file, relative to the repository root. Only when rejecting.
+	*/
+	decisionFile?: string;
+	/**
+	* The files restored, relative to the repository root.
+	*/
+	revertedFiles: Array<string>;
+	/**
+	* The files of the fix that were not restored, because they had no uncommitted changes to revert.
+	*/
+	unrevertedFiles: Array<string>;
+	/**
+	* Other findings whose fixes were undone. They stay open, and the next run judges and fixes them again.
+	*/
+	reopened: Array<Finding>;
+};
+/**
+* Rejects or dismisses one finding in the working tree of the checkout, by its short ID:
+*
+* 1. If the finding has a fix, every file of the fix is restored: from the base branch on a report branch,
+*    from `HEAD` otherwise.
+* 2. If other fixes changed any of those files, they are lost too. Without `force`, nothing changes and the error
+*    lists them. With `force`, all their files are restored as well, their findings lose the fix, and their units are
+*    judged and fixed again by the next run.
+* 3. The finding leaves `open.json`. When rejecting, a decision file records the reason.
+* 4. `report.md` is regenerated. The changes stay in the working tree for a human to review and commit.
+*/
+export declare function resolveFinding(options: ResolveFindingOptions): Promise<ResolvedFinding>;
+/**
+* Renders what `resolveFinding()` did, as plain text for the console.
+*/
+export declare function renderResolvedFinding(result: ResolvedFinding): string;

package/dist/config/importmodules.d.ts

@@ -0,0 +1,11 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Imports the default export of every file matching the pattern in the directory, sorted by path.
+*/
+export declare function importDefaultExports(directory: string, pattern: string): Promise<Array<{
+	file: string;
+	value: unknown;
+}>>;

package/dist/config/loadconfig.d.ts

@@ -0,0 +1,10 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { Target } from "../types.js";
+/**
+* Loads the targets of the config directory, with their tasks. A directory without tasks or targets is almost always
+* the wrong one, so it throws.
+*/
+export declare function loadConfig(configPath: string): Promise<Map<string, Target>>;

package/dist/config/loadtargets.d.ts

@@ -0,0 +1,14 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import { type LoadedTask } from "./loadtasks.js";
+import type { Target, TargetConfig } from "../types.js";
+/**
+* Loads every target from `<targetsPath>/<name>.{js,mjs,ts,mts}`. Adding a repository means adding a file.
+*/
+export declare function loadTargets(targetsPath: string, tasks: Map<string, LoadedTask>): Promise<Map<string, Target>>;
+export declare function normalizeTarget(config: TargetConfig | undefined, { name, tasks }: {
+	name: string;
+	tasks: Map<string, LoadedTask>;
+}): Target;

package/dist/config/loadtasks.d.ts

@@ -0,0 +1,20 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { Task } from "../types.js";
+export type LoadedTask = {
+	task: Task;
+	/**
+	* An absolute path to the directory of the task.
+	*/
+	directory: string;
+};
+/**
+* Loads every task from `<tasksPath>/<id>/index.{js,mjs,ts,mts}`. Adding a task means adding a directory.
+*/
+export declare function loadTasks(tasksPath: string): Promise<Map<string, LoadedTask>>;
+/**
+* Checks the rules of a task that its type cannot express.
+*/
+export declare function validateTask(task: Task | undefined, id: string): void;

package/dist/config/selecttargets.d.ts

@@ -0,0 +1,14 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { Target } from "../types.js";
+/**
+* Returns the targets to run in a checkout of the `originSlug` repository: the named ones, or every target of
+* the repository. A checkout belongs to one repository, so only the targets of that repository can run in it.
+*/
+export declare function selectTargets(targets: Map<string, Target>, { originSlug, names, taskIds }: {
+	originSlug: string | undefined;
+	names: Array<string>;
+	taskIds: Array<string>;
+}): Array<Target>;

package/dist/constants.d.ts

@@ -0,0 +1,20 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* The directory, relative to the target root, that holds the state of every task.
+*/
+export declare const STATE_DIRECTORY = ".ai-tasks";
+/**
+* The prefix of report branches: `ai-tasks/<task>/<target>/<branch>`.
+*/
+export declare const REPORT_BRANCH_PREFIX = "ai-tasks";
+/**
+* The tools an agent may use while judging. None of them can change a file.
+*/
+export declare const READ_ONLY_TOOLS: ReadonlyArray<string>;
+/**
+* Every built-in tool of the Pi agent. The agent ignores unknown tool names, so the configuration is checked against it.
+*/
+export declare const AGENT_TOOLS: ReadonlyArray<string>;

package/dist/define.d.ts

@@ -0,0 +1,33 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { FileUnit, TargetConfig, Task, TaskOptions, TaskUnit } from "./types.js";
+/**
+* Defines a task. It returns the task unchanged and only helps with types: they are inferred from the task itself,
+* so every hook knows its input without annotations.
+*
+* * `options` from `defaultOptions`,
+* * `shared` from what `prepare()` returns,
+* * `unit` from what `scope()` returns, or `FileUnit` (with a `path`) for a task that works on `include`,
+* * `payload` from what `payload()` returns.
+*
+* ```ts
+* export default defineTask( {
+* 	id: 'meta-description',
+* 	include: [ 'docs/**\/*.md' ],
+* 	defaultOptions: { maxLength: 160 },
+* 	…
+* } );
+* ```
+*/
+export declare function defineTask<
+	TShared = undefined,
+	TUnit extends TaskUnit = FileUnit,
+	TPayload = unknown,
+	TOptions extends TaskOptions = TaskOptions
+>(task: Task<TShared, TUnit, TPayload, TOptions>): Task<TShared, TUnit, TPayload, TOptions>;
+/**
+* Defines a target. It returns the target unchanged and only helps with types.
+*/
+export declare function defineTarget(target: TargetConfig): TargetConfig;

package/dist/git/gitworkspace.d.ts

@@ -0,0 +1,72 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+export type GitWorkspace = {
+	/**
+	* An absolute path to the root of the repository.
+	*/
+	path: string;
+	/**
+	* The checked-out branch: the base of the report branches. `HEAD` when it is detached.
+	*/
+	branch: string;
+	/**
+	* The repository on GitHub that `origin` points to, for example `ckeditor/ckeditor5`, or `undefined`.
+	*/
+	originSlug: string | undefined;
+	/**
+	* Throws when the checkout cannot be published from: a detached `HEAD`, uncommitted changes, a shallow history,
+	* or ignored `paths` (relative to the repository root) that the run must commit. The environment that runs
+	* the framework must prepare the checkout correctly.
+	*/
+	assertPublishable(paths: Array<string>): Promise<void>;
+	/**
+	* Checks out the report branch of a task.
+	*
+	* When the report pull request is open, it continues that branch and merges the base branch into it first, so
+	* decisions and fixes merged to the base branch meanwhile are taken into account. A regular merge commit keeps
+	* review comments anchored. When there is no open pull request, a fresh branch starts at the base branch.
+	*/
+	checkoutReportBranch(options: {
+		name: string;
+		continueExisting: boolean;
+	}): Promise<void>;
+	/**
+	* Commits the given paths (relative to the repository root). Returns `false` when there was nothing to commit.
+	*/
+	commit(paths: Array<string>, message: string): Promise<boolean>;
+	/**
+	* Pushes the report branch with the credentials of the checkout. The first push of a replaced branch is forced,
+	* every later push is not.
+	*/
+	push(): Promise<void>;
+	/**
+	* Drops anything a failed task left behind on the report branch and checks out the base branch again.
+	*/
+	returnToBase(): Promise<void>;
+	/**
+	* Whether the ref (a branch, a remote branch, or a commit) exists.
+	*/
+	refExists(ref: string): Promise<boolean>;
+	/**
+	* Whether any of the files (relative to the repository root) has uncommitted changes, or is untracked.
+	*/
+	hasChanges(paths: Array<string>): Promise<boolean>;
+	/**
+	* Restores the files (relative to the repository root) to their content at the ref. A file that does not exist
+	* at the ref is deleted.
+	*/
+	restore(paths: Array<string>, ref: string): Promise<void>;
+};
+/**
+* Opens the checkout that contains `cwd`. The checkout is prepared by whoever runs the framework: cloned, with
+* the dependencies installed, and with the base branch checked out. The `author` is needed only to commit.
+*/
+export declare function openWorkspace({ cwd, author }: {
+	cwd: string;
+	author?: {
+		name: string;
+		email: string;
+	};
+}): Promise<GitWorkspace>;

package/dist/github/githubclient.d.ts

@@ -0,0 +1,39 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+export type PullRequest = {
+	number: number;
+	html_url: string;
+};
+export type GitHubClient = {
+	/**
+	* Returns the open pull request from the branch, or `null`. The base branch is not a criterion: a human may change
+	* it in the pull request.
+	*/
+	findOpenPullRequest(options: {
+		slug: string;
+		head: string;
+	}): Promise<PullRequest | null>;
+	createPullRequest(options: {
+		slug: string;
+		head: string;
+		base: string;
+		title: string;
+		body: string;
+	}): Promise<PullRequest>;
+	updatePullRequest(options: {
+		slug: string;
+		number: number;
+		body: string;
+	}): Promise<PullRequest>;
+	createComment(options: {
+		slug: string;
+		number: number;
+		body: string;
+	}): Promise<unknown>;
+};
+/**
+* Creates a minimal client of the GitHub REST API with the calls that report pull requests need.
+*/
+export declare function createGitHubClient(token: string): GitHubClient;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+export { defineTask, defineTarget } from "./define.js";
+export { findingSchema } from "./utils/findingschema.js";
+export type { FileUnit, Finding, FindingInput, FixInput, JudgeInput, PrepareInput, PriorDecision, ScopeInput, TargetConfig, Task, TaskUnit, UnitInput, VerifyInput } from "./types.js";

package/dist/index.js

@@ -0,0 +1,79 @@
+//#region src/define.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Defines a task. It returns the task unchanged and only helps with types: they are inferred from the task itself,
+* so every hook knows its input without annotations.
+*
+* * `options` from `defaultOptions`,
+* * `shared` from what `prepare()` returns,
+* * `unit` from what `scope()` returns, or `FileUnit` (with a `path`) for a task that works on `include`,
+* * `payload` from what `payload()` returns.
+*
+* ```ts
+* export default defineTask( {
+* 	id: 'meta-description',
+* 	include: [ 'docs/**\/*.md' ],
+* 	defaultOptions: { maxLength: 160 },
+* 	…
+* } );
+* ```
+*/
+function defineTask(task) {
+	return task;
+}
+/**
+* Defines a target. It returns the target unchanged and only helps with types.
+*/
+function defineTarget(target) {
+	return target;
+}
+//#endregion
+//#region src/utils/findingschema.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* Returns the JSON Schema of the findings a judge returns, wrapped in an object (`{ findings: [ … ] }`),
+* because structured-output APIs require an object at the top level. Pass it as `outputSchema` to `agent.run()`.
+*/
+function findingSchema({ ruleIds }) {
+	return {
+		type: "object",
+		properties: { findings: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					ruleId: {
+						type: "string",
+						enum: [...ruleIds],
+						description: "The rule the finding breaks."
+					},
+					detail: {
+						type: "string",
+						minLength: 1,
+						description: "A short explanation of what is wrong, written for the person who fixes it."
+					},
+					discriminator: {
+						type: "string",
+						description: "Tells apart findings of the same rule in the same unit, for example a heading."
+					}
+				},
+				required: ["ruleId", "detail"]
+			}
+		} },
+		required: ["findings"]
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+//#endregion
+export { defineTarget, defineTask, findingSchema };

package/dist/report/renderconsolesummary.d.ts

@@ -0,0 +1,9 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { TargetResult } from "../runtasks.js";
+/**
+* Renders what a run did, as plain text for the console: one block per task of every target.
+*/
+export declare function renderConsoleSummary(targets: Array<TargetResult>): string;

package/dist/report/renderpullrequest.d.ts

@@ -0,0 +1,28 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { Target, TaskSummary } from "../types.js";
+/**
+* Renders the description of the report pull request. It is rewritten on every run that pushes,
+* so it always shows the current number of findings.
+*/
+export declare function renderPullRequestBody({ task, target, branch, reportBranch, open, fixed }: {
+	task: {
+		id: string;
+		title: string;
+	};
+	target: Pick<Target, "name" | "root" | "slug">;
+	branch: string;
+	reportBranch: string;
+	open: number;
+	fixed: number;
+}): string;
+/**
+* Renders the comment posted after every run that pushed something.
+*/
+export declare function renderRunComment({ today, summary, buildUrl }: {
+	today: string;
+	summary: TaskSummary;
+	buildUrl?: string;
+}): string;

package/dist/report/renderreport.d.ts

@@ -0,0 +1,18 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { Finding, Target } from "../types.js";
+/**
+* Renders `report.md` of one task from its findings. The file is regenerated on every run,
+* so `open.json` stays the only source of truth.
+*/
+export declare function renderReport({ task, target, branch, open }: {
+	task: {
+		id: string;
+		title: string;
+	};
+	target: Pick<Target, "root" | "slug">;
+	branch: string;
+	open: Array<Finding>;
+}): string;

package/dist/runner/changetracker.d.ts

@@ -0,0 +1,37 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+/**
+* The state before a fix: `HEAD`, the whole working tree as a git tree, and the exact Git index, so staged changes
+* can be restored too.
+*/
+export type ChangeSnapshot = {
+	head: string;
+	tree: string;
+	index: Buffer | null;
+};
+export type ChangeTracker = {
+	capture(): Promise<ChangeSnapshot>;
+	/**
+	* Inspects changes relative to the snapshot without modifying HEAD, the index or files.
+	*/
+	collect(snapshot: ChangeSnapshot): Promise<{
+		changed: Array<string>;
+		headMoved: boolean;
+	}>;
+	/**
+	* Returns the given paths, `HEAD` and the index to their state in the snapshot. It undoes a fix with the snapshot
+	* from before it, and brings the fix back with a snapshot taken while it was applied.
+	*/
+	restore(snapshot: ChangeSnapshot, paths: Array<string>): Promise<void>;
+};
+/**
+* Tracks what `fix()` changes in a git working tree. It sees every file git sees: tracked files and untracked files
+* that are not ignored. The working tree may already have changes (the kept fixes of earlier units, or local changes
+* in a local run). Only what changes after a snapshot counts.
+*
+* A snapshot stores the working tree as a tree object, written through a copy of the index, so the real index
+* is never touched.
+*/
+export declare function createChangeTracker(root: string): Promise<ChangeTracker>;

package/dist/runner/createcontext.d.ts

@@ -0,0 +1,22 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { Agent, TaskContext, TaskPhase, WritableTaskContext } from "../types.js";
+type ContextOptions = {
+	root: string;
+	phase: TaskPhase;
+	options: Record<string, unknown>;
+	agent: Agent;
+	log: (message: string) => void;
+};
+/**
+* Creates the `ctx` of the judging phase. It can read the target, but not change it.
+*/
+export declare function createTaskContext({ root, phase, options, agent, log }: ContextOptions): TaskContext;
+/**
+* Creates the `ctx` of `fix()` and `verify()`. It can also change files and run commands in the target root.
+*/
+export declare function createWritableTaskContext(options: ContextOptions): WritableTaskContext;
+export declare function resolveInside(root: string, path: string): string;
+export {};

package/dist/runner/fixunit.d.ts

@@ -0,0 +1,64 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { ChangeTracker } from "./changetracker.js";
+import type { AppliedFix, Finding, Task, TaskUnit, WritableTaskContext } from "../types.js";
+/**
+* What the run does with one unit, shared by judging and by checking fixes.
+*/
+export type UnitOperations = {
+	contentHash(unit: TaskUnit): Promise<string>;
+	/**
+	* Returns the validated findings of `judge()` about the unit, without duplicates.
+	*/
+	judge(unit: TaskUnit, fragment: string): Promise<Array<Finding>>;
+	/**
+	* Whether a decision that still holds rejects the finding.
+	*/
+	isRejected(finding: Finding): boolean;
+};
+/**
+* One unit in a run. `current` follows accepted fixes, including fixes made while processing another unit. Only
+* the units selected for this run are `judged` and may advance their baseline. Checking a deferred unit during a fix
+* does not select it.
+*/
+export type UnitRun = {
+	unit: TaskUnit;
+	current?: {
+		fragment: string;
+		findings?: Array<Finding>;
+	};
+	judged?: Array<Finding>;
+	error?: string;
+	discarded?: {
+		message: string;
+		findings: number;
+	};
+	fixes: Map<string, Omit<AppliedFix, "fragment">>;
+};
+export type FixOutcome = {
+	status: "none";
+} | {
+	status: "discarded";
+	message: string;
+	findings: number;
+} | {
+	status: "kept";
+	files: Array<string>;
+	resolved: Map<UnitRun, Set<string>>;
+};
+export type FixUnitOptions = UnitOperations & {
+	task: Task;
+	shared: unknown;
+	root: string;
+	units: Map<string, UnitRun>;
+	tracker: ChangeTracker;
+	fixContext: WritableTaskContext;
+	verifyContext: WritableTaskContext;
+};
+/**
+* Fixes one unit transactionally. Every affected unit is checked, including units whose hash depends on
+* files outside their own path. A later fix must preserve the accepted judgments of earlier fixes.
+*/
+export declare function fixUnit(runner: FixUnitOptions, record: UnitRun, actionable: Array<Finding>): Promise<FixOutcome>;

package/dist/runner/runtarget.d.ts

@@ -0,0 +1,49 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { GitWorkspace } from "../git/gitworkspace.js";
+import type { GitHubClient } from "../github/githubclient.js";
+import type { Target, TaskSummary } from "../types.js";
+export type TaskResult = {
+	task: string;
+	title: string;
+	durationMs: number;
+	/**
+	* Missing when the task failed before it finished. A task whose publishing failed has both.
+	*/
+	summary?: TaskSummary;
+	failure?: string;
+	pullRequestUrl?: string;
+};
+export type RunTargetOptions = {
+	target: Target;
+	/**
+	* Tasks requested explicitly. When empty, the tasks enabled in the target run.
+	*/
+	taskIds: Array<string>;
+	workspace: GitWorkspace;
+	/**
+	* Set for a published run. Without it, the results stay in the working tree.
+	*/
+	github?: GitHubClient;
+	today: string;
+	/**
+	* Receives the progress of the run, the tool calls of the agent, and the messages of `log()` in the hooks.
+	*/
+	log: (message: string) => void;
+	/**
+	* Published run: linked from the run comment.
+	*/
+	buildUrl?: string;
+};
+/**
+* Runs the selected tasks against one target, in the working tree of the checkout.
+*
+* Both flows judge, fix, and write the state in the checkout. Kept fixes and the state stay in the files. A local run
+* stops there: nothing is committed or pushed. A published run does every task on its own report branch: it continues
+* the open report pull request or starts a new branch at the base branch, commits and pushes once, opens or updates
+* the pull request, and checks out the base branch again.
+*/
+export declare function runTarget(options: RunTargetOptions): Promise<Array<TaskResult>>;
+export declare function getReportBranch(taskId: string, target: Pick<Target, "name">, branch: string): string;