@markus-global/cli 0.2.0

package/templates/skills/markus-hub-connector/server.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+// Self-contained MCP server for Markus Hub operations.
+// Reads hub URL from ~/.markus/markus.json, token from ~/.markus/hub-token.
+// Protocol: JSON-RPC 2.0 over stdio (MCP 2024-11-05).
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline';
+
+const MARKUS_DIR = join(homedir(), '.markus');
+const CONFIG_PATH = join(MARKUS_DIR, 'markus.json');
+const TOKEN_PATH = join(MARKUS_DIR, 'hub-token');
+const ARTIFACTS_DIR = join(MARKUS_DIR, 'builder-artifacts');
+const DEFAULT_HUB_URL = 'https://markus.global';
+
+function getHubUrl() {
+  try {
+    const cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+    return cfg?.hub?.url || DEFAULT_HUB_URL;
+  } catch {
+    return DEFAULT_HUB_URL;
+  }
+}
+
+function getHubToken() {
+  try {
+    return readFileSync(TOKEN_PATH, 'utf-8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function hubFetch(path, opts = {}) {
+  const hubUrl = getHubUrl();
+  const token = getHubToken();
+  const headers = { 'Content-Type': 'application/json', ...opts.headers };
+  if (token) headers['Authorization'] = `Bearer ${token}`;
+  const url = `${hubUrl}/api${path}`;
+  const res = await fetch(url, { ...opts, headers });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Hub API ${res.status}: ${text || res.statusText}`);
+  }
+  return res.json();
+}
+
+// --------------- Tool implementations ---------------
+
+async function hubSearch(args) {
+  const params = new URLSearchParams();
+  if (args.query) params.set('q', args.query);
+  if (args.type) params.set('type', args.type);
+  if (args.category) params.set('category', args.category);
+  if (args.sort) params.set('sort', args.sort);
+  if (args.page) params.set('page', String(args.page));
+  if (args.limit) params.set('limit', String(args.limit || 20));
+  const qs = params.toString();
+  const data = await hubFetch(`/items${qs ? `?${qs}` : ''}`);
+  const items = (data.items || []).map(i => ({
+    id: i.id, name: i.name, type: i.itemType,
+    description: i.description, author: i.author?.username,
+    downloads: i.downloadCount, version: i.version,
+  }));
+  return JSON.stringify({ total: data.total, items }, null, 2);
+}
+
+async function hubDownload(args) {
+  const token = getHubToken();
+  if (!token) return JSON.stringify({ error: 'Not authenticated. User must login to Markus Hub first (via the web UI).' });
+
+  const data = await hubFetch(`/items/${args.id}/download`, { method: 'POST' });
+  const itemType = data.itemType || 'skill';
+  const name = data.name || args.id;
+  const typeDir = `${itemType}s`;
+  const targetDir = join(ARTIFACTS_DIR, typeDir, name);
+  mkdirSync(targetDir, { recursive: true });
+
+  if (data.config) {
+    writeFileSync(join(targetDir, `${itemType}.json`), JSON.stringify(data.config, null, 2), 'utf-8');
+  }
+  if (data.files) {
+    for (const [filename, content] of Object.entries(data.files)) {
+      const filePath = join(targetDir, filename);
+      mkdirSync(join(filePath, '..'), { recursive: true });
+      writeFileSync(filePath, content, 'utf-8');
+    }
+  }
+
+  const fileList = [];
+  try {
+    const walk = (dir, prefix = '') => {
+      for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (e.isDirectory()) walk(join(dir, e.name), `${prefix}${e.name}/`);
+        else fileList.push(`${prefix}${e.name}`);
+      }
+    };
+    walk(targetDir);
+  } catch { /* ignore */ }
+
+  return JSON.stringify({
+    downloaded: name,
+    type: itemType,
+    path: targetDir,
+    files: fileList,
+    note: 'Downloaded to builder-artifacts. User can install it from the Builder page.',
+  }, null, 2);
+}
+
+async function hubPublish(args) {
+  const token = getHubToken();
+  if (!token) return JSON.stringify({ error: 'Not authenticated. User must login to Markus Hub first (via the web UI).' });
+
+  let payload;
+  if (args.directory) {
+    payload = buildPayloadFromDir(args.directory);
+    if (payload.error) return JSON.stringify(payload);
+  } else {
+    payload = {
+      itemType: args.type || 'skill',
+      name: args.name,
+      description: args.description,
+      category: args.category,
+      tags: args.tags,
+      config: args.config,
+      files: args.files,
+      readme: args.readme,
+    };
+  }
+
+  const data = await hubFetch('/items', { method: 'POST', body: JSON.stringify(payload) });
+  return JSON.stringify({
+    id: data.id, name: data.name, slug: data.slug,
+    updated: data.updated || false,
+    url: `${getHubUrl()}/packages/${data.slug || data.id}`,
+  }, null, 2);
+}
+
+function buildPayloadFromDir(dir) {
+  const resolved = dir.startsWith('~') ? join(homedir(), dir.slice(1)) : dir;
+  if (!existsSync(resolved)) return { error: `Directory not found: ${resolved}` };
+
+  const manifestNames = ['skill.json', 'agent.json', 'team.json'];
+  let manifestFile = null;
+  let itemType = 'skill';
+  for (const mf of manifestNames) {
+    if (existsSync(join(resolved, mf))) {
+      manifestFile = mf;
+      itemType = mf.replace('.json', '');
+      break;
+    }
+  }
+  if (!manifestFile) return { error: `No manifest (skill.json/agent.json/team.json) found in ${resolved}` };
+
+  let config;
+  try { config = JSON.parse(readFileSync(join(resolved, manifestFile), 'utf-8')); }
+  catch { return { error: `Invalid JSON in ${manifestFile}` }; }
+
+  const files = {};
+  const walk = (d, prefix = '') => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const rel = `${prefix}${e.name}`;
+      if (e.name === manifestFile && !prefix) continue;
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      if (e.isDirectory()) walk(join(d, e.name), `${rel}/`);
+      else {
+        try { files[rel] = readFileSync(join(d, e.name), 'utf-8'); }
+        catch { /* skip binary files */ }
+      }
+    }
+  };
+  walk(resolved);
+
+  let readme;
+  if (files['README.md']) { readme = files['README.md']; delete files['README.md']; }
+
+  return {
+    itemType, name: config.name, description: config.description,
+    category: config.category, tags: config.tags, config, files, readme,
+  };
+}
+
+async function hubMyItems() {
+  const token = getHubToken();
+  if (!token) return JSON.stringify({ error: 'Not authenticated. User must login to Markus Hub first (via the web UI).' });
+
+  const data = await hubFetch('/items/mine');
+  const items = (data.items || []).map(i => ({
+    id: i.id, name: i.name, type: i.itemType,
+    description: i.description, version: i.version,
+    updatedAt: i.updatedAt,
+  }));
+  return JSON.stringify({ count: items.length, items }, null, 2);
+}
+
+// --------------- MCP protocol ---------------
+
+const TOOLS = [
+  {
+    name: 'hub_search',
+    description: 'Search Markus Hub for agents, teams, or skills by keyword, type, or category',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query:    { type: 'string', description: 'Search keyword' },
+        type:     { type: 'string', enum: ['agent', 'team', 'skill'], description: 'Filter by package type' },
+        category: { type: 'string', description: 'Filter by category' },
+        sort:     { type: 'string', enum: ['downloads', 'recent', 'name'], description: 'Sort order' },
+        page:     { type: 'number', description: 'Page number (1-based)' },
+        limit:    { type: 'number', description: 'Results per page (default 20)' },
+      },
+    },
+  },
+  {
+    name: 'hub_download',
+    description: 'Download a package from Markus Hub to local builder-artifacts directory. Requires Hub login.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Hub item ID (from search results)' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'hub_publish',
+    description: 'Publish a local builder artifact to Markus Hub. Requires Hub login. Provide either a directory path or explicit fields.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        directory:   { type: 'string', description: 'Path to artifact directory (reads manifest + files automatically)' },
+        type:        { type: 'string', enum: ['agent', 'team', 'skill'], description: 'Package type (when not using directory)' },
+        name:        { type: 'string', description: 'Package name (when not using directory)' },
+        description: { type: 'string', description: 'Package description (when not using directory)' },
+        category:    { type: 'string' },
+        tags:        { type: 'array', items: { type: 'string' } },
+        config:      { type: 'object', description: 'Manifest JSON (when not using directory)' },
+        files:       { type: 'object', description: 'Map of filename→content (when not using directory)' },
+        readme:      { type: 'string', description: 'README content (when not using directory)' },
+      },
+    },
+  },
+  {
+    name: 'hub_my_items',
+    description: 'List all items the current user has published on Markus Hub. Requires Hub login.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+];
+
+const TOOL_MAP = {
+  hub_search: hubSearch,
+  hub_download: hubDownload,
+  hub_publish: hubPublish,
+  hub_my_items: hubMyItems,
+};
+
+function respond(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+}
+
+function respondError(id, code, message) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n');
+}
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+
+rl.on('line', async (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  let msg;
+  try { msg = JSON.parse(trimmed); } catch { return; }
+
+  const { id, method, params } = msg;
+
+  if (!method) return; // response to something we sent — ignore
+
+  // Notifications (no id) — just acknowledge silently
+  if (id === undefined || id === null) return;
+
+  switch (method) {
+    case 'initialize':
+      respond(id, {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'markus-hub', version: '1.0.0' },
+      });
+      break;
+
+    case 'tools/list':
+      respond(id, { tools: TOOLS });
+      break;
+
+    case 'tools/call': {
+      const toolName = params?.name;
+      const toolArgs = params?.arguments || {};
+      const handler = TOOL_MAP[toolName];
+      if (!handler) {
+        respondError(id, -32601, `Unknown tool: ${toolName}`);
+        break;
+      }
+      try {
+        const text = await handler(toolArgs);
+        respond(id, { content: [{ type: 'text', text }] });
+      } catch (err) {
+        respond(id, { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true });
+      }
+      break;
+    }
+
+    default:
+      respondError(id, -32601, `Method not found: ${method}`);
+  }
+});
+
+// Keep process alive
+process.stdin.resume();

package/templates/skills/markus-hub-connector/skill.json

@@ -0,0 +1,20 @@
+{
+  "type": "skill",
+  "name": "markus-hub-connector",
+  "displayName": "Markus Hub Connector",
+  "version": "1.0.0",
+  "description": "Search, download, and publish agents/teams/skills on Markus Hub community marketplace",
+  "author": "markus",
+  "category": "productivity",
+  "tags": ["hub", "marketplace", "community", "share"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "requiredPermissions": ["network"],
+    "mcpServers": {
+      "markus-hub": {
+        "command": "node",
+        "args": ["${SKILL_DIR}/server.mjs"]
+      }
+    }
+  }
+}

package/templates/skills/markus-project-cli/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: markus-project-cli
+description: Manage projects, tasks, requirements, deliverables, reports, reviews, and approvals via markus CLI.
+---
+
+# Project & Task Management via CLI
+
+Operate projects, tasks, requirements, deliverables, reports, reviews, and approvals through `shell_execute` with `markus` commands. Always use `--json` for parseable output.
+
+## Projects
+
+```bash
+markus project list --json
+markus project get proj_xxx --json
+markus project create --name "Web App v2" --org-id default --description "Next version"
+markus project update proj_xxx --description "Updated scope"
+markus project delete proj_xxx
+```
+
+| Command | Key Options |
+|---------|-------------|
+| `project list` | `--org <id>` |
+| `project get <id>` | |
+| `project create` | `--name` (required) `--org` `--description` `--repositories` `--team-ids` |
+| `project update <id>` | `--name` `--description` `--status` `--repositories` `--team-ids` |
+| `project delete <id>` | |
+
+## Tasks (nested under project)
+
+```bash
+markus project task list --status in_progress --json
+markus project task create --title "Implement login page" --priority high --assignee agt_xxx --project-id proj_xxx
+markus project task run tsk_xxx
+markus project task get tsk_xxx --json
+markus project task approve tsk_xxx
+markus project task accept tsk_xxx
+markus project task revision tsk_xxx --reason "Tests are missing"
+```
+
+### CRUD
+
+| Command | Options |
+|---------|---------|
+| `project task list` | `--status` `--agent-id` `--project-id` `--requirement-id` `--org-id` `--limit` |
+| `project task get <id>` | |
+| `project task create` | `--title` (required) `--description` `--priority` `--assignee` `--reviewer` `--project-id` `--blocked-by` `--type` |
+| `project task update <id>` | `--title` `--description` `--priority` `--status` `--assignee` `--reviewer` `--project-id` `--blocked-by` |
+| `project task dashboard` | `--org-id` |
+| `project task board` | `--org-id` `--project-id` |
+
+### Lifecycle Actions
+
+| Command | Options |
+|---------|---------|
+| `project task approve <id>` | |
+| `project task reject <id>` | |
+| `project task run <id>` | |
+| `project task pause <id>` | |
+| `project task resume <id>` | |
+| `project task retry <id>` | |
+| `project task cancel <id>` | `--cascade` |
+| `project task accept <id>` | |
+| `project task revision <id>` | `--reason` |
+| `project task archive <id>` | |
+
+### Subtasks & Comments
+
+| Command | Options |
+|---------|---------|
+| `project task subtasks <id>` | |
+| `project task subtask-add <id>` | `--title` (required) |
+| `project task comment <id>` | `--content` (required) `--author-id` `--author-name` |
+| `project task logs <id>` | |
+
+### Task State Flow
+
+```
+pending → pending_approval → assigned → in_progress → review → accepted → completed → archived
+```
+
+## Requirements (nested under project)
+
+```bash
+markus project requirement list --project proj_xxx --json
+markus project requirement create --title "User auth" --project proj_xxx --priority high
+markus project requirement approve req_xxx
+markus project requirement reject req_xxx --reason "Out of scope"
+```
+
+| Command | Key Options |
+|---------|-------------|
+| `project requirement list` | `--org` `--status` `--project` `--source` |
+| `project requirement get <id>` | |
+| `project requirement create` | `--title` (required) `--description` `--priority` `--project` `--org` `--tags` |
+| `project requirement update <id>` | `--title` `--description` `--priority` `--tags` |
+| `project requirement approve <id>` | |
+| `project requirement reject <id>` | `--reason` |
+| `project requirement delete <id>` | |
+
+### Requirement State Flow
+
+```
+draft → pending_review → approved → in_progress → completed
+                      → rejected / cancelled
+```
+
+## Deliverables (nested under project)
+
+```bash
+markus project deliverable list --project-id proj_xxx --json
+markus project deliverable create --title "API Design Doc" --type knowledge --project-id proj_xxx
+markus project deliverable update dlv_xxx --status verified
+markus project deliverable delete dlv_xxx
+```
+
+| Command | Key Options |
+|---------|-------------|
+| `project deliverable list` | `--query` `--project` `--agent` `--task` `--type` `--status` `--limit` `--offset` |
+| `project deliverable create` | `--title` (required) `--type` `--summary` `--reference` `--tags` `--task` `--agent` `--project` |
+| `project deliverable update <id>` | `--title` `--summary` `--reference` `--tags` `--status` `--type` |
+| `project deliverable delete <id>` | |
+
+## Reports & Usage (nested under project)
+
+```bash
+markus project report generate --period weekly --scope org
+markus project report usage --json
+```
+
+| Command | Key Options |
+|---------|-------------|
+| `project report generate` | `--period` (required: daily/weekly/monthly) `--scope` `--org` `--project` |
+| `project report list` | `--scope` `--scope-id` `--type` |
+| `project report get <id>` | |
+| `project report usage` | `--org` |
+
+## Code Reviews (nested under project)
+
+```bash
+markus project review run --task-id tsk_xxx --agent-id agt_xxx --description "PR review"
+markus project review list --task-id tsk_xxx --json
+markus project review get rev_xxx --json
+```
+
+| Command | Key Options |
+|---------|-------------|
+| `project review run` | `--task` (required) `--agent` (required) `--description` `--changed-files` |
+| `project review list` | `--task` `--limit` |
+| `project review get <id>` | |
+
+## Approvals (nested under project)
+
+```bash
+markus project approval list --task-id tsk_xxx --json
+markus project approval process apv_xxx --action approve
+```
+
+| Command | Key Options |
+|---------|-------------|
+| `project approval list` | `--task` `--status` |
+| `project approval process <id>` | `--action` (approve/reject) `--reason` |

package/templates/skills/markus-project-cli/skill.json

@@ -0,0 +1,14 @@
+{
+  "type": "skill",
+  "name": "markus-project-cli",
+  "displayName": "Markus Project CLI",
+  "version": "1.0.0",
+  "description": "Manage projects, requirements, deliverables, reports, and code reviews via markus CLI.",
+  "author": "markus",
+  "category": "platform",
+  "tags": ["cli", "projects", "requirements", "deliverables", "reports"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "alwaysOn": false
+  }
+}

package/templates/skills/markus-skill-cli/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: markus-skill-cli
+description: Manage skills via markus CLI — list, install, uninstall, search, scaffold.
+---
+
+# Skill Management via CLI
+
+Operate the skill registry through `shell_execute` with `markus skill` commands. Always use `--json` for parseable output.
+
+## Quick examples
+
+```bash
+# List installed skills
+markus skill list --json
+
+# List built-in template skills
+markus skill builtin --json
+
+# Search remote registries
+markus skill search --query "browser automation" --json
+
+# Install a skill
+markus skill install --name chrome-devtools --source builtin
+
+# Uninstall a skill
+markus skill uninstall chrome-devtools
+
+# Scaffold a new custom skill
+markus skill init --name my-skill
+```
+
+## Command Reference
+
+| Command | Key Options |
+|---------|-------------|
+| `skill list` | |
+| `skill builtin` | |
+| `skill search` | `--query` |
+| `skill install` | `--name` (required) `--source` |
+| `skill uninstall <name>` | |
+| `skill init` | `--name` `--dir` |
+
+## Skill types
+
+- **Built-in**: Ship with Markus (e.g. `chrome-devtools`, `self-evolution`)
+- **Custom**: User-created, stored locally
+- **Registry**: Discovered via `skill search`, installed from remote sources
+
+## Scaffold structure
+
+`markus skill init --name my-skill` creates:
+
+```
+my-skill/
+  skill.json    # Metadata (name, version, category, tags)
+  SKILL.md      # Instructions for the agent
+```

package/templates/skills/markus-skill-cli/skill.json

@@ -0,0 +1,14 @@
+{
+  "type": "skill",
+  "name": "markus-skill-cli",
+  "displayName": "Markus Skill CLI",
+  "version": "1.0.0",
+  "description": "Manage skills via markus CLI — list, install, uninstall, search, scaffold.",
+  "author": "markus",
+  "category": "platform",
+  "tags": ["cli", "skills", "registry"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "alwaysOn": false
+  }
+}

package/templates/skills/markus-team-cli/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: markus-team-cli
+description: Manage teams via markus CLI — create, members, lifecycle, export.
+---
+
+# Team Management via CLI
+
+Operate teams through `shell_execute` with `markus team` commands. Always use `--json` for parseable output.
+
+## Quick examples
+
+```bash
+# List teams
+markus team list --json
+
+# Create a team
+markus team create --name "Backend Team" --org default
+
+# Add/remove members
+markus team add-member team_xxx --member agt_xxx --type agent
+markus team remove-member team_xxx agt_xxx
+
+# Team lifecycle
+markus team start team_xxx
+markus team stop team_xxx
+markus team pause team_xxx --reason "Maintenance"
+markus team resume team_xxx
+
+# Team status
+markus team status team_xxx --json
+
+# Export team config
+markus team export team_xxx --json
+```
+
+## Command Reference
+
+| Command | Key Options |
+|---------|-------------|
+| `team list` | `--org` |
+| `team get <id>` | |
+| `team create` | `--name` (required) `--org` `--description` |
+| `team update <id>` | `--name` `--description` `--manager-id` `--manager-type` |
+| `team delete <id>` | `--delete-members` `--purge-files` |
+| `team add-member <id>` | `--member` (required) `--type` (agent/human) |
+| `team remove-member <id> <memberId>` | |
+| `team start <id>` | |
+| `team stop <id>` | |
+| `team pause <id>` | `--reason` |
+| `team resume <id>` | |
+| `team status <id>` | |
+| `team export <id>` | |

package/templates/skills/markus-team-cli/skill.json

@@ -0,0 +1,14 @@
+{
+  "type": "skill",
+  "name": "markus-team-cli",
+  "displayName": "Markus Team CLI",
+  "version": "1.0.0",
+  "description": "Manage teams via markus CLI — create, members, lifecycle, export.",
+  "author": "markus",
+  "category": "platform",
+  "tags": ["cli", "teams", "management"],
+  "skill": {
+    "skillFile": "SKILL.md",
+    "alwaysOn": false
+  }
+}