@julong/mono-rele2-core 1.3.0 → 1.4.0

package/README.md

@@ -0,0 +1,96 @@
+# @julong/mono-rele2-core
+
+Core system utility tools for the mono-rele2 monorepo. Available as an MCP server and a standalone CLI.
+
+## CLI
+
+### Installation
+
+```sh
+npm install -g @julong/mono-rele2-core
+# or
+npx @julong/mono-rele2-core <skillName> [...args]
+```
+
+### Usage
+
+```sh
+mono-rele2-core <skillName> [...args]
+```
+
+Run without arguments to list all available skills:
+
+```sh
+mono-rele2-core
+```
+
+```
+Available skills:
+
+  echoTool
+  Returns the message as-is
+    message  Message to echo
+  ...
+```
+
+### Skills
+
+<!-- SKILLS:START -->
+
+#### `echoTool`
+
+Returns the message as-is.
+
+```sh
+mono-rele2-core echoTool <message>
+```
+
+| arg | type | description |
+|-----|------|-------------|
+| `message` | string | Message to echo |
+
+```sh
+mono-rele2-core echoTool "hello world"    # hello world
+```
+
+#### `timestampTool`
+
+Returns the current UTC timestamp.
+
+```sh
+mono-rele2-core timestampTool [format]
+```
+
+| arg | type | description |
+|-----|------|-------------|
+| `format` | `iso` \| `unix` | Timestamp format (default: `iso`) |
+
+```sh
+mono-rele2-core timestampTool         # 2026-05-02T00:00:00.000Z
+mono-rele2-core timestampTool unix    # 1746144000000
+```
+
+#### `envTool`
+
+Returns the value of an environment variable.
+
+```sh
+mono-rele2-core envTool <key>
+```
+
+| arg | type | description |
+|-----|------|-------------|
+| `key` | string | Environment variable name |
+
+```sh
+mono-rele2-core envTool HOME        # /Users/julong
+mono-rele2-core envTool NODE_ENV    # development
+```
+
+<!-- SKILLS:END -->
+
+## MCP Server
+
+```sh
+mcp-core
+```

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// ../common/mcp/tool.ts
+// ../common/kit/tool.ts
 function toolDef(def) {
   return def;
 }
@@ -11,11 +11,11 @@ function text(content) {
   return { content: [{ type: "text", text: content }] };
 }
 
-// ../common/mcp/server.ts
+// ../common/kit/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// ../common/mcp/cli.ts
+// ../common/kit/cli.ts
 import { z } from "zod";
 function formatSkills(tools2) {
   const sections = Object.entries(tools2).map(([key, tool]) => {
@@ -66,35 +66,48 @@ function handleCliError(err) {
   process.exit(1);
 }
 
-// src/tools/system.ts
+// ../common/kit/skill.ts
 import { z as z2 } from "zod";
+
+// src/tools/system.ts
+import { z as z3 } from "zod";
 var tools = {
   echoTool: toolDef({
     name: "echo",
     description: "Returns the message as-is",
     inputSchema: {
-      message: z2.string().describe("Message to echo")
+      message: z3.string().describe("Message to echo")
     },
-    handler: async ({ message }) => text(message)
+    handler: async ({ message }) => text(message),
+    examples: [{ args: [`"hello world"`], result: "hello world" }]
   }),
   timestampTool: toolDef({
     name: "timestamp",
     description: "Returns the current UTC timestamp",
     inputSchema: {
-      format: z2.enum(["iso", "unix"]).default("iso").describe("Timestamp format")
+      format: z3.enum(["iso", "unix"]).default("iso").describe("Timestamp format")
     },
     handler: async ({ format }) => {
       const value = format === "unix" ? String(Date.now()) : (/* @__PURE__ */ new Date()).toISOString();
       return text(value);
-    }
+    },
+    examples: [
+      { args: [], result: "2026-05-02T00:00:00.000Z" },
+      { args: ["unix"], result: "1746144000000" }
+    ]
   }),
   envTool: toolDef({
     name: "env",
     description: "Returns the value of an environment variable",
     inputSchema: {
-      key: z2.string().describe("Environment variable name")
+      key: z3.string().describe("Environment variable name")
     },
-    handler: async ({ key }) => text(process.env[key] ?? "")
+    handler: async ({ key }) => text(process.env[key] ?? ""),
+    examples: [
+      { args: ["HOME"], result: "/Users/julong" },
+      { args: ["NODE_ENV"], result: "development" }
+    ],
+    guidelines: ["`envTool` returns an empty string when the variable is not set"]
   })
 };
 var echoTool = defineTool(tools.echoTool);

package/dist/index.d.ts

@@ -1,5 +1,74 @@
 import * as _modelcontextprotocol_sdk_server_mcp_js from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+type ToolResult = CallToolResult;
+type ToolExample = {
+    args: string[];
+    result: string;
+};
+type AnyToolDef = {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    handler: (args: any) => Promise<ToolResult>;
+    examples?: ToolExample[];
+    guidelines?: string[];
+};
+
+type SkillTools = Record<string, AnyToolDef>;
+declare function generateSkillMarkdown(opts: {
+    binName: string;
+    description: string;
+    tools: SkillTools;
+}): string;
+declare function generateReadmeSkills(opts: {
+    binName: string;
+    tools: SkillTools;
+}): string;
+
+declare const tools: {
+    echoTool: {
+        name: string;
+        description: string;
+        inputSchema: {
+            readonly message: z.ZodString;
+        };
+        handler: (input: {
+            message: string;
+        }) => Promise<ToolResult>;
+        examples?: ToolExample[];
+        guidelines?: string[];
+    };
+    timestampTool: {
+        name: string;
+        description: string;
+        inputSchema: {
+            readonly format: z.ZodDefault<z.ZodEnum<{
+                iso: "iso";
+                unix: "unix";
+            }>>;
+        };
+        handler: (input: {
+            format: "iso" | "unix";
+        }) => Promise<ToolResult>;
+        examples?: ToolExample[];
+        guidelines?: string[];
+    };
+    envTool: {
+        name: string;
+        description: string;
+        inputSchema: {
+            readonly key: z.ZodString;
+        };
+        handler: (input: {
+            key: string;
+        }) => Promise<ToolResult>;
+        examples?: ToolExample[];
+        guidelines?: string[];
+    };
+};
 
 declare function createCoreServer(): _modelcontextprotocol_sdk_server_mcp_js.McpServer;
 
-export { createCoreServer };
+export { createCoreServer, generateReadmeSkills, generateSkillMarkdown, tools };

package/dist/index.js

@@ -1,4 +1,4 @@
-// ../common/mcp/tool.ts
+// ../common/kit/tool.ts
 function toolDef(def) {
   return def;
 }
@@ -9,7 +9,7 @@ function text(content) {
   return { content: [{ type: "text", text: content }] };
 }
 
-// ../common/mcp/server.ts
+// ../common/kit/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 function createMcpServer(config, tools2) {
@@ -25,38 +25,227 @@ function createMcpServer(config, tools2) {
   return server;
 }
 
-// ../common/mcp/cli.ts
+// ../common/kit/cli.ts
 import { z } from "zod";
 
-// src/tools/system.ts
+// ../common/kit/skill.ts
 import { z as z2 } from "zod";
+function generateSkillMarkdown(opts) {
+  const { binName, description, tools: tools2 } = opts;
+  return `---
+name: ${binName}
+description: ${description}
+---
+
+# ${binName}
+
+\`\`\`sh
+${binName} <skillName> [...args]
+\`\`\`
+
+## Skills
+
+${renderSkills(tools2)}
+
+## Examples
+
+${renderExamples(binName, tools2)}
+
+## Guidelines
+
+${renderGuidelines(binName, tools2)}
+`;
+}
+function renderSkills(tools2) {
+  return Object.entries(tools2).map(([key, tool]) => {
+    const rows = Object.entries(tool.inputSchema).map(([field, schema]) => `| \`${field}\` | ${describeField(schema)} |`).join("\n");
+    return `### ${key}
+
+${tool.description}
+
+| arg | description |
+|-----|-------------|
+${rows}`;
+  }).join("\n\n");
+}
+function describeField(schema) {
+  const baseDesc = schema.description ?? "";
+  let inner = schema;
+  let defaultValue;
+  let isOptional = false;
+  while (inner instanceof z2.ZodOptional || inner instanceof z2.ZodDefault) {
+    if (inner instanceof z2.ZodDefault) {
+      const raw = inner.def.defaultValue;
+      defaultValue = typeof raw === "function" ? raw() : raw;
+    }
+    if (inner instanceof z2.ZodOptional) isOptional = true;
+    inner = inner.unwrap();
+  }
+  const parts = [];
+  if (baseDesc) parts.push(baseDesc);
+  if (inner instanceof z2.ZodEnum) {
+    const values = inner.options.map((v) => `\`${v}\``).join(" \\| ");
+    parts.push(values);
+  }
+  if (defaultValue !== void 0) parts.push(`default: \`${String(defaultValue)}\``);
+  else if (isOptional) parts.push("optional");
+  return parts.join(" \u2014 ");
+}
+function renderExamples(binName, tools2) {
+  const lines = [];
+  for (const [key, tool] of Object.entries(tools2)) {
+    if (!tool.examples) continue;
+    for (const ex of tool.examples) {
+      const cmd = [binName, key, ...ex.args].join(" ");
+      lines.push(`- \`${cmd}\` \u2192 \`${ex.result}\``);
+    }
+  }
+  return lines.join("\n");
+}
+function renderGuidelines(binName, tools2) {
+  const items = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (g) => {
+    if (seen.has(g)) return;
+    seen.add(g);
+    items.push(g);
+  };
+  push("Arguments are positional \u2014 pass them in the order listed in each skill's table");
+  const allSchemas = Object.values(tools2).flatMap((t) => Object.values(t.inputSchema));
+  if (allSchemas.some((s) => containsType(s, z2.ZodNumber))) {
+    push("Numeric args are auto-parsed \u2014 pass as plain numbers (e.g. `10`)");
+  }
+  if (allSchemas.some((s) => containsType(s, z2.ZodArray))) {
+    push('Array args must be valid JSON \u2014 wrap in single quotes on Unix shells (e.g. `\'["a","b"]\'`)');
+  }
+  if (allSchemas.some((s) => s instanceof z2.ZodOptional || s instanceof z2.ZodDefault)) {
+    push("Optional args with defaults may be omitted");
+  }
+  for (const tool of Object.values(tools2)) {
+    if (!tool.guidelines) continue;
+    for (const g of tool.guidelines) push(g);
+  }
+  push(`Run \`${binName}\` with no args to list all available skills`);
+  return items.map((g) => `- ${g}`).join("\n");
+}
+function containsType(schema, ctor) {
+  let inner = schema;
+  while (inner instanceof z2.ZodOptional || inner instanceof z2.ZodDefault) {
+    inner = inner.unwrap();
+  }
+  return inner instanceof ctor;
+}
+function generateReadmeSkills(opts) {
+  const { binName, tools: tools2 } = opts;
+  return Object.entries(tools2).map(([key, tool]) => renderReadmeSkill(binName, key, tool)).join("\n\n");
+}
+function renderReadmeSkill(binName, key, tool) {
+  const fields = Object.entries(tool.inputSchema);
+  const usageArgs = fields.map(([field, schema]) => {
+    const isOpt = schema instanceof z2.ZodOptional || schema instanceof z2.ZodDefault;
+    return isOpt ? `[${field}]` : `<${field}>`;
+  }).join(" ");
+  const usage = [binName, key, usageArgs].filter(Boolean).join(" ");
+  const rows = fields.map(([field, schema]) => {
+    const t = describeReadmeType(schema);
+    const d = describeReadmeDesc(schema);
+    return `| \`${field}\` | ${t} | ${d} |`;
+  }).join("\n");
+  const examples = tool.examples ?? [];
+  let exampleBlock = "";
+  if (examples.length > 0) {
+    const cmds = examples.map((ex) => [binName, key, ...ex.args].join(" "));
+    const width = Math.max(...cmds.map((c) => c.length));
+    const lines = examples.map((ex, i) => `${cmds[i].padEnd(width)}    # ${ex.result}`);
+    exampleBlock = `
+
+\`\`\`sh
+${lines.join("\n")}
+\`\`\``;
+  }
+  return `#### \`${key}\`
+
+${tool.description}.
+
+\`\`\`sh
+${usage}
+\`\`\`
+
+| arg | type | description |
+|-----|------|-------------|
+${rows}${exampleBlock}`;
+}
+function describeReadmeType(schema) {
+  let inner = schema;
+  while (inner instanceof z2.ZodOptional || inner instanceof z2.ZodDefault) {
+    inner = inner.unwrap();
+  }
+  if (inner instanceof z2.ZodEnum) {
+    return inner.options.map((v) => `\`${v}\``).join(" \\| ");
+  }
+  if (inner instanceof z2.ZodNumber) return "number";
+  if (inner instanceof z2.ZodString) return "string";
+  if (inner instanceof z2.ZodBoolean) return "boolean";
+  if (inner instanceof z2.ZodArray) return "JSON string (array)";
+  return "unknown";
+}
+function describeReadmeDesc(schema) {
+  const baseDesc = schema.description ?? "";
+  let inner = schema;
+  let defaultValue;
+  let isOptional = false;
+  while (inner instanceof z2.ZodOptional || inner instanceof z2.ZodDefault) {
+    if (inner instanceof z2.ZodDefault) {
+      const raw = inner.def.defaultValue;
+      defaultValue = typeof raw === "function" ? raw() : raw;
+    }
+    if (inner instanceof z2.ZodOptional) isOptional = true;
+    inner = inner.unwrap();
+  }
+  if (defaultValue !== void 0) return `${baseDesc} (default: \`${String(defaultValue)}\`)`;
+  if (isOptional) return `${baseDesc} (optional)`;
+  return baseDesc;
+}
+
+// src/tools/system.ts
+import { z as z3 } from "zod";
 var tools = {
   echoTool: toolDef({
     name: "echo",
     description: "Returns the message as-is",
     inputSchema: {
-      message: z2.string().describe("Message to echo")
+      message: z3.string().describe("Message to echo")
     },
-    handler: async ({ message }) => text(message)
+    handler: async ({ message }) => text(message),
+    examples: [{ args: [`"hello world"`], result: "hello world" }]
   }),
   timestampTool: toolDef({
     name: "timestamp",
     description: "Returns the current UTC timestamp",
     inputSchema: {
-      format: z2.enum(["iso", "unix"]).default("iso").describe("Timestamp format")
+      format: z3.enum(["iso", "unix"]).default("iso").describe("Timestamp format")
     },
     handler: async ({ format }) => {
       const value = format === "unix" ? String(Date.now()) : (/* @__PURE__ */ new Date()).toISOString();
       return text(value);
-    }
+    },
+    examples: [
+      { args: [], result: "2026-05-02T00:00:00.000Z" },
+      { args: ["unix"], result: "1746144000000" }
+    ]
   }),
   envTool: toolDef({
     name: "env",
     description: "Returns the value of an environment variable",
     inputSchema: {
-      key: z2.string().describe("Environment variable name")
+      key: z3.string().describe("Environment variable name")
     },
-    handler: async ({ key }) => text(process.env[key] ?? "")
+    handler: async ({ key }) => text(process.env[key] ?? ""),
+    examples: [
+      { args: ["HOME"], result: "/Users/julong" },
+      { args: ["NODE_ENV"], result: "development" }
+    ],
+    guidelines: ["`envTool` returns an empty string when the variable is not set"]
   })
 };
 var echoTool = defineTool(tools.echoTool);
@@ -71,5 +260,8 @@ function createCoreServer() {
   );
 }
 export {
-  createCoreServer
+  createCoreServer,
+  generateReadmeSkills,
+  generateSkillMarkdown,
+  tools
 };

package/dist/server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// ../common/mcp/tool.ts
+// ../common/kit/tool.ts
 function toolDef(def) {
   return def;
 }
@@ -11,7 +11,7 @@ function text(content) {
   return { content: [{ type: "text", text: content }] };
 }
 
-// ../common/mcp/server.ts
+// ../common/kit/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 function createMcpServer(config, tools2) {
@@ -31,38 +31,51 @@ async function startServer(server2) {
   await server2.connect(transport);
 }
 
-// ../common/mcp/cli.ts
+// ../common/kit/cli.ts
 import { z } from "zod";
 
-// src/tools/system.ts
+// ../common/kit/skill.ts
 import { z as z2 } from "zod";
+
+// src/tools/system.ts
+import { z as z3 } from "zod";
 var tools = {
   echoTool: toolDef({
     name: "echo",
     description: "Returns the message as-is",
     inputSchema: {
-      message: z2.string().describe("Message to echo")
+      message: z3.string().describe("Message to echo")
     },
-    handler: async ({ message }) => text(message)
+    handler: async ({ message }) => text(message),
+    examples: [{ args: [`"hello world"`], result: "hello world" }]
   }),
   timestampTool: toolDef({
     name: "timestamp",
     description: "Returns the current UTC timestamp",
     inputSchema: {
-      format: z2.enum(["iso", "unix"]).default("iso").describe("Timestamp format")
+      format: z3.enum(["iso", "unix"]).default("iso").describe("Timestamp format")
     },
     handler: async ({ format }) => {
       const value = format === "unix" ? String(Date.now()) : (/* @__PURE__ */ new Date()).toISOString();
       return text(value);
-    }
+    },
+    examples: [
+      { args: [], result: "2026-05-02T00:00:00.000Z" },
+      { args: ["unix"], result: "1746144000000" }
+    ]
   }),
   envTool: toolDef({
     name: "env",
     description: "Returns the value of an environment variable",
     inputSchema: {
-      key: z2.string().describe("Environment variable name")
+      key: z3.string().describe("Environment variable name")
     },
-    handler: async ({ key }) => text(process.env[key] ?? "")
+    handler: async ({ key }) => text(process.env[key] ?? ""),
+    examples: [
+      { args: ["HOME"], result: "/Users/julong" },
+      { args: ["NODE_ENV"], result: "development" }
+    ],
+    guidelines: ["`envTool` returns an empty string when the variable is not set"]
   })
 };
 var echoTool = defineTool(tools.echoTool);

package/dist/{mono-rele2-core → skills/mono-rele2-core}/skill.md

@@ -5,8 +5,6 @@ description: Use this skill to invoke core system utility functions via the mono
 
 # mono-rele2-core
 
-CLI for running core system utility functions from the mono-rele2 package.
-
 ```sh
 mono-rele2-core <skillName> [...args]
 ```
@@ -15,7 +13,7 @@ mono-rele2-core <skillName> [...args]
 
 ### echoTool
 
-Returns the message as-is.
+Returns the message as-is
 
 | arg | description |
 |-----|-------------|
@@ -23,15 +21,15 @@ Returns the message as-is.
 
 ### timestampTool
 
-Returns the current UTC timestamp.
+Returns the current UTC timestamp
 
 | arg | description |
 |-----|-------------|
-| `format` | Output format: `iso` (default) \| `unix` |
+| `format` | Timestamp format — `iso` \| `unix` — default: `iso` |
 
 ### envTool
 
-Returns the value of an environment variable.
+Returns the value of an environment variable
 
 | arg | description |
 |-----|-------------|
@@ -41,7 +39,6 @@ Returns the value of an environment variable.
 
 - `mono-rele2-core echoTool "hello world"` → `hello world`
 - `mono-rele2-core timestampTool` → `2026-05-02T00:00:00.000Z`
-- `mono-rele2-core timestampTool iso` → `2026-05-02T00:00:00.000Z`
 - `mono-rele2-core timestampTool unix` → `1746144000000`
 - `mono-rele2-core envTool HOME` → `/Users/julong`
 - `mono-rele2-core envTool NODE_ENV` → `development`
@@ -49,6 +46,6 @@ Returns the value of an environment variable.
 ## Guidelines
 
 - Arguments are positional — pass them in the order listed in each skill's table
-- `format` in `timestampTool` defaults to `iso` if omitted
+- Optional args with defaults may be omitted
 - `envTool` returns an empty string when the variable is not set
 - Run `mono-rele2-core` with no args to list all available skills

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@julong/mono-rele2-core",
-  "version": "1.3.0",
+  "version": "1.4.0",
+  "description": "Use this skill to invoke core system utility functions via the mono-rele2-core CLI. Handles message echo, UTC timestamp generation, and environment variable lookup.",
   "license": "ISC",
   "type": "module",
   "exports": {
@@ -22,6 +23,11 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "clean": "rimraf dist"
+    "clean": "rimraf dist",
+    "update-readme": "node ../common/build/update-readme.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.2"
   }
 }