Speed up lightweight CLI commands and reuse output declarations

Author: TrueNine

cli/src/cli-runtime.test.ts

@@ -0,0 +1,67 @@
+import {afterEach, describe, expect, it, vi} from 'vitest'
+
+const {
+  createDefaultPluginConfigMock,
+  pipelineRunMock,
+  pluginPipelineCtorMock
+} = vi.hoisted(() => ({
+  createDefaultPluginConfigMock: vi.fn(),
+  pipelineRunMock: vi.fn(),
+  pluginPipelineCtorMock: vi.fn()
+}))
+
+vi.mock('./plugin.config', () => ({
+  createDefaultPluginConfig: createDefaultPluginConfigMock
+}))
+
+vi.mock('./PluginPipeline', () => ({
+  PluginPipeline: function MockPluginPipeline(...args: unknown[]) {
+    pluginPipelineCtorMock(...args)
+    return {
+      run: pipelineRunMock
+    }
+  }
+}))
+
+afterEach(() => {
+  vi.clearAllMocks()
+  vi.resetModules()
+})
+
+describe('cli runtime lightweight commands', () => {
+  it('does not load plugin config for --version', async () => {
+    const {runCli} = await import('./cli-runtime')
+
+    const exitCode = await runCli(['node', 'tnmsc', '--version'])
+
+    expect(exitCode).toBe(0)
+    expect(createDefaultPluginConfigMock).not.toHaveBeenCalled()
+    expect(pluginPipelineCtorMock).not.toHaveBeenCalled()
+    expect(pipelineRunMock).not.toHaveBeenCalled()
+  })
+
+  it('emits JSON for --version --json without loading plugin config', async () => {
+    const {runCli} = await import('./cli-runtime')
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+
+    try {
+      const exitCode = await runCli(['node', 'tnmsc', '--version', '--json'])
+
+      expect(exitCode).toBe(0)
+      expect(createDefaultPluginConfigMock).not.toHaveBeenCalled()
+      expect(pluginPipelineCtorMock).not.toHaveBeenCalled()
+      expect(pipelineRunMock).not.toHaveBeenCalled()
+
+      const payload = JSON.parse(String(writeSpy.mock.calls[0]?.[0])) as {
+        readonly success: boolean
+        readonly message?: string
+      }
+
+      expect(payload.success).toBe(true)
+      expect(payload.message).toBe('Version displayed')
+    }
+    finally {
+      writeSpy.mockRestore()
+    }
+  })
+})

cli/src/cli-runtime.ts

@@ -1,9 +1,15 @@
+import type {Command, CommandContext, CommandResult} from '@/commands/Command'
+import * as path from 'node:path'
 import process from 'node:process'
-import {toJsonCommandResult} from '@/commands/JsonOutputCommand'
+import {JsonOutputCommand, toJsonCommandResult} from '@/commands/JsonOutputCommand'
 import {buildUnhandledExceptionDiagnostic} from '@/diagnostics'
 import {PluginPipeline} from '@/PluginPipeline'
+import {mergeConfig} from './config'
+import {extractUserArgs, parseArgs, resolveCommand} from './pipeline/CliArgumentParser'
 import {createDefaultPluginConfig} from './plugin.config'
-import {createLogger, drainBufferedDiagnostics} from './plugins/plugin-core'
+import {createLogger, drainBufferedDiagnostics, FilePathKind, setGlobalLogLevel} from './plugins/plugin-core'
+
+const LIGHTWEIGHT_COMMAND_NAMES = new Set(['help', 'version', 'unknown'])
 
 export function isJsonMode(argv: readonly string[]): boolean {
   return argv.some(arg => arg === '--json' || arg === '-j' || /^-[^-]*j/.test(arg))
@@ -21,8 +27,67 @@ function writeJsonFailure(error: unknown): void {
   }, drainBufferedDiagnostics()))}\n`)
 }
 
+function createUnavailableContext(kind: 'cleanup' | 'write'): never {
+  throw new Error(`${kind} context is unavailable for lightweight commands`)
+}
+
+function createLightweightCommandContext(logLevel: ReturnType<typeof parseArgs>['logLevel']): CommandContext {
+  const workspaceDir = process.cwd()
+  const userConfigOptions = mergeConfig({
+    workspaceDir,
+    ...logLevel != null ? {logLevel} : {}
+  })
+
+  return {
+    logger: createLogger('PluginPipeline', logLevel),
+    outputPlugins: [],
+    collectedOutputContext: {
+      workspace: {
+        directory: {
+          pathKind: FilePathKind.Absolute,
+          path: workspaceDir,
+          getDirectoryName: () => path.basename(workspaceDir)
+        },
+        projects: []
+      }
+    },
+    userConfigOptions,
+    createCleanContext: () => createUnavailableContext('cleanup'),
+    createWriteContext: () => createUnavailableContext('write')
+  }
+}
+
+function resolveLightweightCommand(argv: readonly string[]): {
+  readonly command: Command
+  readonly context: CommandContext
+} | undefined {
+  const filteredArgs = argv.filter((arg): arg is string => arg != null)
+  const parsedArgs = parseArgs(extractUserArgs(filteredArgs))
+  let command: Command = resolveCommand(parsedArgs)
+
+  if (!LIGHTWEIGHT_COMMAND_NAMES.has(command.name)) return void 0
+
+  if (parsedArgs.logLevel != null) setGlobalLogLevel(parsedArgs.logLevel)
+
+  if (parsedArgs.jsonFlag) {
+    setGlobalLogLevel('silent')
+    command = new JsonOutputCommand(command)
+  }
+
+  return {
+    command,
+    context: createLightweightCommandContext(parsedArgs.logLevel)
+  }
+}
+
 export async function runCli(argv: readonly string[] = process.argv): Promise<number> {
   try {
+    const lightweightCommand = resolveLightweightCommand(argv)
+    if (lightweightCommand != null) {
+      const result: CommandResult = await lightweightCommand.command.execute(lightweightCommand.context)
+      return result.success ? 0 : 1
+    }
+
     const pipeline = new PluginPipeline(...argv)
     const userPluginConfig = await createDefaultPluginConfig(argv)
     const result = await pipeline.run(userPluginConfig)

cli/src/commands/CleanupUtils.ts

@@ -1,4 +1,4 @@
-import type {ILogger, OutputCleanContext, OutputCleanupDeclarations, OutputCleanupPathDeclaration, OutputPlugin, PluginOptions} from '../plugins/plugin-core'
+import type {ILogger, OutputCleanContext, OutputCleanupDeclarations, OutputCleanupPathDeclaration, OutputFileDeclaration, OutputPlugin, PluginOptions} from '../plugins/plugin-core'
 import type {ProtectedPathRule, ProtectionMode, ProtectionRuleMatcher} from '../ProtectedDeletionGuard'
 import * as fs from 'node:fs'
 import * as path from 'node:path'
@@ -130,14 +130,18 @@ async function collectPluginCleanupDeclarations(
 
 async function collectPluginCleanupSnapshot(
   plugin: OutputPlugin,
-  cleanCtx: OutputCleanContext
+  cleanCtx: OutputCleanContext,
+  predeclaredOutputs?: ReadonlyMap<OutputPlugin, readonly OutputFileDeclaration[]>
 ): Promise<{
   readonly plugin: OutputPlugin
   readonly outputs: Awaited<ReturnType<OutputPlugin['declareOutputFiles']>>
   readonly cleanup: OutputCleanupDeclarations
 }> {
+  const existingOutputDeclarations = predeclaredOutputs?.get(plugin)
   const [outputs, cleanup] = await Promise.all([
-    plugin.declareOutputFiles({...cleanCtx, dryRun: true}),
+    existingOutputDeclarations != null
+      ? Promise.resolve(existingOutputDeclarations)
+      : plugin.declareOutputFiles({...cleanCtx, dryRun: true}),
     collectPluginCleanupDeclarations(plugin, cleanCtx)
   ])
 
@@ -258,7 +262,8 @@ function logCleanupProtectionConflicts(
  */
 export async function collectDeletionTargets(
   outputPlugins: readonly OutputPlugin[],
-  cleanCtx: OutputCleanContext
+  cleanCtx: OutputCleanContext,
+  predeclaredOutputs?: ReadonlyMap<OutputPlugin, readonly OutputFileDeclaration[]>
 ): Promise<{
   filesToDelete: string[]
   dirsToDelete: string[]
@@ -272,7 +277,9 @@ export async function collectDeletionTargets(
   const excludeScanGlobSet = new Set<string>(DEFAULT_CLEANUP_SCAN_EXCLUDE_GLOBS)
   const outputPathOwners = new Map<string, string[]>()
 
-  const pluginSnapshots = await Promise.all(outputPlugins.map(async plugin => collectPluginCleanupSnapshot(plugin, cleanCtx)))
+  const pluginSnapshots = await Promise.all(
+    outputPlugins.map(async plugin => collectPluginCleanupSnapshot(plugin, cleanCtx, predeclaredOutputs))
+  )
 
   const addDeletePath = (rawPath: string, kind: 'file' | 'directory'): void => {
     if (kind === 'directory') deleteDirs.add(resolveAbsolutePath(rawPath))
@@ -491,19 +498,22 @@ function logCleanupPlanDiagnostics(
 export async function performCleanup(
   outputPlugins: readonly OutputPlugin[],
   cleanCtx: OutputCleanContext,
-  logger: ILogger
+  logger: ILogger,
+  predeclaredOutputs?: ReadonlyMap<OutputPlugin, readonly OutputFileDeclaration[]>
 ): Promise<CleanupResult> {
-  const outputs = await collectAllPluginOutputs(outputPlugins, cleanCtx) // Collect outputs for logging
-  logger.debug('Collected outputs for cleanup', {
-    projectDirs: outputs.projectDirs.length,
-    projectFiles: outputs.projectFiles.length,
-    globalDirs: outputs.globalDirs.length,
-    globalFiles: outputs.globalFiles.length
-  })
+  if (predeclaredOutputs != null) {
+    const outputs = await collectAllPluginOutputs(outputPlugins, cleanCtx, predeclaredOutputs)
+    logger.debug('Collected outputs for cleanup', {
+      projectDirs: outputs.projectDirs.length,
+      projectFiles: outputs.projectFiles.length,
+      globalDirs: outputs.globalDirs.length,
+      globalFiles: outputs.globalFiles.length
+    })
+  }
 
   let targets: Awaited<ReturnType<typeof collectDeletionTargets>>
   try {
-    targets = await collectDeletionTargets(outputPlugins, cleanCtx)
+    targets = await collectDeletionTargets(outputPlugins, cleanCtx, predeclaredOutputs)
   }
   catch (error) {
     if (error instanceof CleanupProtectionConflictError) {

cli/src/commands/ExecuteCommand.ts

@@ -1,5 +1,6 @@
 import type {Command, CommandContext, CommandResult} from './Command'
 import {
+  collectOutputDeclarations,
   executeDeclarativeWriteOutputs
 } from '../plugins/plugin-core'
 import {performCleanup} from './CleanupUtils'
@@ -15,8 +16,10 @@ export class ExecuteCommand implements Command {
     const {logger, outputPlugins, createCleanContext, createWriteContext} = ctx
     logger.info('started', {command: 'execute'})
 
+    const writeCtx = createWriteContext(false)
+    const predeclaredOutputs = await collectOutputDeclarations(outputPlugins, writeCtx)
     const cleanCtx = createCleanContext(false) // Step 1: Pre-cleanup (non-dry-run only)
-    const cleanupResult = await performCleanup(outputPlugins, cleanCtx, logger)
+    const cleanupResult = await performCleanup(outputPlugins, cleanCtx, logger, predeclaredOutputs)
 
     if (cleanupResult.violations.length > 0 || cleanupResult.conflicts.length > 0) {
       return {
@@ -29,8 +32,7 @@ export class ExecuteCommand implements Command {
 
     logger.info('cleanup complete', {deletedFiles: cleanupResult.deletedFiles, deletedDirs: cleanupResult.deletedDirs})
 
-    const writeCtx = createWriteContext(false) // Step 2: Write outputs
-    const results = await executeDeclarativeWriteOutputs(outputPlugins, writeCtx)
+    const results = await executeDeclarativeWriteOutputs(outputPlugins, writeCtx, predeclaredOutputs) // Step 2: Write outputs
 
     let totalFiles = 0
     let totalDirs = 0

cli/src/commands/ProtectedDeletionCommands.test.ts

@@ -44,8 +44,10 @@ function createMockOutputPlugin(
   }
 }
 
-function createCommandContext(outputPlugins: readonly OutputPlugin[]): CommandContext {
-  const workspaceDir = path.resolve('tmp-workspace-command')
+function createCommandContext(
+  outputPlugins: readonly OutputPlugin[],
+  workspaceDir: string = path.resolve('tmp-workspace-command')
+): CommandContext {
   const aindexDir = path.join(workspaceDir, 'aindex')
   const collectedOutputContext = {
     workspace: {
@@ -180,6 +182,44 @@ describe('protected deletion commands', () => {
     }))
   })
 
+  it('reuses declared outputs across cleanup and write during execute', async () => {
+    const workspaceDir = path.resolve('tmp-workspace-command-cached')
+    const outputPath = path.join(workspaceDir, 'project-a', 'AGENTS.md')
+    let declareOutputFilesCalls = 0
+    const plugin: OutputPlugin = {
+      type: PluginKind.Output,
+      name: 'CachedOutputPlugin',
+      log: createMockLogger(),
+      declarativeOutput: true,
+      outputCapabilities: {},
+      async declareOutputFiles() {
+        declareOutputFilesCalls += 1
+        return [{path: outputPath, source: {}}]
+      },
+      async declareCleanupPaths() {
+        return {}
+      },
+      async convertContent() {
+        return 'cached-output'
+      }
+    }
+
+    fs.rmSync(workspaceDir, {recursive: true, force: true})
+    fs.mkdirSync(path.join(workspaceDir, 'project-a'), {recursive: true})
+
+    try {
+      const ctx = createCommandContext([plugin], workspaceDir)
+      const result = await new ExecuteCommand().execute(ctx)
+
+      expect(result.success).toBe(true)
+      expect(declareOutputFilesCalls).toBe(1)
+      expect(fs.readFileSync(outputPath, 'utf8')).toBe('cached-output')
+    }
+    finally {
+      fs.rmSync(workspaceDir, {recursive: true, force: true})
+    }
+  })
+
   it('includes structured diagnostics in JSON output errors', async () => {
     const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
     const command = new JsonOutputCommand({

cli/src/inputs/input-agentskills.ts

@@ -628,7 +628,7 @@ async function createSkillPrompt(
   ) // Merge fallback export parsing with compiled metadata so empty metadata objects do not mask valid fields
 
   const authoredNames = new Set<string>()
-  const yamlName = parsed?.yamlFrontMatter?.['name']
+  const yamlName = parsed?.yamlFrontMatter?.name
   if (typeof yamlName === 'string' && yamlName.trim().length > 0) authoredNames.add(yamlName)
   const exportedName = exportMetadata.name
   if (typeof exportedName === 'string' && exportedName.trim().length > 0) authoredNames.add(exportedName)

cli/src/plugins/plugin-core/plugin.ts

@@ -389,20 +389,33 @@ export function validateOutputScopeOverridesForPlugins(
   }
 }
 
+export async function collectOutputDeclarations(
+  plugins: readonly OutputPlugin[],
+  ctx: OutputWriteContext
+): Promise<Map<OutputPlugin, readonly OutputFileDeclaration[]>> {
+  validateOutputScopeOverridesForPlugins(plugins, ctx.pluginOptions)
+
+  const declarationEntries = await Promise.all(
+    plugins.map(async plugin => [plugin, await plugin.declareOutputFiles(ctx)] as const)
+  )
+
+  return new Map(declarationEntries)
+}
+
 /**
  * Execute declarative write operations for output plugins.
  * Core runtime owns file system writes; plugins only declare and convert content.
  */
 export async function executeDeclarativeWriteOutputs(
   plugins: readonly OutputPlugin[],
-  ctx: OutputWriteContext
+  ctx: OutputWriteContext,
+  predeclaredOutputs?: ReadonlyMap<OutputPlugin, readonly OutputFileDeclaration[]>
 ): Promise<Map<string, WriteResults>> {
   const results = new Map<string, WriteResults>()
-
-  validateOutputScopeOverridesForPlugins(plugins, ctx.pluginOptions)
+  const outputDeclarations = predeclaredOutputs ?? await collectOutputDeclarations(plugins, ctx)
 
   for (const plugin of plugins) {
-    const declarations = await plugin.declareOutputFiles(ctx)
+    const declarations = outputDeclarations.get(plugin) ?? []
     const fileResults: WriteResult[] = []
 
     for (const declaration of declarations) {
@@ -464,18 +477,20 @@ export interface CollectedOutputs {
  */
 export async function collectAllPluginOutputs(
   plugins: readonly OutputPlugin[],
-  ctx: OutputPluginContext
+  ctx: OutputPluginContext,
+  predeclaredOutputs?: ReadonlyMap<OutputPlugin, readonly OutputFileDeclaration[]>
 ): Promise<CollectedOutputs> {
   const projectDirs: string[] = []
   const projectFiles: string[] = []
   const globalDirs: string[] = []
   const globalFiles: string[] = []
 
-  validateOutputScopeOverridesForPlugins(plugins, ctx.pluginOptions)
-
-  const declarationGroups = await Promise.all(
-    plugins.map(async plugin => plugin.declareOutputFiles({...ctx, dryRun: true}))
-  )
+  const declarationGroups = predeclaredOutputs != null
+    ? [...predeclaredOutputs.values()]
+    : Array.from(
+        await collectOutputDeclarations(plugins, {...ctx, dryRun: true}),
+        ([, declarations]) => declarations
+      )
 
   for (const declarations of declarationGroups) {
     for (const declaration of declarations) {