Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

4.2 KB
Raw Blame
import type { Descriptor, OpFacets } from './describe'
import type { ExitCodeValue } from '@/errors/codes'
import type { CommandContext } from '@/plugins/base'
import type { Example, JsonSchema } from '@/plugins/catalog'
import type { Printable } from '@/sys/io/view'
import { z } from 'zod'
import { validateInput } from '@/call/validate'
import { BaseError, LOC_SEPARATOR } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { inputSchema } from '@/plugins/argv/parse'
import { COMMAND_SEPARATOR } from '@/protocol/op-id'
import { typedName } from '@/util/flag-name'
import { BINARY } from '@/version/info'
import { commandRow } from './describe'

export type { Descriptor, OpFacets } from './describe'

export const COMMAND_EFFECTS = ['read', 'write', 'destructive'] as const
export type CommandEffect = (typeof COMMAND_EFFECTS)[number]

export function isCommandEffect(value: string): value is CommandEffect {
  return (COMMAND_EFFECTS as readonly string[]).includes(value)
}

export const HELP_WORD = 'help'

/** Points at the help for `words`, or at the map when nothing is named. */
export function helpHint(...words: readonly string[]): string {
  return ['run', BINARY, HELP_WORD, ...words].join(COMMAND_SEPARATOR)
}

type InputCheck = Readonly<{
  command: readonly string[]
  schema: JsonSchema
  positional?: readonly string[]
  input: Record<string, unknown>
}>

function typedField(loc: readonly (string | number)[], positional: readonly string[] = []) {
  const [head, ...rest] = loc
  if (typeof head !== 'string') return undefined
  return [typedName(head, positional), ...rest].join(LOC_SEPARATOR)
}

export function assertValidInput(check: InputCheck): void {
  const details = validateInput(check.schema, check.input)
  if (details.length === 0) return
  throw new BaseError({
    code: ErrorCode.InputInvalid,
    message: `invalid input for "${check.command.join(COMMAND_SEPARATOR)}"`,
    hint: helpHint(...check.command),
    details: details.map((detail) => ({
      ...detail,
      field: typedField(detail.loc, check.positional),
    })),
    schema: check.schema,
  })
}

/** Returned by a command that already wrote its output or needs a non-zero exit. */
export class Outcome {
  readonly code: ExitCodeValue
  readonly body?: Printable

  constructor(code: ExitCodeValue, body?: Printable) {
    this.code = code
    this.body = body
  }
}

export type CommandResult = Printable | Outcome | undefined

export type HelpArgs = {
  readonly path: readonly string[]
  readonly rest: readonly string[]
  readonly ctx: CommandContext
}

export abstract class Command<S extends z.ZodObject = z.ZodObject> {
  static summary = ''
  static effect: CommandEffect | undefined = 'read'
  static input: z.ZodObject = z.object({})
  static positional: readonly string[] = []
  static examples: readonly Example[] = []
  static hidden?: boolean

  static schema(this: CommandConstructor): JsonSchema {
    return inputSchema(this.input)
  }

  static flags(this: CommandConstructor): JsonSchema {
    return this.schema()
  }

  static facets(): Partial<OpFacets> {
    return {}
  }

  // The one input gate. parseArgv only coerces what was typed; zod owns the declared
  // defaults, so reaching its parse means a zod rejection is a schema/parser contract bug.
  static finalize(
    this: CommandConstructor,
    input: Record<string, unknown>,
    path: readonly string[],
  ): Record<string, unknown> {
    assertValidInput({ command: path, schema: this.schema(), positional: this.positional, input })
    const parsed = this.input.safeParse(input)
    if (!parsed.success) {
      throw new BaseError({
        code: ErrorCode.Unknown,
        message: parsed.error.issues.map((issue) => issue.message).join('; '),
        cause: parsed.error,
      })
    }
    return parsed.data
  }

  static async help(this: CommandConstructor, args: HelpArgs): Promise<Descriptor> {
    return { ...commandRow(this, args.path), ...this.facets() }
  }

  abstract run(input: z.infer<S>, ctx: CommandContext): Promise<CommandResult>
}

// `Omit` drops the abstract construct signature (and the generic `S` with it), so the
// registry can hold and instantiate any concrete subclass while keeping the statics.
export type CommandConstructor = Omit<typeof Command, 'prototype'> & (new () => Command)