@open-agent-toolkit/cli 0.1.73 → 0.1.74

package/dist/providers/cursor/codec/materialize.d.ts

@@ -0,0 +1,24 @@
+import type { CanonicalAgentDocument } from '../../../agents/canonical/index.js';
+import type { CursorModelPinMapping } from './catalog.js';
+import { type CursorRoleOwner } from './shared.js';
+export interface CursorMaterializedAgent {
+    roleName: string;
+    fileName: string;
+    description: string;
+    content: string;
+    owner: CursorRoleOwner;
+    mapping: CursorModelPinMapping;
+}
+export interface CursorMaterializeAgentOptions {
+    agent: CanonicalAgentDocument;
+    mapping: CursorModelPinMapping;
+    owner: CursorRoleOwner;
+}
+export declare function materializeCursorAgent({ agent, mapping, owner, }: CursorMaterializeAgentOptions): CursorMaterializedAgent;
+export declare function materializeCursorAgents(options: {
+    agents: CanonicalAgentDocument[];
+    targets: readonly CursorModelPinMapping[];
+    owner: CursorRoleOwner;
+}): CursorMaterializedAgent[];
+export declare function assertNoUnmanagedCursorAgentCollisions(scopeRoot: string, desiredRoleNames: Iterable<string>): Promise<void>;
+//# sourceMappingURL=materialize.d.ts.map

package/dist/providers/cursor/codec/materialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../../../src/providers/cursor/codec/materialize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAKhE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAQlB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,sBAAsB,CAAC;IAC9B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,KAAK,EAAE,eAAe,CAAC;CACxB;AA4BD,wBAAgB,sBAAsB,CAAC,EACrC,KAAK,EACL,OAAO,EACP,KAAK,GACN,EAAE,6BAA6B,GAAG,uBAAuB,CA8BzD;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACjC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1C,KAAK,EAAE,eAAe,CAAC;CACxB,GAAG,uBAAuB,EAAE,CAwB5B;AAqCD,wBAAsB,sCAAsC,CAC1D,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CA0Ef"}

package/dist/providers/cursor/codec/materialize.js

@@ -0,0 +1,166 @@
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError } from '../../../errors/index.js';
+import { validateRealPathWithinScope } from '../../../fs/paths.js';
+import YAML from 'yaml';
+import { buildCursorMaterializedRoleName, isOatManagedCursorRoleFile, normalizeCursorRoleName, renderCursorManagedComments, } from './shared.js';
+const CURSOR_AGENT_DISCOVERY_DIRECTORIES = [
+    '.cursor/agents',
+    '.claude/agents',
+    '.codex/agents',
+];
+function assertApprovedMapping(mapping) {
+    if (mapping.gateEvidence.gate !== 'g01' ||
+        mapping.gateEvidence.disposition !== 'approved' ||
+        !mapping.gateEvidence.probeName.trim()) {
+        throw new CliError(`Cannot materialize Cursor model ${mapping.ladderModelId}: mapping-specific gate g01 approval is required.`);
+    }
+    if (!/\[[^\]]+\]$/.test(mapping.frontmatterModel)) {
+        throw new CliError(`Cannot materialize Cursor model ${mapping.ladderModelId}: frontmatter model must include a non-empty bracket segment.`);
+    }
+}
+function optionalCursorBoolean(agent, field) {
+    const value = field === 'readonly' ? agent.readonly : agent.frontmatter[field];
+    return typeof value === 'boolean' ? value : undefined;
+}
+export function materializeCursorAgent({ agent, mapping, owner, }) {
+    assertApprovedMapping(mapping);
+    const roleName = buildCursorMaterializedRoleName({
+        agentName: agent.name,
+        ladderModelId: mapping.ladderModelId,
+    });
+    if (!roleName) {
+        throw new CliError('Cannot materialize Cursor role: missing role name.');
+    }
+    const readonly = optionalCursorBoolean(agent, 'readonly');
+    const isBackground = optionalCursorBoolean(agent, 'is_background');
+    const frontmatter = {
+        name: roleName,
+        description: agent.description,
+        model: mapping.frontmatterModel,
+        ...(readonly !== undefined ? { readonly } : {}),
+        ...(isBackground !== undefined ? { is_background: isBackground } : {}),
+    };
+    const yaml = YAML.stringify(frontmatter).trimEnd();
+    const comments = renderCursorManagedComments(roleName, owner).join('\n');
+    return {
+        roleName,
+        fileName: `${roleName}.md`,
+        description: agent.description,
+        content: `---\n${comments}\n${yaml}\n---\n${agent.body}`,
+        owner,
+        mapping,
+    };
+}
+export function materializeCursorAgents(options) {
+    const materialized = options.agents.flatMap((agent) => options.targets.map((mapping) => materializeCursorAgent({
+        agent,
+        mapping,
+        owner: options.owner,
+    })));
+    const byRoleName = new Map();
+    for (const role of materialized) {
+        const existing = byRoleName.get(role.roleName);
+        if (existing) {
+            throw new CliError(`Distinct Cursor targets produced the same Cursor role name ${role.roleName} (${existing.mapping.ladderModelId}, ${role.mapping.ladderModelId}). Refusing ambiguous role writes.`);
+        }
+        byRoleName.set(role.roleName, role);
+    }
+    return materialized.sort((left, right) => left.roleName.localeCompare(right.roleName));
+}
+async function readPathStats(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+function readDeclaredCursorAgentName(content) {
+    const normalized = content.startsWith('\uFEFF') ? content.slice(1) : content;
+    const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(normalized);
+    if (!match?.[1]) {
+        return null;
+    }
+    try {
+        const frontmatter = YAML.parse(match[1]);
+        if (!frontmatter ||
+            typeof frontmatter !== 'object' ||
+            Array.isArray(frontmatter)) {
+            return null;
+        }
+        const name = frontmatter['name'];
+        return typeof name === 'string' && name.trim()
+            ? normalizeCursorRoleName(name)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function assertNoUnmanagedCursorAgentCollisions(scopeRoot, desiredRoleNames) {
+    const desiredNames = new Set(desiredRoleNames);
+    for (const directory of CURSOR_AGENT_DISCOVERY_DIRECTORIES) {
+        const directoryPath = join(scopeRoot, directory);
+        const directoryStats = await readPathStats(directoryPath);
+        if (!directoryStats) {
+            continue;
+        }
+        if (directoryStats.isSymbolicLink()) {
+            throw new CliError(`Cursor agent discovery directory is a symbolic link: ${directory}. Refusing unsafe materialization.`);
+        }
+        if (!directoryStats.isDirectory()) {
+            throw new CliError(`Cursor agent discovery path is not a directory: ${directory}.`);
+        }
+        for (const fileName of await readdir(directoryPath)) {
+            if (!fileName.endsWith('.md')) {
+                continue;
+            }
+            const relativePath = `${directory}/${fileName}`;
+            const absolutePath = join(directoryPath, fileName);
+            const filenameRoleName = normalizeCursorRoleName(fileName);
+            const fileStats = await readPathStats(absolutePath);
+            if (!fileStats) {
+                continue;
+            }
+            if (fileStats.isSymbolicLink()) {
+                try {
+                    await validateRealPathWithinScope(absolutePath, scopeRoot);
+                }
+                catch {
+                    throw new CliError(`Cursor agent definition is a symbolic link at ${relativePath} whose target escapes the sync scope.`);
+                }
+            }
+            if (!fileStats.isFile() && !fileStats.isSymbolicLink()) {
+                continue;
+            }
+            let content;
+            try {
+                content = await readFile(absolutePath, 'utf8');
+            }
+            catch {
+                throw new CliError(`Cursor role name collision at ${relativePath}: existing Markdown definition cannot be verified as OAT-managed.`);
+            }
+            const declaredRoleName = readDeclaredCursorAgentName(content);
+            const filenameCollision = desiredNames.has(filenameRoleName);
+            const declaredCollision = declaredRoleName !== null && desiredNames.has(declaredRoleName);
+            if (!filenameCollision && !declaredCollision) {
+                continue;
+            }
+            if (fileStats.isSymbolicLink()) {
+                throw new CliError(`Cursor agent definition is a symbolic link at ${relativePath} with a colliding role name. Refusing unsafe materialization.`);
+            }
+            const collidingRoleName = declaredCollision
+                ? declaredRoleName
+                : filenameRoleName;
+            if (!isOatManagedCursorRoleFile(content, collidingRoleName)) {
+                throw new CliError(declaredCollision && !filenameCollision
+                    ? `Unmanaged Cursor definition at ${relativePath} declares colliding name ${collidingRoleName}.`
+                    : `Cursor role name collision at ${relativePath}: existing Markdown definition is unmanaged.`);
+            }
+        }
+    }
+}

package/dist/providers/cursor/codec/shared.d.ts

@@ -0,0 +1,14 @@
+export declare const OAT_MANAGED_CURSOR_COMMENT = "# oat-managed: true";
+export declare const OAT_CURSOR_ROLE_COMMENT_PREFIX = "# oat-role: ";
+export declare const OAT_CURSOR_OWNER_COMMENT_PREFIX = "# oat-owner: ";
+export type CursorRoleOwner = 'supported-catalogue' | 'user-config' | 'project-config';
+export declare function normalizeCursorRoleName(input: string): string;
+export declare function buildCursorMaterializedRoleName(options: {
+    agentName: string;
+    ladderModelId: string;
+}): string;
+export declare function renderCursorManagedComments(roleName: string, owner: CursorRoleOwner): string[];
+export declare function isOatManagedCursorRoleFile(content: string, roleName?: string): boolean;
+export declare function readOatManagedCursorRoleName(content: string): string | null;
+export declare function readOatManagedCursorRoleOwner(content: string): CursorRoleOwner | null;
+//# sourceMappingURL=shared.d.ts.map

package/dist/providers/cursor/codec/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../../src/providers/cursor/codec/shared.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAChE,eAAO,MAAM,8BAA8B,iBAAiB,CAAC;AAC7D,eAAO,MAAM,+BAA+B,kBAAkB,CAAC;AAE/D,MAAM,MAAM,eAAe,GACvB,qBAAqB,GACrB,aAAa,GACb,gBAAgB,CAAC;AAYrB,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7D;AAED,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,MAAM,CAIT;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,eAAe,GACrB,MAAM,EAAE,CAcV;AAgDD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAMT;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3E;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,GACd,eAAe,GAAG,IAAI,CAExB"}

package/dist/providers/cursor/codec/shared.js

@@ -0,0 +1,76 @@
+export const OAT_MANAGED_CURSOR_COMMENT = '# oat-managed: true';
+export const OAT_CURSOR_ROLE_COMMENT_PREFIX = '# oat-role: ';
+export const OAT_CURSOR_OWNER_COMMENT_PREFIX = '# oat-owner: ';
+const CURSOR_ROLE_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CURSOR_ROLE_COMMENT_PATTERN = /^# oat-role: ([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+const CURSOR_OWNER_COMMENT_PATTERN = /^# oat-owner: (supported-catalogue|user-config|project-config)$/;
+export function normalizeCursorRoleName(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/\.md$/i, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+export function buildCursorMaterializedRoleName(options) {
+    return normalizeCursorRoleName(`${normalizeCursorRoleName(options.agentName)}-${normalizeCursorRoleName(options.ladderModelId)}`);
+}
+export function renderCursorManagedComments(roleName, owner) {
+    const normalizedRoleName = normalizeCursorRoleName(roleName);
+    if (normalizedRoleName !== roleName ||
+        !CURSOR_ROLE_NAME_PATTERN.test(roleName)) {
+        throw new Error(`Invalid managed Cursor role name: ${roleName}`);
+    }
+    return [
+        OAT_MANAGED_CURSOR_COMMENT,
+        `${OAT_CURSOR_ROLE_COMMENT_PREFIX}${roleName}`,
+        `${OAT_CURSOR_OWNER_COMMENT_PREFIX}${owner}`,
+    ];
+}
+function frontmatterLines(content) {
+    const normalized = content.startsWith('\uFEFF') ? content.slice(1) : content;
+    if (!normalized.startsWith('---\n')) {
+        return null;
+    }
+    const end = normalized.indexOf('\n---', 4);
+    if (end < 0) {
+        return null;
+    }
+    return normalized.slice(4, end).split('\n');
+}
+function parseCursorManagedRoleMarkers(content) {
+    const lines = frontmatterLines(content);
+    if (!lines) {
+        return null;
+    }
+    const managedLines = lines.filter((line) => line.startsWith('# oat-managed:'));
+    const roleLines = lines.filter((line) => line.startsWith('# oat-role:'));
+    const ownerLines = lines.filter((line) => line.startsWith('# oat-owner:'));
+    if (managedLines.length !== 1 ||
+        roleLines.length !== 1 ||
+        ownerLines.length !== 1 ||
+        managedLines[0] !== OAT_MANAGED_CURSOR_COMMENT) {
+        return null;
+    }
+    const roleMatch = CURSOR_ROLE_COMMENT_PATTERN.exec(roleLines[0]);
+    const ownerMatch = CURSOR_OWNER_COMMENT_PATTERN.exec(ownerLines[0]);
+    if (!roleMatch || !ownerMatch) {
+        return null;
+    }
+    return {
+        roleName: roleMatch[1],
+        owner: ownerMatch[1],
+    };
+}
+export function isOatManagedCursorRoleFile(content, roleName) {
+    const markers = parseCursorManagedRoleMarkers(content);
+    return (markers !== null &&
+        (roleName === undefined || markers.roleName === roleName));
+}
+export function readOatManagedCursorRoleName(content) {
+    return parseCursorManagedRoleMarkers(content)?.roleName ?? null;
+}
+export function readOatManagedCursorRoleOwner(content) {
+    return parseCursorManagedRoleMarkers(content)?.owner ?? null;
+}

package/dist/providers/cursor/codec/sync-extension.d.ts

@@ -0,0 +1,37 @@
+import type { CanonicalEntry } from '../../../engine/index.js';
+import { type MaterializationApplyResult, type MaterializationContext, type MaterializationExtension, type MaterializationOperation, type MaterializationPlan, type MaterializationWriteOperation } from '../../shared/index.js';
+import { type CursorModelPinMapping } from './catalog.js';
+import { type CursorRoleOwner } from './shared.js';
+export type CursorExtensionTarget = 'role';
+export interface CursorExtensionOperation extends MaterializationOperation<'cursor', CursorExtensionTarget> {
+    roleName?: string;
+}
+export interface CursorExtensionWriteOperation extends MaterializationWriteOperation<'cursor', CursorExtensionTarget> {
+    roleName?: string;
+}
+export interface CursorExtensionPlanMetadata {
+    cleanupOwners: CursorRoleOwner[];
+    isPartialSync: boolean;
+}
+export interface CursorExtensionPlan extends MaterializationPlan<'cursor', CursorExtensionTarget, CursorExtensionPlanMetadata> {
+    operations: CursorExtensionWriteOperation[];
+}
+export type CursorExtensionApplyResult = MaterializationApplyResult;
+export interface CursorMaterializationTargetOptions {
+    userConfigDir?: string;
+    projectPath?: string | null;
+    env?: NodeJS.ProcessEnv;
+    enabled?: boolean;
+    modelMappings?: readonly CursorModelPinMapping[];
+    supportedTargets?: readonly CursorModelPinMapping[];
+}
+export declare function computeCursorProjectExtensionPlan(scopeRoot: string, canonicalEntries: CanonicalEntry[], allowedCanonicalPaths?: string[], options?: CursorMaterializationTargetOptions): Promise<CursorExtensionPlan>;
+export declare function applyCursorProjectExtensionPlan(scopeRoot: string, plan: CursorExtensionPlan): Promise<CursorExtensionApplyResult>;
+export declare function hasCursorExtensionChanges(plan: CursorExtensionPlan): boolean;
+export declare function summarizeCursorExtension(plan: CursorExtensionPlan): {
+    plannedOperations: number;
+    skipped: number;
+};
+export declare function toCursorExtensionOperations(plan: CursorExtensionPlan): CursorExtensionOperation[];
+export declare const cursorMaterializationExtension: MaterializationExtension<CursorExtensionPlan, MaterializationContext<CursorMaterializationTargetOptions>>;
+//# sourceMappingURL=sync-extension.d.ts.map

package/dist/providers/cursor/codec/sync-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-extension.d.ts","sourceRoot":"","sources":["../../../../src/providers/cursor/codec/sync-extension.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,OAAO,EAIL,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EACnC,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAC;AAMnB,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,wBAAyB,SAAQ,wBAAwB,CACxE,QAAQ,EACR,qBAAqB,CACtB;IACC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,6BAA8B,SAAQ,6BAA6B,CAClF,QAAQ,EACR,qBAAqB,CACtB;IACC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,eAAe,EAAE,CAAC;IACjC,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB,CAC9D,QAAQ,EACR,qBAAqB,EACrB,2BAA2B,CAC5B;IACC,UAAU,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED,MAAM,MAAM,0BAA0B,GAAG,0BAA0B,CAAC;AAQpE,MAAM,WAAW,kCAAkC;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,gBAAgB,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACrD;AAoWD,wBAAsB,iCAAiC,CACrD,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,cAAc,EAAE,EAClC,qBAAqB,CAAC,EAAE,MAAM,EAAE,EAChC,OAAO,GAAE,kCAAuC,GAC/C,OAAO,CAAC,mBAAmB,CAAC,CAmH9B;AA6DD,wBAAsB,+BAA+B,CACnD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,0BAA0B,CAAC,CA0BrC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAE5E;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,mBAAmB,GAAG;IACnE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB,CAEA;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,mBAAmB,GACxB,wBAAwB,EAAE,CAM5B;AAED,eAAO,MAAM,8BAA8B,EAAE,wBAAwB,CACnE,mBAAmB,EACnB,sBAAsB,CAAC,kCAAkC,CAAC,CAY3D,CAAC"}