@pikku/core 0.12.107 → 0.12.112

package/src/wirings/cli/cli.types.ts

@@ -1,388 +0,0 @@
-import type {
-  CoreSingletonServices,
-  CoreUserSession,
-  CoreServices,
-} from '../../types/core.types.js'
-import type {
-  CorePikkuMiddleware,
-  MiddlewareMetadata,
-} from '../../middleware/middleware.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuPermission,
-  CorePikkuFunction,
-  CorePikkuFunctionSessionless,
-} from '../../function/functions.types.js'
-import type { ChannelRemote, PikkuChannel } from '../channel/channel.types.js'
-
-/**
- * The shape an option's value is parsed into. `'string[]'` splits a single
- * value on commas; `'boolean'` is a flag that consumes the next token only
- * when it is an explicit literal (`true`/`false`/`1`/`0`/`yes`/`no`); every
- * other type consumes one token verbatim, so a value may start with `-`. Left
- * unset — which is the usual case — it is read from the command function's
- * input schema, then from `default`, and otherwise falls back to `'string'`.
- * Declare it only where neither can say: an option belonging to no function
- * input, such as one the config factory reads straight off the CLI data.
- */
-export type CLIOptionType = 'string' | 'number' | 'boolean' | 'string[]'
-
-/**
- * CLI option definition
- */
-export interface CLIOption<T = any> {
-  description: string
-  short?: string
-  type?: CLIOptionType
-  default?: T
-  choices?: T[]
-  required?: boolean
-}
-
-/**
- * CLI options collection
- */
-export type CLIOptions<T> = {
-  [K in keyof T]: CLIOption<T[K]>
-}
-
-/**
- * Positional argument definition
- */
-export interface CLIPositional {
-  name: string
-  required: boolean
-  variadic?: boolean
-}
-
-/**
- * CLI wire context
- */
-export type PikkuCLI<Remote extends (...args: any[]) => any = ChannelRemote> = {
-  program: string
-  command: string[]
-  data: Record<string, any> // All positionals and options merged
-  channel: PikkuChannel<unknown, unknown, Remote>
-}
-
-/**
- * Runtime CLI program state
- */
-export interface CLIProgramState {
-  defaultRenderer?: CorePikkuCLIRender<any>
-  middleware: CorePikkuMiddleware[]
-  renderers: Record<string, CorePikkuCLIRender<any>>
-  commandOptions?: Record<string, Record<string, CLIOption>>
-  commandMiddleware?: Record<string, CorePikkuMiddleware[]>
-  tags?: string[]
-}
-
-/**
- * CLI command metadata for runtime
- */
-export interface CLICommandMeta {
-  parameters?: string
-  pikkuFuncId: string
-  packageName?: string
-  positionals: CLIPositional[]
-  options: Record<string, CLIOption>
-  renderName?: string
-  summary?: string
-  description?: string
-  errors?: string[]
-  tags?: string[]
-  subcommands?: Record<string, CLICommandMeta>
-  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
-  isDefault?: boolean
-}
-
-/**
- * CLI metadata collection (per program)
- */
-export type CLIProgramMeta = {
-  program: string
-  commands: Record<string, CLICommandMeta>
-  options: Record<string, CLIOption>
-  defaultRenderName?: string
-  /**
-   * Whether the channel serving this program over a websocket requires a
-   * session. Only meaningful for the generated channel backend — a locally
-   * executed CLI has no connection to authenticate.
-   */
-  auth?: boolean
-}
-
-/**
- * Renderer metadata for CLI commands
- */
-export interface RendererMeta {
-  name: string
-  exportedName?: string
-  services: {
-    optimized: boolean
-    services: string[]
-  }
-  filePath: string
-}
-
-export type RenderersMeta = Record<string, RendererMeta>
-
-/**
- * All CLI programs metadata
- */
-export interface CLIMeta {
-  programs: Record<string, CLIProgramMeta>
-  renderers: RenderersMeta
-}
-
-/**
- * CLI-specific renderer that outputs to console
- */
-export type CorePikkuCLIRender<
-  Data,
-  Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-> = CorePikkuRender<Data, void, Services, Session>
-
-/**
- * Extract input parameters from a Pikku function config type
- */
-export type ExtractFunctionInput<Func> =
-  Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
-    ? FuncType extends
-        | CorePikkuFunction<infer Input, any, any, any, any>
-        | CorePikkuFunctionSessionless<infer Input, any, any, any, any>
-      ? Input
-      : never
-    : never
-
-/**
- * Strip < > [ ] characters from a string
- */
-type StripBrackets<S extends string> = S extends `<${infer Inner}>`
-  ? Inner
-  : S extends `[${infer Inner}]`
-    ? Inner
-    : S
-
-/**
- * Split string by spaces
- */
-type SplitBySpace<S extends string> = S extends `${infer First} ${infer Rest}`
-  ? [First, ...SplitBySpace<Rest>]
-  : S extends ''
-    ? []
-    : [S]
-
-/**
- * Strip the `...` a variadic positional carries, so `[files...]` validates
- * against the `files` key the runtime parser fills.
- */
-type StripVariadic<S extends string> = S extends `${infer Name}...` ? Name : S
-
-/**
- * Recursively build a tuple by stripping brackets from each element
- */
-type BuildParamsTuple<Parts extends readonly string[]> =
-  Parts extends readonly [
-    infer First extends string,
-    ...infer Rest extends string[],
-  ]
-    ? [StripVariadic<StripBrackets<First>>, ...BuildParamsTuple<Rest>]
-    : []
-
-/**
- * Extract parameter names from CLI parameter string into a tuple
- * Example: "<env> [region]" => ["env", "region"]
- */
-type ExtractParameterNames<S extends string> = BuildParamsTuple<SplitBySpace<S>>
-
-/**
- * Check if all elements of a tuple are valid keys of Input
- */
-type AllParamsValid<
-  Params extends readonly any[],
-  Input,
-> = Params extends readonly [infer First, ...infer Rest]
-  ? First extends keyof Input
-    ? AllParamsValid<Rest, Input>
-    : false
-  : true
-
-/**
- * Validate that all parameter names are valid keys of the function input
- */
-export type ValidateParameters<Params extends string, Input> =
-  AllParamsValid<ExtractParameterNames<Params>, Input> extends true
-    ? Params
-    : never
-
-/**
- * CLI command configuration that infers options from function input type.
- * This is a helper type for creating type-safe CLI commands.
- */
-export type CoreCLICommandConfig<
-  FuncConfig,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
-    any,
-    any
-  >,
-  PikkuCLIRender extends CorePikkuCLIRender<any, any, any> = CorePikkuCLIRender<
-    any,
-    any
-  >,
-  Params extends string = string,
-> = {
-  /**
-   * Positional arguments, written the way `--help` prints them: `<env>` is
-   * required, `[region]` optional. Each name must be a key of the function's
-   * input schema, so a typo is a compile error rather than an argument that
-   * silently never arrives.
-   */
-  parameters?: ValidateParameters<Params, ExtractFunctionInput<FuncConfig>>
-  /** The function to run. Omit it on a command that exists only to hold `subcommands`. */
-  func?: FuncConfig
-  /** The heading shown above this command's own help. */
-  title?: string
-  /** The one-line summary listed beside the command name. */
-  description?: string
-  /**
-   * Prints the result. The function returns data and this is the only thing
-   * that writes to stdout, which is what lets one command serve both a human
-   * reading it and a script parsing it.
-   */
-  render?: PikkuCLIRender
-  /**
-   * Flags, keyed by the input field each one fills. A field with no entry is
-   * still accepted as `--field`; an entry is how it gets a short form, a
-   * default, or help text.
-   */
-  options?: {
-    [K in keyof ExtractFunctionInput<FuncConfig>]?: {
-      /** What this flag is for, as `--help` prints it. */
-      description?: string
-      /** A single-letter alias, so `--verbose` can also be `-v`. */
-      short?: string
-      /** How the argument is parsed. Inferred from the input schema when omitted. */
-      type?: CLIOptionType
-      /** Used when the flag is absent, and shown in `--help` so nobody has to guess it. */
-      default?: ExtractFunctionInput<FuncConfig>[K]
-      /**
-       * The values this option accepts. Rejected by the parser and listed in
-       * `--help`, so a flag with a fixed vocabulary says so once rather than
-       * repeating itself in its description.
-       */
-      choices?: ReadonlyArray<ExtractFunctionInput<FuncConfig>[K]>
-    }
-  }
-  /** Wraps every run of this command. */
-  middleware?: PikkuMiddleware[]
-  /** Nested commands, keyed by the word that selects them: `deploy plan` is `deploy` with a `plan` subcommand. */
-  subcommands?: Record<
-    string,
-    CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender, any>
-  >
-  /** Whether running this requires a logged-in session. Defaults to true — a command is closed unless it says otherwise. */
-  auth?: boolean
-  /** Permission checks run before the function, for a command that not every logged-in user may run. */
-  permissions?: any[]
-  /** Runs when the parent is invoked with no subcommand named. */
-  isDefault?: boolean
-}
-
-/**
- * CLI command definition
- */
-export interface CoreCLICommand<
-  In,
-  Out,
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
-  >,
-  PikkuPermission extends CorePikkuPermission<any, any, any>,
-  PikkuMiddleware extends CorePikkuMiddleware,
-  Options = any,
-  Subcommands extends Record<string, CoreCLICommandConfig<any, any, any>> =
-    Record<string, CoreCLICommandConfig<any, any, any>>,
-> {
-  parameters?: string
-  func: PikkuFunctionConfig
-  render?: CorePikkuCLIRender<Out>
-  description?: string
-  options?: CLIOptions<Options>
-  middleware?: PikkuMiddleware[]
-  permissions?: Record<string, PikkuPermission | PikkuPermission[]>
-  auth?: boolean
-  summary?: string
-  errors?: string[]
-  tags?: string[]
-  subcommands?: Subcommands
-  isDefault?: boolean
-}
-
-/**
- * Shorthand command definition (just a function)
- */
-export type CLICommandShorthand<
-  In,
-  Out,
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
-  >,
-> = PikkuFunctionConfig
-
-/**
- * CLI wiring configuration
- */
-export interface CoreCLI<
-  Commands extends Record<string, CoreCLICommandConfig<any, any, any>>,
-  Options,
-  PikkuMiddleware,
-  PikkuCLIRender,
-> {
-  /** The command name a user types. It is also what `--help` prints as the program. */
-  program: string
-  /** What the program is for, shown at the top of `--help`. */
-  description?: string
-  /** Top-level commands, keyed by the word that selects them. */
-  commands: Commands
-  /** Flags accepted before any command, for things that apply to the whole program. */
-  options?: CLIOptions<Options>
-  /** Wraps every command. */
-  middleware?: PikkuMiddleware[]
-  /** The fallback printer for commands that declare none of their own. */
-  render?: PikkuCLIRender
-  /** A one-line description for listings, where the full `description` is too long. */
-  summary?: string
-  /** Names of error classes any command may throw, so each one's registered exit behaviour is used. */
-  errors?: string[]
-  /** Filters this program in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-  /**
-   * Requires a session on the websocket serving this program remotely. Has no
-   * effect on local execution, where there is no connection to authenticate.
-   */
-  auth?: boolean
-}
-
-/**
- * Generic renderer type that can transform data into any output format.
- * Can be used across different wirings for flexible output handling.
- *
- * @template Data - The input data type to be rendered
- * @template Output - The output type after rendering
- * @template Services - The services available to the renderer
- * @template Session - The user session type
- */
-export type CorePikkuRender<
-  Data,
-  Output,
-  Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-> = (
-  services: Services,
-  data: Data,
-  session?: Session
-) => Output | Promise<Output>