@open-agent-toolkit/cli 0.3.37 → 0.3.39

package/dist/providers/codex/codec/sync-extension.js

@@ -12,7 +12,7 @@ import TOML from '@iarna/toml';
 import { hasMaterializationChanges, summarizeMaterializationPlan, } from '../../shared/index.js';
 import YAML from 'yaml';
 import { SUPPORTED_CODEX_BASE_ROLES, SUPPORTED_CODEX_ROLE_TARGETS, } from './catalog.js';
-import { mergeCodexConfig, readCodexMaxDepth, } from './config-merge.js';
+import { describeCodexConfigMerge, mergeCodexConfig, readCodexMaxDepth, } from './config-merge.js';
 import { exportCanonicalAgentToCodexRole } from './export-to-codex.js';
 import { materializeCodexRole } from './materialize.js';
 import { isOatManagedCodexRoleFile, readOatManagedCodexRoleOwner, withOatManagedCodexRoleOwner, } from './shared.js';
@@ -35,6 +35,13 @@ async function readOptionalFile(path) {
     }
     return readFile(path, 'utf8');
 }
+function describeConfigOperation(summary, configMerge) {
+    const details = describeCodexConfigMerge(configMerge);
+    if (configMerge.removedRoles.length > 0) {
+        details.unshift(`removes stale role tables: ${configMerge.removedRoles.map((role) => `agents.${role}`).join(', ')}`);
+    }
+    return [summary, ...details].join('; ');
+}
 function normalizeManagedRolesConfig(desiredRoles) {
     return desiredRoles.map((role) => ({
         roleName: role.roleName,
@@ -42,7 +49,7 @@ function normalizeManagedRolesConfig(desiredRoles) {
         configFile: role.configFile,
     }));
 }
-async function desiredRolesFromCanonical(canonicalEntries, scopeRoot, materializationTargets) {
+async function desiredRolesFromCanonical(canonicalEntries, scopeRoot, materializationTargets, scopeOwner) {
     const roles = [];
     for (const entry of canonicalEntries) {
         if (entry.type !== 'agent' ||
@@ -57,7 +64,7 @@ async function desiredRolesFromCanonical(canonicalEntries, scopeRoot, materializ
             description: exported.description,
             configFile: exported.configFile,
             rolePath: join(scopeRoot, '.codex', exported.configFile),
-            content: exported.content,
+            content: withOatManagedCodexRoleOwner(exported.content, scopeOwner),
             sourcePath: entry.canonicalPath,
         });
         if (CODEX_MATERIALIZED_BASE_ROLES.has(exported.roleName)) {
@@ -329,9 +336,47 @@ function parseConfigAgentTable(content) {
         return {};
     }
 }
-async function collectStaleManagedRoles(scopeRoot, existingConfigContent, desiredRoleNames, cleanupOwner, removeLegacyProjectRoles) {
+function codexScopeOwner(scopeRoot, options) {
+    return isUserCodexScope(scopeRoot, options)
+        ? 'user-config'
+        : 'project-config';
+}
+function codexCleanupOwners(scopeRoot, options) {
+    return isUserCodexScope(scopeRoot, options)
+        ? ['user-config']
+        : ['supported-catalogue', 'project-config'];
+}
+/**
+ * Whether a partial sync removes a canonical agent. A removed file can no
+ * longer be parsed for the role name it declared, so such a sync runs the full
+ * stale cleanup against the roles every present canonical agent produces.
+ */
+function removesCanonicalAgent(canonicalEntries, allowedCanonicalPaths) {
+    const presentFiles = new Set(canonicalEntries
+        .filter((entry) => entry.type === 'agent' && entry.isFile)
+        .map((entry) => entry.name));
+    return allowedCanonicalPaths.some((path) => {
+        const match = /^\.agents\/agents\/([^/]+\.md)$/.exec(path);
+        return match?.[1] !== undefined && !presentFiles.has(match[1]);
+    });
+}
+async function collectStaleManagedRoles(scopeRoot, existingConfigContent, desiredRoleNames, cleanupOwners, removeLegacyProjectRoles) {
     const agents = parseConfigAgentTable(existingConfigContent);
-    const stale = new Set();
+    const staleFiles = new Set();
+    const staleTables = new Set();
+    const isStaleManagedRole = (roleName, roleContent) => {
+        if (!roleContent || !isOatManagedCodexRoleFile(roleContent, roleName)) {
+            return false;
+        }
+        const owner = readOatManagedCodexRoleOwner(roleContent);
+        const legacyProjectRole = removeLegacyProjectRoles &&
+            owner === null &&
+            SUPPORTED_CODEX_BASE_ROLES.some((baseRole) => roleName.startsWith(`${baseRole}-`));
+        return ((owner !== null && cleanupOwners.includes(owner)) || legacyProjectRole);
+    };
+    // Stale cleanup deletes files, so a candidate whose real path (through a
+    // symlinked file or `.codex/agents` directory) leaves the scope is skipped.
+    const isWithinScope = (rolePath) => validateRealPathWithinScope(rolePath, scopeRoot).then(() => true, () => false);
     for (const [roleName, roleConfig] of Object.entries(agents)) {
         if (desiredRoleNames.has(roleName)) {
             continue;
@@ -341,18 +386,12 @@ async function collectStaleManagedRoles(scopeRoot, existingConfigContent, desire
             continue;
         }
         const rolePath = join(scopeRoot, '.codex', configFile);
-        const roleContent = await readOptionalFile(rolePath);
-        if (!roleContent || !isOatManagedCodexRoleFile(roleContent, roleName)) {
+        if (!(await isWithinScope(rolePath)) ||
+            !isStaleManagedRole(roleName, await readOptionalFile(rolePath))) {
             continue;
         }
-        const owner = readOatManagedCodexRoleOwner(roleContent);
-        const legacyProjectRole = removeLegacyProjectRoles &&
-            owner === null &&
-            SUPPORTED_CODEX_BASE_ROLES.some((baseRole) => roleName.startsWith(`${baseRole}-`));
-        if (owner !== cleanupOwner && !legacyProjectRole) {
-            continue;
-        }
-        stale.add(roleName);
+        staleTables.add(roleName);
+        staleFiles.add(roleName);
     }
     const agentsDir = join(scopeRoot, '.codex', 'agents');
     let roleFiles;
@@ -367,28 +406,27 @@ async function collectStaleManagedRoles(scopeRoot, existingConfigContent, desire
             continue;
         }
         const roleName = basename(roleFile, '.toml');
-        if (desiredRoleNames.has(roleName) || stale.has(roleName)) {
+        if (desiredRoleNames.has(roleName) || staleFiles.has(roleName)) {
             continue;
         }
         const rolePath = join(agentsDir, roleFile);
-        const roleContent = await readOptionalFile(rolePath);
-        if (!roleContent || !isOatManagedCodexRoleFile(roleContent, roleName)) {
-            continue;
-        }
-        const owner = readOatManagedCodexRoleOwner(roleContent);
-        const legacyProjectRole = removeLegacyProjectRoles &&
-            owner === null &&
-            SUPPORTED_CODEX_BASE_ROLES.some((baseRole) => roleName.startsWith(`${baseRole}-`));
-        if (owner !== cleanupOwner && !legacyProjectRole) {
+        if (!(await isWithinScope(rolePath)) ||
+            !isStaleManagedRole(roleName, await readOptionalFile(rolePath))) {
             continue;
         }
-        stale.add(roleName);
+        // A table of the same name that points elsewhere was re-pointed by the
+        // user; only the leftover file is OAT's to remove.
+        staleFiles.add(roleName);
     }
-    return [...stale].sort((left, right) => left.localeCompare(right));
+    const sorted = (names) => [...names].sort((left, right) => left.localeCompare(right));
+    return { roleFiles: sorted(staleFiles), configTables: sorted(staleTables) };
 }
 export async function computeCodexProjectExtensionPlan(scopeRoot, canonicalEntries, allowedCanonicalPaths, options = {}) {
     const isPartialSync = allowedCanonicalPaths !== undefined && allowedCanonicalPaths.length > 0;
+    const cleansStaleRoles = !isPartialSync ||
+        removesCanonicalAgent(canonicalEntries, allowedCanonicalPaths);
     const materializationTargets = await readCodexMaterializationTargets(scopeRoot, options);
+    const scopeOwner = codexScopeOwner(scopeRoot, options);
     if (!isPartialSync &&
         isUserCodexScope(scopeRoot, options) &&
         materializationTargets.length > 0) {
@@ -400,11 +438,20 @@ export async function computeCodexProjectExtensionPlan(scopeRoot, canonicalEntri
             throw new CliError(`Bundled managed Codex role definitions are unavailable for user sync: ${missingBaseRoles.join(', ')}. Refusing stale user-role cleanup.`);
         }
     }
-    const desiredRoles = await desiredRolesFromCanonical(canonicalEntries.filter((entry) => canonicalPathAllowed(scopeRoot, entry, allowedCanonicalPaths)), scopeRoot, materializationTargets);
+    const desiredRoles = await desiredRolesFromCanonical(canonicalEntries.filter((entry) => canonicalPathAllowed(scopeRoot, entry, allowedCanonicalPaths)), scopeRoot, materializationTargets, scopeOwner);
     const desiredRoleNames = new Set(desiredRoles.map((role) => role.roleName));
     const existingConfigPath = configPath(scopeRoot);
     const existingConfigContent = await readOptionalFile(existingConfigPath);
-    if (isPartialSync && desiredRoles.length === 0) {
+    const producedRoleNames = isPartialSync && cleansStaleRoles
+        ? new Set((await desiredRolesFromCanonical(canonicalEntries, scopeRoot, materializationTargets, scopeOwner)).map((role) => role.roleName))
+        : desiredRoleNames;
+    const staleRoles = cleansStaleRoles
+        ? await collectStaleManagedRoles(scopeRoot, existingConfigContent, producedRoleNames, codexCleanupOwners(scopeRoot, options), !isUserCodexScope(scopeRoot, options))
+        : { roleFiles: [], configTables: [] };
+    if (isPartialSync &&
+        desiredRoles.length === 0 &&
+        staleRoles.roleFiles.length === 0 &&
+        staleRoles.configTables.length === 0) {
         const aggregateConfigHash = hashContent(existingConfigContent ?? '');
         return {
             provider: 'codex',
@@ -420,9 +467,6 @@ export async function computeCodexProjectExtensionPlan(scopeRoot, canonicalEntri
         };
     }
     const inheritedMaxDepth = await readInheritedCodexMaxDepth(scopeRoot, options);
-    const staleRoles = isPartialSync
-        ? []
-        : await collectStaleManagedRoles(scopeRoot, existingConfigContent, desiredRoleNames, isUserCodexScope(scopeRoot, options) ? 'user-config' : 'project-config', !isUserCodexScope(scopeRoot, options));
     const operations = [];
     for (const role of desiredRoles) {
         const existingRoleContent = await readOptionalFile(role.rolePath);
@@ -462,10 +506,12 @@ export async function computeCodexProjectExtensionPlan(scopeRoot, canonicalEntri
             roleName: role.roleName,
         });
     }
-    for (const staleRole of staleRoles) {
+    for (const staleRole of staleRoles.roleFiles) {
         const staleRolePath = join(scopeRoot, '.codex', 'agents', `${staleRole}.toml`);
         const staleRoleContent = await readOptionalFile(staleRolePath);
-        if (staleRoleContent &&
+        const staleRoleWithinScope = await validateRealPathWithinScope(staleRolePath, scopeRoot).then(() => true, () => false);
+        if (staleRoleWithinScope &&
+            staleRoleContent &&
             isOatManagedCodexRoleFile(staleRoleContent, staleRole)) {
             operations.push({
                 provider: 'codex',
@@ -481,7 +527,7 @@ export async function computeCodexProjectExtensionPlan(scopeRoot, canonicalEntri
     const configMerge = mergeCodexConfig({
         existingContent: existingConfigContent,
         desiredRoles: normalizeManagedRolesConfig(desiredRoles),
-        staleManagedRoles: staleRoles,
+        staleManagedRoles: staleRoles.configTables,
         inheritedMaxDepth,
     });
     operations.push({
@@ -493,16 +539,16 @@ export async function computeCodexProjectExtensionPlan(scopeRoot, canonicalEntri
                 : 'skip',
         target: 'config',
         path: '.codex/config.toml',
-        reason: existingConfigContent === null
+        reason: describeConfigOperation(existingConfigContent === null
             ? 'codex config missing'
             : configMerge.changed
                 ? 'codex config differs from desired managed state'
-                : 'codex config already in sync',
+                : 'codex config already in sync', configMerge),
         content: configMerge.mergedContent,
     });
     const managedRoles = [
         ...desiredRoles.map((role) => role.roleName),
-        ...staleRoles,
+        ...staleRoles.roleFiles,
     ];
     const aggregateConfigHash = hashContent(configMerge.mergedContent);
     return {

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

@@ -1 +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;AAEvD,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;AAWD,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"}
+{"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;AAEvD,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;AAWD,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;AAgDD,wBAAsB,sCAAsC,CAC1D,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CA+Ef"}

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

@@ -1,4 +1,4 @@
-import { lstat, readFile, readdir } from 'node:fs/promises';
+import { lstat, readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { CliError } from '../../../errors/index.js';
 import { validateRealPathWithinScope } from '../../../fs/paths.js';
@@ -70,6 +70,17 @@ async function readPathStats(path) {
         throw error;
     }
 }
+async function isDanglingLink(path) {
+    try {
+        await stat(path);
+        return false;
+    }
+    catch (error) {
+        // Other failures, such as a link loop, fall through to the scope check
+        // and its controlled refusal.
+        return error.code === 'ENOENT';
+    }
+}
 function readDeclaredCursorAgentName(content) {
     const normalized = content.startsWith('\uFEFF') ? content.slice(1) : content;
     const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(normalized);
@@ -118,6 +129,11 @@ export async function assertNoUnmanagedCursorAgentCollisions(scopeRoot, desiredR
                 continue;
             }
             if (fileStats.isSymbolicLink()) {
+                // A dangling link cannot define a role, and the main sync plan
+                // removes the manifest-tracked view it was created as.
+                if (await isDanglingLink(absolutePath)) {
+                    continue;
+                }
                 try {
                     await validateRealPathWithinScope(absolutePath, scopeRoot);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.37",
+  "version": "0.3.39",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -41,8 +41,8 @@
     "unified": "11.0.5",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.37",
-    "@open-agent-toolkit/docs-transforms": "0.3.37"
+    "@open-agent-toolkit/control-plane": "0.3.39",
+    "@open-agent-toolkit/docs-transforms": "0.3.39"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",