Skip to content

Enhance command handling and testing with new features and refactor #133

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
divyeshio merged 7 commits into from
Apr 16, 2026
Merged

Enhance command handling and testing with new features and refactor #133

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6a3a13c
feat: add exclusionGroups to NestedCommand and update related logic
divyeshio Apr 15, 2026
130f1ec
refactor: update tool properties to use binaryName instead of name
divyeshio Apr 16, 2026
8b9a642
Merge 130f1ec0a09ca21119f6a758ee2071fbd594a53b into a209bf32cdbb5177b…
divyeshio Apr 16, 2026
8986869
chore: update generated specifications and registry
github-actions[bot] Apr 16, 2026
2ace6ab
feat: enhance command tree and tool editor components
divyeshio Apr 16, 2026
e3d70e4
Merge branch 'cleanup' of divyeshio:divyeshio/commandly into cleanup
divyeshio Apr 16, 2026
291720a
fix: remove unnecessary reporter option for GitHub Actions in coverag…
divyeshio Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 11 additions & 12 deletions .agents/skills/commandly-tool-generation/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ Generate and edit CLI tool definitions in the Commandly flat JSON schema format.
### Parsing Help Text

1. Identify the tool name and any description/version info → populate `name`, `displayName`, `info`.
2. Identify commands and subcommands → `commands[]` array with `key`, `name`, optional `parentCommandKey`.
2. Identify commands and subcommands → `commands[]` array with `key`, `name`, optional `parentCommandKey`. If the tool has no subcommands, leave `commands` as an empty array `[]`.
3. Map each flag/option/argument to a parameter → `parameters[]` array.
4. Assign `commandKey` to non-global parameters.
4. If commands exist, assign `commandKey` to non-global parameters. If no commands exist, parameters are **root parameters** — omit both `commandKey` and `isGlobal`.
5. Output pure JSON — no code fences, no comments.
6. Identify options which can take pre-defined values and create `Enum` parameters with `enum.values[]`. Note: "e.g." in help text does not necessarily mean the values are free-form — cross-check with documentation to determine if the full value set is known and fixed before using `Enum`.

Expand All @@ -33,7 +33,7 @@ Generate and edit CLI tool definitions in the Commandly flat JSON schema format.
### Creating from Scratch

1. Use tool name as `name` (lowercase, hyphenated) and a display-friendly `displayName`.
2. Create at minimum one command (use the tool name if there are no subcommands, mark `isDefault: true`).
2. If the tool has subcommands, add them to `commands[]`. If it has no subcommands, use `commands: []`.
3. Map all known parameters following the type rules below.

## Parameter Type Rules
Expand All @@ -53,15 +53,14 @@ Generate and edit CLI tool definitions in the Commandly flat JSON schema format.
## Key Rules

1. Every `key` must be unique across the entire `parameters[]` array. It should be meaningful and derived from the parameter name or description.
2. Non-global parameters **must** have `commandKey`. Global parameters **must not**.
3. `name` should be user-friendly title case (e.g. `--output-file` → `"Output File"`).
4. Descriptions in sentence case, trimmed.
5. Do not add `defaultValue` — it does not exist in the schema.
6. Do not add empty arrays/objects for optional properties (`validations`, `exclusionGroups`, `tags`, `dependencies`, `enum.values` when empty).
7. Tool description/version live under `info: { description, version, url }` — never at top level. `version` is **required** and must reflect the current release (no `v` prefix, e.g. `"1.9.0"` not `"v1.9.0"`). To find the latest version, call `GET https://api.github.com/repos/{owner}/{repo}/releases/latest` and use the `tag_name` field with the leading `v` stripped. For tools with non-standard tag formats (e.g. curl uses `curl-8_19_0`), use the release `name` field instead. For date-based versioning (e.g. yt-dlp uses `2026.03.17`), use `tag_name` as-is.
8. If only one command exists, do not mark all parameters as global.
9. There must always be at least one command. If no subcommand is found, create one with the tool name.
10. Output is pure JSON — no backticks, no trailing commas, proper indentation.
2. When `commands` is non-empty: non-global parameters **must** have `commandKey`, global parameters **must** have `isGlobal: true` and no `commandKey`.
3. When `commands` is empty: parameters are **root parameters** — they must **not** have `commandKey` or `isGlobal`. Do not create a dummy command matching the tool name.
4. `name` should be user-friendly title case (e.g. `--output-file` → `"Output File"`).
5. Descriptions in sentence case, trimmed.
6. Do not add `defaultValue` — it does not exist in the schema.
7. Do not add empty arrays/objects for optional properties (`validations`, `exclusionGroups`, `tags`, `dependencies`, `enum.values` when empty).
8. Tool description/version live under `info: { description, version, url }` — never at top level. `version` is **required** and must reflect the current release (no `v` prefix, e.g. `"1.9.0"` not `"v1.9.0"`). To find the latest version, call `GET https://api.github.com/repos/{owner}/{repo}/releases/latest` and use the `tag_name` field with the leading `v` stripped. For tools with non-standard tag formats (e.g. curl uses `curl-8_19_0`), use the release `name` field instead. For date-based versioning (e.g. yt-dlp uses `2026.03.17`), use `tag_name` as-is.
9. Output is pure JSON — no backticks, no trailing commas, proper indentation.

## Schema Reference

Expand Down
28 changes: 8 additions & 20 deletions .agents/skills/commandly-tool-generation/references/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Commandly Tool JSON Examples

## 1. Simple single-command tool (curl)
## 1. Simple tool with no subcommands (curl)

Demonstrates: single default command, Flag / Option / Argument parameter types, `keyValueSeparator`.
Demonstrates: root parameters (no commands, no `commandKey`), Flag / Option / Argument parameter types, `keyValueSeparator`.

```json
{
Expand All @@ -13,15 +13,7 @@ Demonstrates: single default command, Flag / Option / Argument parameter types,
"description": "curl is a command line tool and library for transferring data with URLs.",
"url": "https://curl.se/"
},
"commands": [
{
"key": "curl",
"name": "curl",
"description": "Run curl to download files.",
"isDefault": true,
"sortOrder": 1
}
],
"commands": [],
"parameters": [
{
"key": "target",
Expand All @@ -31,8 +23,7 @@ Demonstrates: single default command, Flag / Option / Argument parameter types,
"dataType": "String",
"isRequired": true,
"position": 1,
"sortOrder": 5,
"commandKey": "curl"
"sortOrder": 5
},
{
"key": "output",
Expand All @@ -43,8 +34,7 @@ Demonstrates: single default command, Flag / Option / Argument parameter types,
"shortFlag": "-o",
"longFlag": "--output",
"keyValueSeparator": " ",
"sortOrder": 4,
"commandKey": "curl"
"sortOrder": 4
},
{
"key": "location",
Expand All @@ -54,8 +44,7 @@ Demonstrates: single default command, Flag / Option / Argument parameter types,
"dataType": "Boolean",
"shortFlag": "-L",
"longFlag": "--location",
"sortOrder": 1,
"commandKey": "curl"
"sortOrder": 1
},
{
"key": "silent",
Expand All @@ -65,8 +54,7 @@ Demonstrates: single default command, Flag / Option / Argument parameter types,
"dataType": "Boolean",
"shortFlag": "-s",
"longFlag": "--silent",
"sortOrder": 2,
"commandKey": "curl"
"sortOrder": 2
}
]
}
Expand Down Expand Up @@ -104,7 +92,7 @@ Demonstrates: `dataType: "Enum"`, `enum.values[]`, `isRepeatable`.
}
]
},
"commandKey": "nuclei"
"sortOrder": 1
}
```

Expand Down
46 changes: 23 additions & 23 deletions .agents/skills/commandly-tool-generation/references/schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
| `name` | string | ✓ | Lowercase, hyphenated CLI name (e.g. `"curl"`) |
| `displayName` | string | ✓ | Human-friendly title (e.g. `"Curl"`) |
| `info` | ToolInfo | | Description, version, URL |
| `commands` | Command[] | ✓ | At least one required |
| `commands` | Command[] | ✓ | Can be empty for tools with no subcommands |
| `parameters` | Parameter[] | ✓ | Can be empty array |
| `exclusionGroups` | ExclusionGroup[] | | Omit if unused |
| `metadata` | ToolMetadata | | Omit if unused |
Expand All @@ -34,28 +34,28 @@

## Parameter

| Field | Type | Required | Notes |
| ------------------- | --------------------- | -------- | --------------------------------------------------- |
| `key` | string | ✓ | Unique across all parameters |
| `name` | string | ✓ | User-friendly title case |
| `parameterType` | ParameterType | ✓ | `"Flag"` \| `"Option"` \| `"Argument"` |
| `dataType` | ParameterDataType | ✓ | `"Boolean"` \| `"String"` \| `"Number"` \| `"Enum"` |
| `commandKey` | string | | Required if not global; omit if global |
| `description` | string | | Sentence case |
| `group` | string | | Visual grouping label |
| `isRequired` | boolean | | |
| `isRepeatable` | boolean | | True if flag can appear multiple times |
| `isGlobal` | boolean | | True if applies to all commands |
| `shortFlag` | string | | e.g. `"-o"`. Omit if none. |
| `longFlag` | string | | e.g. `"--output"`. Preserve exact prefix. |
| `position` | number | | 1-based; only for `Argument` type |
| `sortOrder` | number | | Display order |
| `arraySeparator` | string | | For array-valued options |
| `keyValueSeparator` | string | | `" "` or `"="` |
| `enum` | ParameterEnumValues | | Required when `dataType` is `"Enum"` |
| `validations` | ParameterValidation[] | | Omit if unused |
| `dependencies` | ParameterDependency[] | | Omit if unused |
| `metadata` | ParameterMetadata | | Contains `tags[]` |
| Field | Type | Required | Notes |
| ------------------- | --------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `key` | string | ✓ | Unique across all parameters |
| `name` | string | ✓ | User-friendly title case |
| `parameterType` | ParameterType | ✓ | `"Flag"` \| `"Option"` \| `"Argument"` |
| `dataType` | ParameterDataType | ✓ | `"Boolean"` \| `"String"` \| `"Number"` \| `"Enum"` |
| `commandKey` | string | | Required when commands exist and not global; omit for root parameters (no commands) and global parameters |
| `description` | string | | Sentence case |
| `group` | string | | Visual grouping label |
| `isRequired` | boolean | | |
| `isRepeatable` | boolean | | True if flag can appear multiple times |
| `isGlobal` | boolean | | True if applies to all commands; must not be set when commands is empty |
| `shortFlag` | string | | e.g. `"-o"`. Omit if none. |
| `longFlag` | string | | e.g. `"--output"`. Preserve exact prefix. |
| `position` | number | | 1-based; only for `Argument` type |
| `sortOrder` | number | | Display order |
| `arraySeparator` | string | | For array-valued options |
| `keyValueSeparator` | string | | `" "` or `"="` |
| `enum` | ParameterEnumValues | | Required when `dataType` is `"Enum"` |
| `validations` | ParameterValidation[] | | Omit if unused |
| `dependencies` | ParameterDependency[] | | Omit if unused |
| `metadata` | ParameterMetadata | | Contains `tags[]` |

## ParameterEnumValues

Expand Down
21 changes: 20 additions & 1 deletion .github/workflows/pr.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,4 +83,23 @@ jobs:
fi

- run: bun run build
- run: bun run test
- run: bun run coverage

- name: Write coverage summary
if: always()
run: |
bun -e "
const s = require('./coverage/coverage-summary.json');
const t = s.total;
const fmt = (m) => \`\${m.pct}% (\${m.covered}/\${m.total})\`;
const lines = [
'## Test Coverage',
'| Metric | Coverage |',
'|--------|----------|',
\`| Statements | \${fmt(t.statements)} |\`,
\`| Branches | \${fmt(t.branches)} |\`,
\`| Functions | \${fmt(t.functions)} |\`,
\`| Lines | \${fmt(t.lines)} |\`,
].join('\n');
require('fs').appendFileSync(process.env.GITHUB_STEP_SUMMARY, lines + '\n');
"
3 changes: 2 additions & 1 deletion components.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
},
"registries": {
"@ai-elements": "https://ai-sdk.dev/elements/api/registry/{name}.json",
"@diceui": "https://diceui.com/r/{name}.json"
"@diceui": "https://diceui.com/r/{name}.json",
"@magicui": "https://magicui.design/r/{name}"
}
}
2 changes: 1 addition & 1 deletion mcp/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ server.registerTool(
const tools = loadToolsFromCollection();

const toolsList = tools.map((tool) => ({
name: tool.name,
binaryName: tool.binaryName,
displayName: tool.displayName,
description: tool.info?.description || "",
metadata: tool.metadata,
Expand Down
Loading
Loading