refactor(node): share intent runtime helpers

Author: kvz

packages/node/src/cli/commands/assemblies.ts

@@ -1458,8 +1458,14 @@ export async function create(
       })
     }
 
-    if (singleAssembly) {
-      // Single-assembly mode: collect file paths, then create one assembly with all inputs
+    function handleEmitterError(err: Error): void {
+      abortController.abort()
+      queue.clear()
+      outputctl.error(err)
+      reject(err)
+    }
+
+    function runSingleAssemblyEmitter(): void {
       const collectedPaths: string[] = []
 
       emitter.on('job', (job: Job) => {
@@ -1470,13 +1476,6 @@ export async function create(
         }
       })
 
-      emitter.on('error', (err: Error) => {
-        abortController.abort()
-        queue.clear()
-        outputctl.error(err)
-        reject(err)
-      })
-
       emitter.on('end', async () => {
         if (collectedPaths.length === 0) {
           resolve({ results: [], hasFailures: false })
@@ -1533,13 +1532,13 @@ export async function create(
 
         resolve({ results, hasFailures })
       })
-    } else {
-      // Default mode: one assembly per file with p-queue concurrency limiting
+    }
+
+    function runPerFileEmitter(): void {
       emitter.on('job', (job: Job) => {
         const inPath = job.inputPath
         const outputPlan = job.out
         outputctl.debug(`GOT JOB ${inPath ?? 'null'} ${outputPlan?.path ?? 'null'}`)
-        // Add job to queue - p-queue handles concurrency automatically
         queue
           .add(async () => {
             const result = await processAssemblyJob(inPath, outputPlan)
@@ -1553,19 +1552,19 @@ export async function create(
           })
       })
 
-      emitter.on('error', (err: Error) => {
-        abortController.abort()
-        queue.clear()
-        outputctl.error(err)
-        reject(err)
-      })
-
       emitter.on('end', async () => {
-        // Wait for all queued jobs to complete
         await queue.onIdle()
         resolve({ results, hasFailures })
       })
     }
+
+    emitter.on('error', handleEmitterError)
+
+    if (singleAssembly) {
+      runSingleAssemblyEmitter()
+    } else {
+      runPerFileEmitter()
+    }
   })
 }
 

packages/node/src/cli/commands/image-describe.ts

@@ -1,22 +1,11 @@
-import { statSync } from 'node:fs'
 import { Command, Option } from 'clipanion'
+import { z } from 'zod'
 
 import type { InterpolatableRobotAiChatInstructionsWithHiddenFieldsInput } from '../../alphalib/types/robots/ai-chat.ts'
 import type { InterpolatableRobotImageDescribeInstructionsWithHiddenFieldsInput } from '../../alphalib/types/robots/image-describe.ts'
-import {
-  concurrencyOption,
-  countProvidedInputs,
-  deleteAfterProcessingOption,
-  inputPathsOption,
-  recursiveOption,
-  reprocessStaleOption,
-  validateSharedFileProcessingOptions,
-  watchOption,
-} from '../fileProcessingOptions.ts'
-import { prepareIntentInputs } from '../intentRuntime.ts'
-import type { AssembliesCreateOptions } from './assemblies.ts'
+import type { IntentFileCommandDefinition, PreparedIntentInputs } from '../intentRuntime.ts'
+import { GeneratedWatchableFileIntentCommand } from '../intentRuntime.ts'
 import * as assembliesCommands from './assemblies.ts'
-import { AuthenticatedCommand } from './BaseCommand.ts'
 
 const imageDescribeFields = ['labels', 'altText', 'title', 'caption', 'description'] as const
 
@@ -31,15 +20,6 @@ const wordpressDescribeFields = [
 
 const defaultDescribeModel = 'anthropic/claude-sonnet-4-5'
 
-function isHttpUrl(value: string): boolean {
-  try {
-    const url = new URL(value)
-    return url.protocol === 'http:' || url.protocol === 'https:'
-  } catch {
-    return false
-  }
-}
-
 function parseFields(value: string[] | undefined): ImageDescribeField[] {
   const rawFields = (value ?? [])
     .flatMap((part) => part.split(','))
@@ -259,7 +239,27 @@ function buildDescribeStep({
   return buildAiChatStep({ fields, model, profile })
 }
 
-export class ImageDescribeCommand extends AuthenticatedCommand {
+const imageDescribeBaseDefinition = {
+  commandLabel: 'image describe',
+  execution: {
+    kind: 'single-step',
+    fields: [],
+    fixedValues: {},
+    resultStepName: 'describe',
+    schema: z.object({}),
+  },
+  inputPolicy: {
+    kind: 'required',
+  },
+  outputDescription: 'Write the JSON result to this path or directory',
+} satisfies IntentFileCommandDefinition
+
+type ResolvedDescribeRequest = {
+  profile: 'wordpress' | null
+  requestedFields: ImageDescribeField[]
+}
+
+export class ImageDescribeCommand extends GeneratedWatchableFileIntentCommand {
   static override paths = [['image', 'describe']]
 
   static override usage = Command.Usage({
@@ -283,17 +283,6 @@ export class ImageDescribeCommand extends AuthenticatedCommand {
     ],
   })
 
-  outputPath = Option.String('--out,-o', {
-    description: 'Write the JSON result to this path or directory',
-    required: true,
-  })
-
-  inputs = inputPathsOption('Provide an input path, directory, URL, or - for stdin')
-
-  inputBase64 = Option.Array('--input-base64', {
-    description: 'Provide base64-encoded input content directly',
-  })
-
   fields = Option.Array('--fields', {
     description:
       'Describe output fields to generate, for example labels or altText,title,caption,description',
@@ -307,102 +296,65 @@ export class ImageDescribeCommand extends AuthenticatedCommand {
     description: `Model to use for generated text fields (default: ${defaultDescribeModel})`,
   })
 
-  recursive = recursiveOption()
-
-  deleteAfterProcessing = deleteAfterProcessingOption()
-
-  reprocessStale = reprocessStaleOption()
-
-  watch = watchOption()
-
-  concurrency = concurrencyOption()
-
-  private getProvidedInputCount(): number {
-    return countProvidedInputs({
-      inputs: this.inputs,
-      inputBase64: this.inputBase64,
-    })
-  }
-
-  private hasTransientInputSources(): boolean {
-    return (
-      (this.inputs?.some((input) => isHttpUrl(input)) ?? false) ||
-      (this.inputBase64?.length ?? 0) > 0
-    )
+  protected override getIntentDefinition(): IntentFileCommandDefinition {
+    return imageDescribeBaseDefinition
   }
 
-  private isDirectoryOutputTarget(): boolean {
-    try {
-      return statSync(this.outputPath).isDirectory()
-    } catch {
-      return false
+  protected override getIntentRawValues(): Record<string, unknown> {
+    return {
+      fields: this.fields,
+      forProfile: this.forProfile,
+      model: this.model,
     }
   }
 
-  protected override async run(): Promise<number | undefined> {
-    if (this.getProvidedInputCount() === 0) {
-      this.output.error('image describe requires --input or --input-base64')
-      return 1
-    }
-
-    const sharedValidationError = validateSharedFileProcessingOptions({
-      explicitInputCount: this.getProvidedInputCount(),
-      singleAssembly: false,
-      watch: this.watch,
-      watchRequiresInputsMessage: 'image describe --watch requires --input or --input-base64',
-    })
-    if (sharedValidationError != null) {
-      this.output.error(sharedValidationError)
-      return 1
-    }
-
-    if (this.watch && this.hasTransientInputSources()) {
-      this.output.error('--watch is only supported for filesystem inputs')
-      return 1
-    }
-
-    const explicitFields = parseFields(this.fields)
-    const profile = resolveProfile(this.forProfile)
+  private resolveDescribeRequest(rawValues: Record<string, unknown>): ResolvedDescribeRequest {
+    const explicitFields = parseFields(rawValues.fields as string[] | undefined)
+    const profile = resolveProfile(rawValues.forProfile as string | undefined)
     const requestedFields = resolveRequestedFields({ explicitFields, profile })
     validateRequestedFields({
       explicitFields,
       fields: requestedFields,
-      model: this.model,
+      model: rawValues.model as string,
       profile,
     })
 
-    const preparedInputs = await prepareIntentInputs({
-      inputValues: this.inputs ?? [],
-      inputBase64Values: this.inputBase64 ?? [],
-    })
+    return {
+      profile,
+      requestedFields,
+    }
+  }
 
-    try {
-      if (this.watch && preparedInputs.hasTransientInputs) {
-        this.output.error('--watch is only supported for filesystem inputs')
-        return 1
-      }
-
-      const { hasFailures } = await assembliesCommands.create(this.output, this.client, {
-        del: this.deleteAfterProcessing,
-        inputs: preparedInputs.inputs,
-        recursive: this.recursive,
-        reprocessStale: this.reprocessStale,
-        watch: this.watch,
-        concurrency: this.concurrency,
-        output: this.outputPath,
-        outputMode: this.isDirectoryOutputTarget() ? 'directory' : 'file',
-        stepsData: {
-          describe: buildDescribeStep({
-            fields: requestedFields,
-            model: this.model,
-            profile,
-          }),
-        } satisfies AssembliesCreateOptions['stepsData'],
-      })
-
-      return hasFailures ? 1 : undefined
-    } finally {
-      await Promise.all(preparedInputs.cleanup.map((cleanup) => cleanup()))
+  protected override validateBeforePreparingInputs(
+    rawValues: Record<string, unknown>,
+  ): number | undefined {
+    const validationError = super.validateBeforePreparingInputs(rawValues)
+    if (validationError != null) {
+      return validationError
     }
+
+    this.resolveDescribeRequest(rawValues)
+    return undefined
+  }
+
+  protected override async executePreparedInputs(
+    rawValues: Record<string, unknown>,
+    preparedInputs: PreparedIntentInputs,
+  ): Promise<number | undefined> {
+    const { profile, requestedFields } = this.resolveDescribeRequest(rawValues)
+    const { hasFailures } = await assembliesCommands.create(this.output, this.client, {
+      ...this.getCreateOptions(preparedInputs.inputs),
+      output: this.outputPath,
+      outputMode: this.resolveOutputMode(),
+      stepsData: {
+        describe: buildDescribeStep({
+          fields: requestedFields,
+          model: rawValues.model as string,
+          profile,
+        }),
+      },
+    })
+
+    return hasFailures ? 1 : undefined
   }
 }