clack-kit 0.0.1-beta.1

package/README.md

@@ -0,0 +1,161 @@
+# clack-kit
+
+`clack-kit` 是一个面向终端 workflow 的 TypeScript ESM 库
+
+默认就是轻量模式，适合快速搭终端交互流程
+
+需要历史记录、断点恢复、日志落盘时，再按需打开
+
+## 它适合什么场景
+
+- 把一整条终端流程写成可复用的 workflow
+- 把 prompt、条件分支、命令执行放到同一条流程里
+- 在交互步骤和 CLI 参数之间做映射
+- 在需要的时候，再补上历史、checkpoint 和日志
+
+## 默认行为
+
+`clack-kit` 默认不会自动启用下面这三类持久化能力：
+
+- 历史记录
+- 断点恢复
+- 日志保存
+
+也就是说，不做额外配置时，它更像一个专门用来搭终端交互工作流的工具
+
+只有显式开启时，才会写入 `.clack-kit/`
+
+## 安装与开发
+
+```bash
+bun install
+```
+
+常用命令：
+
+```bash
+bun run typecheck
+bun run lint
+CI=1 bun run test
+bun run build
+bun run docs:dev
+bun run docs:build
+```
+
+## 先跑一个最小 workflow
+
+```ts
+import { defineStep, runWorkflowSafely } from 'clack-kit';
+
+const result = await runWorkflowSafely({
+  id: 'hello-workflow',
+  steps: [
+    defineStep.text({
+      id: 'name',
+      message: '名字',
+      required: true,
+    }),
+    defineStep.autocomplete({
+      id: 'framework',
+      message: '框架',
+      options: ['react', 'vue', 'svelte'],
+    }),
+  ],
+});
+
+if (!result) return;
+
+console.log(result.values.name);
+console.log(result.values.framework);
+```
+
+这个例子故意很短
+
+先把交互流程跑通，抓住 `workflow -> steps -> result` 这条主线就够了
+
+## 开启历史、断点和日志
+
+```ts
+import {
+  createWorkflowKit,
+  defineStep,
+  defineSteps,
+  defineWorkflow,
+} from 'clack-kit';
+
+const kit = createWorkflowKit({
+  checkpoints: true,
+  history: true,
+  logs: true,
+});
+
+const workflow = defineWorkflow({
+  id: 'create-project',
+  intro: '创建项目',
+  log: {
+    completion: {
+      initialValue: true,
+      mode: 'confirm',
+      message: '保存这次运行日志吗？',
+    },
+  },
+  steps: defineSteps([
+    defineStep.text({
+      id: 'name',
+      message: '项目名',
+      required: true,
+    }),
+    defineStep.confirm({
+      id: 'install',
+      message: '现在安装依赖吗？',
+    }),
+  ]),
+});
+
+const result = await kit.runSafely(workflow, {
+  checkpoint: {
+    resume: 'ask',
+    save: true,
+  },
+  history: {
+    reuse: 'ask',
+    saveSnapshot: true,
+  },
+});
+
+if (!result) return;
+
+console.log(result.savedLogPath);
+```
+
+这时候库才会开始保存快照、恢复中断流程、落盘运行日志
+
+## 阅读顺序
+
+第一次接触这个库时，建议按这个顺序看：
+
+1. [`docs/getting-started.md`](./docs/getting-started.md)
+2. [`docs/core-concepts.md`](./docs/core-concepts.md)
+3. [`docs/examples.md`](./docs/examples.md)
+4. [`docs/workflows.md`](./docs/workflows.md)
+5. [`docs/commands.md`](./docs/commands.md)
+6. [`docs/cli-integration.md`](./docs/cli-integration.md)
+7. [`docs/persistence.md`](./docs/persistence.md)
+8. [`docs/runtime-context.md`](./docs/runtime-context.md)
+9. [`docs/api-reference.md`](./docs/api-reference.md)
+10. [`docs/troubleshooting.md`](./docs/troubleshooting.md)
+11. [`docs/architecture.md`](./docs/architecture.md)
+
+想先看总览时，可直接从 [`docs/README.md`](./docs/README.md) 开始
+
+## 示例
+
+可直接查看 `examples/`，或者先读 [`examples/README.md`](./examples/README.md)
+
+比较常用的几个示例：
+
+- `examples/create-project.ts`
+- `examples/command-modes.ts`
+- `examples/release-workflow.ts`
+- `examples/deploy-service.ts`
+- `examples/incident-runbook.ts`