@cli-schema/ spec
TypeScript 类型、 供应商的元解析器和验证器 CLI Schema 规格 v1 — 打开标准 以语言不可知、机器可读的方式描述命令行界面.
这是唯一的软件包 cli-schema-js
c. 单体,不依赖CLI框架。 它定义 形状 使用 CLI Schema 文件;
@cli-schema/commander 其实是这样的
产生一个真正的CLI.
快速启动
npm install @cli-schema/spec
import { validate, SCHEMA_VERSION, type CliSchema } from '@cli-schema/spec'
const doc: CliSchema = {
schemaVersion: SCHEMA_VERSION,
name: 'mytool',
version: '1.0.0',
}
const result = validate(doc)
if (!result.valid) throw new Error(JSON.stringify(result.errors, null, 2))
这是最起码的: 文件只需要 schemaVersion, (中文(简体) ), name,以及 version 有效 -- --
其他一切(命令,参数,环境,意图,.)都是可选的浓缩.
目的
CLI 帮助文本为人类编写,完成脚本由每个外壳手写,AI 特工猜测旗子。 CLI Schema 通过定义一个描述一个的 JSON 文档格式来修正它 程序的命令、参数、意图、认证要求、环境依赖和输出 因此,代理、IDE、 shell 补全生成器和文件工具都能够读取 同一文件,而不是重新编号.
@cli-schema/spec 是该格式的编译时间和运行时间合同:您构建的类型
与文档相对的文档,以及您在信任它之前查看的验证符.
特征
- 全面 v1 类型覆盖 ——光谱中的每个对象都有相应的TypeScript接口:
CliSchema(基层),Command, (中文(简体) ),Namespace, (中文(简体) ),Parameter, (中文(简体) ),Constraint, (中文(简体) ),Intent, (中文(简体) ),Output, (中文(简体) ),Environment, (中文(简体) ),EnvVar, (中文(简体) ),ConfigFile, (中文(简体) ),DefaultHandler, (中文(简体) ),Shortcut, (中文(简体) ),Deprecation。 。 。 . - 规范元模型,销售商 —— 说
schema/cli-schema.meta-schema.json从光谱 repo, 于@cli-schema/spec/meta-schema.json用于想要原始 JSON 的工具 直接的Schema(例如在非JS管道中验证,或向编码工具提供). - 即用验证器 —— 说
validate()编号 :assertValid(),由 页:1'"2020-12方言支持. 没必要自找麻烦. inferIntentFromHttp用于 CLI 的小型纯辅助工具, 将 HTTP API 包起来: group a 合理 QQlink intent} 从一个 HTTP 动词(GET编号 :HEAD· 安全并具有能力,PUT→ 有本事的人,DELETE具有破坏性和独能性,POST编号 :PATCH——没有设定,因为他们的语义 )),为特定终点.- 供应商扩展键入 - 每一个允许的物体
x-前缀字段( spec §14) 是 输入以接受它们([extension: \x- ${ string} : 未知), sox-我的工具:{...}type-checks without和任何一个.
使用量
手写文件
作为格式文档的双倍类型——达到 光谱 本身 用于完整字段 语义学,但一个人口众多的文档看起来像:
import type { CliSchema } from '@cli-schema/spec'
const doc: CliSchema = {
schemaVersion: 1,
name: 'gh',
version: '2.45.0',
description: 'GitHub CLI — bring GitHub to your terminal',
requiresAuth: true,
authCommands: ['auth login', 'auth logout'],
reservedMetaCommands: ['__schema'],
commands: [
{
name: 'status',
summary: 'Print information about relevant issues, pull requests, and notifications',
intent: { destructive: false, idempotent: true, requiresAuth: true },
},
],
namespaces: [
{
segment: 'repo',
commands: [
{
name: 'delete',
path: ['repo'],
parameters: [
{ role: 'positional', name: 'repository', type: 'string', required: true },
{ role: 'confirmationSkip', name: 'yes', type: 'boolean', required: false },
],
intent: { destructive: true, idempotent: true, scope: 'global', requiresConfirmation: true },
},
],
},
],
}
在实际操作中,你通常会从一个活的CLI产生这个,而不是用手写出来——看
@cli-schema/commander。 。 。 .
验证未信任的文档
根据第15节,消费者应将计划文件视为不可信的输入:
import { validate, assertValid } from '@cli-schema/spec'
const { valid, errors } = validate(untrustedDoc)
// errors is an ajv ErrorObject[] — empty when valid
assertValid(untrustedDoc) // throws with a formatted message if invalid
读取原始元数据
import metaSchema from '@cli-schema/spec/meta-schema.json' with { type: 'json' }
如果您想要用自己的 ajv 实例验证文档, 则使用不同的验证符 完全,或非JS工具.
HTTP 动词的衍生意图
import { inferIntentFromHttp } from '@cli-schema/spec'
inferIntentFromHttp('DELETE') // { destructive: true, idempotent: true, scope: 'global' }
inferIntentFromHttp('POST') // undefined — annotate explicitly, semantics vary per endpoint
相关软件包
@cli-schema/zod- 从Parameters来自Zod计划@cli-schema/commander- 产生一个完整的CliSchema从活生生的指挥树上
许可证
麻省理工学院