@ doist/ cli- core (英语)

DOist CLI项目的共有核心公用事业待办事宜- cli, (中文(简体) ), 扭曲曲线, (中文(简体) ), 大纲- cli, (中文(简体) ), 通讯cli) (中文(简体) ).

TypeScript, 仅限无害环境管理, 第24节, npm 第11节.

安装

npm install @doist/cli-core

里面有什么东西

使用量

全球参数 + 旋转门

import { createGlobalArgsStore, createSpinnerGate, createSpinner } from '@doist/cli-core'

const store = createGlobalArgsStore()
export const isJsonMode = () => store.get().json

const shouldDisableSpinner = createSpinnerGate({
    envVar: 'TD_SPINNER',
    getArgs: store.get,
})
const { withSpinner } = createSpinner({ isDisabled: shouldDisableSpinner })

空状态打印

import { printEmpty } from '@doist/cli-core'

if (tasks.length === 0) {
    printEmpty({ options, message: 'No tasks found.' })
    return
}

读取管状 stdin

readStdin 备份命令 --stdin 旗帜。 当无一物被吹入其中时,它就抛出 STDIN_IS_TTY 而不是等待永不降临的EOF. 它返回未调整的输入,因此命令决定了空输入的含义.

import { CliError, readStdin } from '@doist/cli-core'

if (options.stdin && options.description !== undefined) {
    throw new CliError('CONFLICTING_OPTIONS', 'Cannot use both --description and --stdin')
}
const description = options.stdin ? await readStdin() : options.description

在测试中, mockStdin 从 @doist/cli-core/testing 代表烟斗:

mockStdin('# Notes\n\nBody.\n') // or mockStdin('', { isTTY: true }) for a terminal

测试助手( 子路径)

重用共享的vitest脚手架而不是按 CLI 手卷:

import { attachStatusCommand } from '@doist/cli-core/auth'
import {
    alanGrant,
    buildSingleEntryStore,
    captureConsole,
    createTestProgram,
} from '@doist/cli-core/testing'

it('greets the active account', async () => {
    const logSpy = captureConsole() // silences console.log, auto-restores
    const { store } = buildSingleEntryStore({ token: 'tok', account: alanGrant })
    const program = createTestProgram((p) =>
        attachStatusCommand(p, { store, renderText: (ctx) => `Signed in as ${ctx.account.email}` }),
    )
    await program.parseAsync(['node', 'cli', 'status'])
    expect(logSpy).toHaveBeenCalledWith('Signed in as [email protected]')
})

buildTokenStore 是一个状态的记忆 TokenStore 模拟。 对于一个CLI,它的商店匹配 refs 不同于默认的 id/ email/ label 规则, pass matchAccount 所以模拟解析 恰好 像生产:

import { buildTokenStore } from '@doist/cli-core/testing'
import { matchTwistAccount } from './lib/auth-provider.js'

const { store } = buildTokenStore<TwistAccount>({
    entries: [{ account: ACCOUNT_ALAN, isDefault: true }],
    matchAccount: matchTwistAccount,
})

整个 @doist/cli-core/testing 入口链接 commander (桶再出口) createTestProgram和 vitest 在导入时, 安装两个 消耗性CLI 已有它们 并仅从测试文件导入此子路径 .

Markdown 渲染( 可选子路径)

在消耗的 CLI 中安装对等求解 :

npm install marked marked-terminal-renderer

然后说:

import { preloadMarkdown, renderMarkdown } from '@doist/cli-core/markdown'

if (!options.json && !options.raw) {
    await preloadMarkdown()
}
console.log(await renderMarkdown(comment.body))

如果同位素缺失, preloadMarkdown 向安装命令投掷一个明确的错误。 TypeScript 也会在等同位素被安装之前无法解决子路径的类型.

标准命令( 可选子路径)

在消耗的 CLI 中安装对等点 :

npm install commander

然后电线 <cli> changelog 在一个电话中:

import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { registerChangelogCommand } from '@doist/cli-core/commands'
import packageJson from '../package.json' with { type: 'json' }

registerChangelogCommand(program, {
    path: join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'CHANGELOG.md'),
    repoUrl: 'https://github.com/todoist/todoist-cli',
    version: packageJson.version,
})

帮手扔出 CliError (单位:千美元)INVALID_TYPE 为了一个坏 --count, (中文(简体) ), FILE_READ_ERROR 如果文件无法被读取),所以CLI的顶级错误处理器格式和退出.

线 <cli> update 财务报告和审定财务报表 <cli> update switch 同样:

import { createSpinner, getConfigPath } from '@doist/cli-core'
import { registerUpdateCommand } from '@doist/cli-core/commands'
import packageJson from '../package.json' with { type: 'json' }

const { withSpinner } = createSpinner()
registerUpdateCommand(program, {
    packageName: '@doist/todoist-cli',
    currentVersion: packageJson.version,
    configPath: getConfigPath('todoist-cli'),
    changelogCommandName: 'td changelog',
    brewFormula: 'doist/tap/todoist-cli',
    withSpinner,
})

以自己的针锋相对的形式发布的CLI

registerUpdateCommand(program, {
    packageName: '@doist/automations-cli',
    currentVersion: packageJson.version,
    configPath: getConfigPath('tda'),
    distTag: 'internal',
    withSpinner,
})

update 检查已配置的频道的 npm dist-tag(stable → latest, (中文(简体) ), pre-release → next页:1 currentVersion外壳 npm i -g (或 pnpm add -g 若为 npm_execpath 说明pnpm。 当CLI通过Homebrew安装时(其二进制解为酿酒) Cellar,它运行 brew upgrade <brewFormula> 相反——设定 brewFormula 在酿酒分配的CLIs上(酿酒公式可能落后于npm发布,因此在公式被撞出之前升级可以是一个不开放的. update switch --stable | --pre-release 翻转所坚持的 update_channel 字段通过 updateConfig保存任何兄弟的钥匙 两个子命令都接受 --json 编号 : --ndjson错误为 CliError (单位:千美元)INVALID_FLAGS, (中文(简体) ), UPDATE_CHECK_FAILED, (中文(简体) ), UPDATE_INSTALL_FAILED,或犬类 CONFIG_* 如果配置文件被损坏,则代码).

distTag 替换在自己的标签下发布的 CLI 频道映射( 仅邀请的 CLI on) internal说吧 它从被绑的标签上安装, update switch 财务报告和审定财务报表 --channel 未注册, 配置文件从不读取, 人类输出和机器记录都携带 distTag 否则它们将携带 channel。 。 。 .

两个动作均为 --json 编号 : --ndjson 所以无论消费者在它的"根"程序上声明还是"让" update 拥有它们。 没有其它东西是继承的:一个恰好被命名的根选项 --check 或者说 --channel 没有任何影响 update。 。 。 .

施舍者parseVersion, (中文(简体) ), compareVersions, (中文(简体) ), isNewer, (中文(简体) ), getInstallTag, (中文(简体) ), fetchLatestVersion, (中文(简体) ), getConfiguredUpdateChannel)也导出,用于注册命令以外的临时用途.

扩展( 可选子路径)

给一个CLI gh- 样式扩展系统: <bin> extension list | create | install | upgrade | remove | exec附加时 <bin> <name> … 用于每个已安装的扩展名。 扩展名是一个名为 <bin>-<name> 持有同名可执行文件;主机以 stdio 继承它并用它的退出代码退出它。 在消耗的 CLI 中安装对等求解 :

npm install commander zod

所有特定主机都通过 ExtensionManagerOptions数字 :

import { realpathSync } from 'node:fs'
import { dirname } from 'node:path'
import { getConfigPath, getDataDir, getStateDir } from '@doist/cli-core'
import { createExtensionManager, registerExtensionCommands } from '@doist/cli-core/extensions'
import chalk from 'chalk'
import packageJson from '../package.json' with { type: 'json' }

const APP_NAME = 'todoist-cli'

function buildExtensionManager(program: Command) {
    // Snapshot the built-in names before any extension is registered, so an
    // extension can never be measured as shadowing itself.
    const reserved = new Set([
        ...program.commands.flatMap((command) => [command.name(), ...command.aliases()]),
        'extension',
        'ext',
        'completion-server',
    ])

    return createExtensionManager({
        binName: 'td',
        envPrefix: 'TD',
        version: packageJson.version,
        dataDir: getDataDir(APP_NAME),
        stateDir: getStateDir(APP_NAME),
        configDir: dirname(getConfigPath(APP_NAME)),
        hostPath: realpathSync(process.argv[1] ?? ''),
        reservedNames: () => reserved,
        officialSource: { host: 'github.com', owner: 'todoist' },
        officialLabel: 'Todoist',
        // Kept away from npm lifecycle scripts when an extension's
        // dependencies are installed, on top of GH_TOKEN and GITHUB_TOKEN.
        secretEnvVars: ['TODOIST_API_TOKEN'],
        isAccessible,
        theme: { dim: chalk.dim, bold: chalk.bold, green: chalk.green, yellow: chalk.yellow },
    })
}

registerExtensionCommands(program, buildExtensionManager(program))

registerExtensionCommands 登记 extension 组(别名) ext)和每个安装的扩展下一个通过命令 Extensions: 帮助组。 与内置连接的扩展名报告为: shadowed 内 list 并保持可达到通过 extension exec。 。 。 .

懒惰地装入命令的CLI通常需要将两者分开. registerExtensionGroup 这是 extension 组,只装入 <bin> extension …。 。 。 . registerExtensionPassThrough 盘索夫