unicommand 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,221 @@
+<a name="TOC"></a>
+
+<div align="center">
+  <div>Unicommand</div>
+  <br />
+  <a href="#-overview">Overview</a> • <a href="#-motivation">Motivation</a> • <a href="#-features">Features</a> • <a href="#-quick-start">Quick Start</a> • <a href="#-usage">Usage</a> • <a href="#-development">Development</a> • <a href="#-license">License</a>
+</div>
+
+<div width="100%" align="center">
+  <img src=".github/image/divider.png" />
+</div>
+
+## 🎺 Overview
+
+Unicommand is a small TypeScript command framework for packages that expose CLIs and MCP servers from the same command definitions.
+
+## ❓ Motivation
+
+I keep building local tools that need the same boring pieces: command metadata, CLI help, completions, update commands, dev shims, MCP tools, package metadata, and generated README command docs.
+
+Why? Repeating that per package makes command behavior drift. Unicommand centralizes the contract so apps only define commands.
+
+## ⭐ Features
+
+- One `defineCommand` contract for CLI and MCP metadata.
+- Package-aware CLI runner using `package.json` bin, version, name, and description.
+- Built-in `completion` and `update` commands.
+- Local dev command shims with active dev-bin detection.
+- README command docs generated from command definitions.
+- MCP command server helpers for tools and resources.
+
+## 🚀 Quick Start
+
+1. Install the package:
+
+   ```sh
+   pnpm add unicommand
+   ```
+
+2. Define a command:
+
+   ```ts
+   import { createCommandAdapters, defineCommand, z } from 'unicommand';
+
+   const metadata = defineCommand({
+     name: 'hello',
+     description: 'Say hello',
+     arguments: [{ synopsis: '<name>', description: 'Name to greet' }],
+     outputSchema: z.string(),
+   });
+
+   export const helloCommand = createCommandAdapters({
+     metadata,
+     handler: ({ name }: { name: string }) => `Hello, ${name}`,
+   });
+   ```
+
+3. Create a CLI runner:
+
+   ```ts
+   #!/usr/bin/env node
+   import { createPackageCommandCliRunner } from 'unicommand';
+
+   const cli = createPackageCommandCliRunner({
+     importMetaUrl: import.meta.url,
+   });
+
+   if (cli.isDirectRun()) {
+     process.exit(await cli.runCli());
+   }
+   ```
+
+## 🧰 Usage
+
+<div align="center">
+
+<details>
+<summary>Show package API</summary>
+<br />
+
+<div align="left">
+
+```ts
+import {
+  createCommandAdapters,
+  createPackageCommandCliRunner,
+  defineCommand,
+  generateReadmeCommandDocs,
+  installPackageDevCommands,
+  startPackageCommandMcpServer,
+  z,
+} from 'unicommand';
+```
+
+Common entry points:
+
+- `defineCommand` describes a command once.
+- `createCommandAdapters` exposes CLI and MCP adapters from one handler.
+- `createPackageCommandCliRunner` builds a package-aware CLI.
+- `startPackageCommandMcpServer` starts an MCP server from command exports.
+- `installPackageDevCommands` installs local dev command shims.
+- `generateReadmeCommandDocs` updates README command blocks.
+
+</div>
+
+</details>
+
+</div>
+
+<div align="center">
+
+<details>
+<summary>Show README command docs</summary>
+<br />
+
+<div align="left">
+
+Add markers to a README:
+
+```md
+<!-- <DYNFIELD:COMMANDS> -->
+<!-- </DYNFIELD:COMMANDS> -->
+```
+
+Then generate docs:
+
+```ts
+import { join } from 'node:path';
+import { generateReadmeCommandDocs } from 'unicommand';
+
+await generateReadmeCommandDocs({
+  binName: 'my-cli',
+  commandsDir: join(process.cwd(), 'src', 'commands'),
+});
+```
+
+</div>
+
+</details>
+
+</div>
+
+<div align="center">
+
+<details>
+<summary>Show local dev shims</summary>
+<br />
+
+<div align="left">
+
+```ts
+import { installPackageDevCommands } from 'unicommand';
+
+installPackageDevCommands(import.meta.url, {
+  commandNames: ['my-clid'],
+});
+```
+
+The generated shim runs `src/cli.ts`, sets the package program-name env var, and lets `update` detect dev mode.
+
+</div>
+
+</details>
+
+</div>
+
+## 🛠 Development
+
+<div align="center">
+
+<details>
+<summary>Show local development setup</summary>
+<br />
+
+<div align="left">
+
+Install dependencies:
+
+```sh
+pnpm install
+```
+
+Run checks:
+
+```sh
+pnpm check:fix
+pnpm typecheck
+pnpm build
+pnpm knip
+```
+
+Create a changeset before publishing changes:
+
+```sh
+pnpm changeset
+```
+
+</div>
+
+</details>
+
+</div>
+
+## 📜 License
+
+[MIT](https://github.com/lucasvtiradentes/unicommand/blob/main/LICENSE)
+
+<div width="100%" align="center">
+  <img src=".github/image/divider.png" />
+</div>
+
+<br />
+
+<div align="center">
+  <div>
+    <a target="_blank" href="https://www.linkedin.com/in/lucasvtiradentes/"><img src="https://img.shields.io/badge/-linkedin-blue?logo=Linkedin&logoColor=white" alt="LinkedIn"></a>
+    <a target="_blank" href="mailto:lucasvtiradentes@gmail.com"><img src="https://img.shields.io/badge/gmail-red?logo=gmail&logoColor=white" alt="Gmail"></a>
+    <a target="_blank" href="https://x.com/lucasvtiradente"><img src="https://img.shields.io/badge/-X-black?logo=X&logoColor=white" alt="X"></a>
+    <a target="_blank" href="https://github.com/lucasvtiradentes"><img src="https://img.shields.io/badge/-github-gray?logo=Github" alt="Github"></a>
+  </div>
+</div>

package/dist/index.d.ts

@@ -7,10 +7,6 @@ type CompletionConfig = {
 };
 declare const registerCompletionCommand: (program: Program, config?: CompletionConfig) => void;
 
-declare const setProgramExamples: (program: Program, examples: string[]) => void;
-declare const isGlobalHelpRequest: (args: readonly string[]) => boolean;
-declare const printProgramHelp: (program: Program) => Promise<void>;
-
 type JsonSchemaProperty = {
     type: 'array' | 'boolean' | 'number' | 'string';
     description?: string;
@@ -99,6 +95,17 @@ declare const commandDefinitionToInputSchema: (definition: CommandDefinition) =>
 };
 declare const commandOptionSynopsis: (option: CommandOptionDefinition) => string;
 
+type ProgramHelpData = {
+    binName: string;
+    commands: readonly CommandDefinition[];
+    description: string;
+    examples: readonly string[];
+    version: string;
+};
+declare const setProgramHelpData: (program: Program, data: ProgramHelpData) => void;
+declare const isGlobalHelpRequest: (args: readonly string[]) => boolean;
+declare const printProgramHelp: (program: Program) => Promise<void>;
+
 type CommandRegistrarContext$1<TContext> = {
     binName: string;
     getContext?: () => Promise<TContext> | TContext;
@@ -606,4 +613,4 @@ type DevCommandShimConfig = {
 declare const installCommandShim: (binDir: string, config: DevCommandShimConfig) => void;
 declare const getBinDir: (envName: string) => string;
 
-export { type CliConfig, type CommandAdapterExport, type CommandAdaptersReturn, type CommandArgumentDefinition, type CommandCompletionDefinition, type CommandDefinition, type CommandExamplesDefinition, type CommandMcpMetadata, type CommandMcpResourceMetadata, type CommandMcpRoute, type CommandMcpRouteFactory, type CommandMcpToolMetadata, type CommandModule, type CommandOptionDefinition, type CommandRegistrar, type CommandRegistrarContext$1 as CommandRegistrarContext, type CommandResourceRoute, type CompletionConfig, type CreateCommandMcpRouterOptions, type CreateCommandMcpServerOptions, type CreateCommandProgramOptions, type CreateMcpServerOptions, type CreatePackageCommandMcpServerOptions, type CreateSingleToolMcpServerOptions, DEFAULT_COMMANDS_DIR, type DefineCommandDefinition, type DevCommandShimConfig, type GenerateReadmeCommandDocsOptions, type JsonRpcRequest, type JsonSchemaProperty, type McpResourceDefinition, type McpResourceTemplateDefinition, type McpResultEnvelope, type McpToolDefinition, PROGRAM_NAME_ENV_SUFFIX, type PackageBinEntry, type PackageCommandMetadata, type PackageJson, PackageManager, type RegisterCliCommandsFromDirectoryOptions, type RegisterParentCommandsFromDefinitionsOptions, type RegisterUpdateCommandOptions, type ResourceReadParams, type ShellCompletionSnippet, type ToolCallParams, assertToolName, commandActionInput, commandDefinitionToInputSchema, commandDefinitionToZodInputSchema, commandDefinitionsFromModules, commandExportsFromModules, commandInputString, commandInputValue, commandMcpRouteToResourceRoute, commandMcpRouteToTool, commandNameToMcpToolName, commandOptionSynopsis, commandResourceInput, commandResourceRouteToResource, commandResourceRouteToResourceTemplate, createCliRunner, createCommandAdapters, createCommandCliRunner, createCommandMcpRoute, createCommandMcpRouter, createCommandMcpServer, createCommandProgram, createMcpServer, createPackageCommandCliRunner, createSingleToolMcpServer, defineCommand, emptyMcpInputSchema, formatCommandDocs, generateReadmeCommandDocs, getBinDir, getPackageManagerFromPath, getProgramBin, getProgramConstructor, installCommandShim, installDevCommand, installPackageDevCommand, installPackageDevCommands, isCommandAdapterExport, isCommandMcpResourceMetadata, isCommandMcpToolMetadata, isDirectRun, isGlobalHelpRequest, isResourceTemplate, loadCommandMcpRoutes, loadCommandModules, loadCommandModulesFromFiles, mcpToolOutputSchema, normalizeCommandInputAliases, packageBinEntry, packageCommandMetadata, packageEnvPrefix, packageRoot, printProgramHelp, readPackageJson, registerCliCommandsFromDirectory, registerCommand, registerCompletionCommand, registerParentCommandsFromDefinitions, registerUpdateCommand, resourceResult, setProgramExamples, shortPackageName, startCommandMcpServer, startPackageCommandMcpServer, throwUnknownTool, uninstallDevCommand, uninstallPackageDevCommand, uninstallPackageDevCommands };
+export { type CliConfig, type CommandAdapterExport, type CommandAdaptersReturn, type CommandArgumentDefinition, type CommandCompletionDefinition, type CommandDefinition, type CommandExamplesDefinition, type CommandMcpMetadata, type CommandMcpResourceMetadata, type CommandMcpRoute, type CommandMcpRouteFactory, type CommandMcpToolMetadata, type CommandModule, type CommandOptionDefinition, type CommandRegistrar, type CommandRegistrarContext$1 as CommandRegistrarContext, type CommandResourceRoute, type CompletionConfig, type CreateCommandMcpRouterOptions, type CreateCommandMcpServerOptions, type CreateCommandProgramOptions, type CreateMcpServerOptions, type CreatePackageCommandMcpServerOptions, type CreateSingleToolMcpServerOptions, DEFAULT_COMMANDS_DIR, type DefineCommandDefinition, type DevCommandShimConfig, type GenerateReadmeCommandDocsOptions, type JsonRpcRequest, type JsonSchemaProperty, type McpResourceDefinition, type McpResourceTemplateDefinition, type McpResultEnvelope, type McpToolDefinition, PROGRAM_NAME_ENV_SUFFIX, type PackageBinEntry, type PackageCommandMetadata, type PackageJson, PackageManager, type RegisterCliCommandsFromDirectoryOptions, type RegisterParentCommandsFromDefinitionsOptions, type RegisterUpdateCommandOptions, type ResourceReadParams, type ShellCompletionSnippet, type ToolCallParams, assertToolName, commandActionInput, commandDefinitionToInputSchema, commandDefinitionToZodInputSchema, commandDefinitionsFromModules, commandExportsFromModules, commandInputString, commandInputValue, commandMcpRouteToResourceRoute, commandMcpRouteToTool, commandNameToMcpToolName, commandOptionSynopsis, commandResourceInput, commandResourceRouteToResource, commandResourceRouteToResourceTemplate, createCliRunner, createCommandAdapters, createCommandCliRunner, createCommandMcpRoute, createCommandMcpRouter, createCommandMcpServer, createCommandProgram, createMcpServer, createPackageCommandCliRunner, createSingleToolMcpServer, defineCommand, emptyMcpInputSchema, formatCommandDocs, generateReadmeCommandDocs, getBinDir, getPackageManagerFromPath, getProgramBin, getProgramConstructor, installCommandShim, installDevCommand, installPackageDevCommand, installPackageDevCommands, isCommandAdapterExport, isCommandMcpResourceMetadata, isCommandMcpToolMetadata, isDirectRun, isGlobalHelpRequest, isResourceTemplate, loadCommandMcpRoutes, loadCommandModules, loadCommandModulesFromFiles, mcpToolOutputSchema, normalizeCommandInputAliases, packageBinEntry, packageCommandMetadata, packageEnvPrefix, packageRoot, printProgramHelp, readPackageJson, registerCliCommandsFromDirectory, registerCommand, registerCompletionCommand, registerParentCommandsFromDefinitions, registerUpdateCommand, resourceResult, setProgramHelpData, shortPackageName, startCommandMcpServer, startPackageCommandMcpServer, throwUnknownTool, uninstallDevCommand, uninstallPackageDevCommand, uninstallPackageDevCommands };