CLI Contracts Specification

export interface CommandOptions {
  datasetRoot?: string
  customConfigPath?: string
  baseTarget?: string // Target resolution: INIT_CWD (pnpm) > [target] arg > CWD
  useDefaults?: boolean
  minLogLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error'
}
 
export interface CliOptions {
  url?: string // --source <url|path>
  kb: boolean // --no-kb flag (true=download, false=offline)
}

export interface InstallOptions extends CommandOptions, CliOptions {
  listTargets?: boolean
  config?: string
  source?: string
  offline?: boolean // derived from kb: false
}

export interface UpdateOptions extends CommandOptions, CliOptions {
  config?: string
  source?: string
  offline?: boolean
}

export interface UpdateLinkOptions extends CommandOptions {
  url?: string
  dryRun?: boolean
  verbose?: boolean
}

export interface PackageOptions {
  output?: string
  sourceDir?: string
  config?: string
  verbose?: boolean
  name?: string
  version?: string
  description?: string
  author?: string
  skipRegistries?: string[]
  root?: string // default: .pair/
  interactive: boolean // default: false
  tags: string[] // default: []
  license: string // default: MIT
  org?: boolean
  orgName?: string
  team?: string
  department?: string
  approver?: string
  compliance?: string[]
  distribution?: 'open' | 'private' | 'restricted'
}
 
export interface OrganizationMetadata {
  name: string
  team?: string
  department?: string
  approver?: string
  compliance: string[]
  distribution: 'open' | 'private' | 'restricted'
}
 
export interface ManifestMetadata {
  name: string
  version: string
  description: string
  author: string
  tags: string[]
  license: string
  created_at: string
  registries: string[]
  contentChecksum?: string
  organization?: OrganizationMetadata
}

export interface KbVerifyCommandConfig {
  packagePath: string
  json?: boolean
  minLogLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error'
}
 
export interface VerificationReport {
  valid: boolean
  checks: {
    checksum: ChecksumCheck
    structure: StructureCheck
    manifest: ManifestCheck
  }
  size: number
  timestamp: string
}

function validateInstallUpdateOptions(options: InstallOptions | UpdateOptions): void {
  const offline = options.kb === false
 
  if (offline && !options.source) {
    throw new ValidationError('V002', '--offline requires --source with local filesystem path')
  }
 
  if (offline && options.source && isUrl(options.source)) {
    throw new ValidationError('V003', 'Cannot use --offline with remote URL')
  }
 
  if (options.config && !fileExists(options.config)) {
    throw new ValidationError('V004', `Config file not found: ${options.config}`)
  }
}