From a11d76264a2643028f16a0d7d2da6c58a7bb499d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Mon, 25 May 2026 09:56:14 +0000 Subject: [PATCH] =?UTF-8?q?chore:=20open-source=20readiness=20=E2=80=94=20?= =?UTF-8?q?LICENSE,=20CONTRIBUTING,=20templates,=20package=20metadata?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add MIT LICENSE - Add CONTRIBUTING.md with setup, conventions, PR workflow - Add GitHub issue/PR templates - Add repository/homepage/bugs/license to all package.json files - Add Install section to README before Quick Start Fixes #510 小橘 🍊（NEKO TeamοΌ‰ --- .github/ISSUE_TEMPLATE/bug_report.md | 31 +++++ .github/ISSUE_TEMPLATE/feature_request.md | 17 +++ .github/pull_request_template.md | 15 +++ CONTRIBUTING.md | 110 ++++++++++++++++++ LICENSE | 21 ++++ README.md | 44 ++++--- package.json | 11 +- packages/cli-workflow/package.json | 12 +- packages/workflow-agent-builtin/package.json | 12 +- .../workflow-agent-claude-code/package.json | 12 +- packages/workflow-agent-hermes/package.json | 12 +- packages/workflow-agent-kit/package.json | 12 +- packages/workflow-moderator/package.json | 12 +- packages/workflow-protocol/package.json | 12 +- packages/workflow-util/package.json | 12 +- 15 files changed, 318 insertions(+), 27 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..ed8a0f5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,31 @@ +--- +name: Bug Report +about: Report a bug or unexpected behavior +labels: bug +--- + +## Describe the bug + +A clear description of what the bug is. + +## To reproduce + +Steps or commands to reproduce: + +```bash +uwf ... +``` + +## Expected behavior + +What you expected to happen. + +## Actual behavior + +What actually happened. Include error messages or logs. + +## Environment + +- OS: +- Bun version: +- uwf version (`uwf --version`): diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..b0f5f26 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,17 @@ +--- +name: Feature Request +about: Suggest a new feature or improvement +labels: enhancement +--- + +## What + +Describe the feature or improvement. + +## Why + +Why is this needed? What problem does it solve? + +## Proposed solution + +How should it work? Include API sketches, CLI examples, or workflow YAML snippets if applicable. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..004907f --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## What + +What this PR does. + +## Why + +Why the change is needed. + +## Changes + +- `path/to/file` β€” what changed and why + +## Ref + +Fixes # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..988e680 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,110 @@ +# Contributing to @uncaged/workflow + +Thank you for your interest in contributing! This guide covers setup, conventions, and the PR workflow. + +## Prerequisites + +- [Bun](https://bun.sh/) (latest) +- [Node.js](https://nodejs.org/) 20+ +- Git + +## Setup + +```bash +git clone https://github.com/shazhou-ww/uncaged-workflow.git +cd uncaged-workflow +bun install +bun run build +bun test +``` + +## Development Workflow + +```bash +bun run build # TypeScript compilation (all packages) +bun run check # tsc + biome lint + log tag validation +bun run format # Auto-format with Biome +bun test # Run all tests +``` + +All three (`build`, `check`, `test`) must pass before submitting a PR. A pre-push hook runs `check` + `test` automatically. + +## Coding Conventions + +See [CLAUDE.md](CLAUDE.md) for the full coding standard. Key points: + +- **Functional-first** β€” `function` + `type`, not `class` + `interface` +- **No optional properties** β€” use `T | null` instead of `?:` +- **Named exports only** β€” no default exports +- **No `console.log`** β€” use the structured logger from `@uncaged/workflow-util` +- **Static imports only** β€” no `await import()` in production code +- **Biome** for lint + format β€” run `bun run check` before committing + +## Commit Messages + +``` +(): + +type: feat | fix | refactor | docs | chore | test +scope: cli | moderator | agent-kit | hermes | builtin | claude-code | util | protocol | dashboard +``` + +Examples: +- `feat(moderator): add cycle detection to graph evaluator` +- `fix(cli): handle missing config file gracefully` +- `docs(protocol): update StepNode field descriptions` + +## Pull Request Process + +1. **Branch** from `main`: `git checkout -b feat/123-short-description` +2. **Implement** your change with tests +3. **Run checks**: `bun run check && bun test` +4. **Commit** with a descriptive message referencing the issue: `Fixes #123` +5. **Push** and open a PR + +### PR Description Template + +``` +## What +What this PR does. + +## Why +Why the change is needed. + +## Changes +- `path/to/file.ts` β€” what changed and why + +## Ref +Fixes #N +``` + +## Adding a Changeset + +For any user-facing change (feat, fix, breaking change), add a changeset: + +```bash +bun changeset +``` + +This creates a markdown file in `.changeset/` describing the change. It will be consumed on the next release to bump versions and generate CHANGELOG entries. + +## Project Structure + +``` +packages/ + workflow-protocol/ # Shared types and JSON Schema + workflow-util/ # Encoding, IDs, logging, frontmatter + workflow-moderator/ # Status-based graph evaluator + workflow-agent-kit/ # createAgent factory, extract pipeline + workflow-agent-hermes/ # Hermes ACP agent + workflow-agent-builtin/ # Built-in LLM agent + workflow-agent-claude-code/ # Claude Code agent + cli-workflow/ # uwf CLI binary + workflow-dashboard/ # Web UI (private, alpha) +``` + +Dependency flows downward β€” lower layers have no dependency on higher layers. See [CLAUDE.md](CLAUDE.md) for the full architecture. + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4fa8e29 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Uncaged + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 033c611..98390b9 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,32 @@ Workflow state lives entirely on disk under `~/.uncaged/workflow/`: CAS nodes fo Agents are pluggable CLI binaries (`uwf-hermes`, `uwf-builtin`, `uwf-claude-code`, or custom commands). The engine spawns the configured agent with `` and ``, sets `UWF_EDGE_PROMPT` from the graph transition, and captures both the agent's markdown output and a detail CAS node for session replay. +## Install + +```bash +npm install -g @uncaged/cli-workflow +``` + +Requires [Bun](https://bun.sh/) runtime (used internally for TypeScript execution). + +## Quick Start + +```bash +# 1. Configure provider, model, and default agent +uwf setup + +# 2. Register a workflow from YAML +uwf workflow add examples/solve-issue.yaml + +# 3. Start a thread (creates head pointer; does not execute) +uwf thread start solve-issue -p "Fix the login redirect bug" + +# 4. Execute steps (one at a time, until done) +uwf thread exec +``` + +Use `-c, --count ` on `thread exec` to run multiple steps in one invocation. Override the agent with `--agent `. + ## Architecture Dependency layers (lower layers have no dependency on higher layers): @@ -60,24 +86,6 @@ See [docs/architecture.md](docs/architecture.md) for the full design β€” three-p | `workflow-agent-claude-code` | `@uncaged/workflow-agent-claude-code` | `uwf-claude-code` β€” spawns Claude Code CLI | agent | [README](packages/workflow-agent-claude-code/README.md) | | `workflow-dashboard` | `@uncaged/workflow-dashboard` | Web graph editor for workflow YAML (private, alpha) | app | [README](packages/workflow-dashboard/README.md) | -## Quick Start - -```bash -# 1. Configure provider, model, and default agent -uwf setup - -# 2. Register a workflow from YAML -uwf workflow add examples/solve-issue.yaml - -# 3. Start a thread (creates head pointer; does not execute) -uwf thread start solve-issue -p "Fix the login redirect bug" - -# 4. Execute steps (one at a time, until done) -uwf thread exec -``` - -Use `-c, --count ` on `thread exec` to run multiple steps in one invocation. Override the agent with `--agent `. - ## CLI Reference Global options: `-V, --version`, `--format `, `-h, --help`. diff --git a/package.json b/package.json index 0be1bde..046fc28 100644 --- a/package.json +++ b/package.json @@ -23,5 +23,14 @@ "@types/xxhashjs": "^0.2.4", "@uncaged/workflow-agent-hermes": "workspace:*", "bun-types": "^1.3.13" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" } diff --git a/packages/cli-workflow/package.json b/packages/cli-workflow/package.json index 073b3c1..f6ae640 100644 --- a/packages/cli-workflow/package.json +++ b/packages/cli-workflow/package.json @@ -29,5 +29,15 @@ }, "devDependencies": { "vitest": "^4.1.6" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git", + "directory": "packages/cli-workflow" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" } diff --git a/packages/workflow-agent-builtin/package.json b/packages/workflow-agent-builtin/package.json index ff7b7e0..c6dd1e8 100644 --- a/packages/workflow-agent-builtin/package.json +++ b/packages/workflow-agent-builtin/package.json @@ -30,5 +30,15 @@ }, "publishConfig": { "access": "public" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git", + "directory": "packages/workflow-agent-builtin" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" } diff --git a/packages/workflow-agent-claude-code/package.json b/packages/workflow-agent-claude-code/package.json index a8917d1..2bed2b0 100644 --- a/packages/workflow-agent-claude-code/package.json +++ b/packages/workflow-agent-claude-code/package.json @@ -30,5 +30,15 @@ }, "publishConfig": { "access": "public" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git", + "directory": "packages/workflow-agent-claude-code" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" } diff --git a/packages/workflow-agent-hermes/package.json b/packages/workflow-agent-hermes/package.json index 3028815..12de6fb 100644 --- a/packages/workflow-agent-hermes/package.json +++ b/packages/workflow-agent-hermes/package.json @@ -31,5 +31,15 @@ }, "publishConfig": { "access": "public" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git", + "directory": "packages/workflow-agent-hermes" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" } diff --git a/packages/workflow-agent-kit/package.json b/packages/workflow-agent-kit/package.json index 355e3ed..8d893a6 100644 --- a/packages/workflow-agent-kit/package.json +++ b/packages/workflow-agent-kit/package.json @@ -30,5 +30,15 @@ }, "publishConfig": { "access": "public" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git", + "directory": "packages/workflow-agent-kit" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" } diff --git a/packages/workflow-moderator/package.json b/packages/workflow-moderator/package.json index 270f5d0..71f785a 100644 --- a/packages/workflow-moderator/package.json +++ b/packages/workflow-moderator/package.json @@ -27,5 +27,15 @@ }, "publishConfig": { "access": "public" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git", + "directory": "packages/workflow-moderator" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" } diff --git a/packages/workflow-protocol/package.json b/packages/workflow-protocol/package.json index 58947e6..0ea5633 100644 --- a/packages/workflow-protocol/package.json +++ b/packages/workflow-protocol/package.json @@ -23,5 +23,15 @@ }, "publishConfig": { "access": "public" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git", + "directory": "packages/workflow-protocol" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" } diff --git a/packages/workflow-util/package.json b/packages/workflow-util/package.json index 5a17e96..d42fae8 100644 --- a/packages/workflow-util/package.json +++ b/packages/workflow-util/package.json @@ -20,5 +20,15 @@ }, "publishConfig": { "access": "public" - } + }, + "repository": { + "type": "git", + "url": "https://github.com/shazhou-ww/uncaged-workflow.git", + "directory": "packages/workflow-util" + }, + "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme", + "bugs": { + "url": "https://github.com/shazhou-ww/uncaged-workflow/issues" + }, + "license": "MIT" }