@ldlework/workmark 1.0.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ldlework/workmark",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/lib/load.js",
+  "bin": {
+    "ws": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": "./dist/lib/load.js",
+    "./types": "./dist/lib/types.js",
+    "./helpers": "./dist/lib/helpers.js",
+    "./workspace": "./dist/lib/workspace.js",
+    "./define": "./dist/lib/define.js",
+    "./project": "./dist/lib/project.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "ignore": "^7.0.5",
+    "jiti": "^2.6.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import { loadCommands } from "./lib/load.js";
+import { loadWorkspace } from "./lib/workspace.js";
+import type { ResolvedCommand } from "./lib/types.js";
+
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+function parseValue(raw: string): unknown {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  const n = Number(raw);
+  if (!Number.isNaN(n) && raw !== "") return n;
+  return raw;
+}
+
+function parseArgs(
+  argv: string[],
+  positionalNames: string[],
+): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  let posIdx = 0;
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+
+    if (token.startsWith("--")) {
+      const key = token.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        args[key] = true;
+      } else {
+        args[key] = parseValue(next);
+        i++;
+      }
+    } else if (posIdx < positionalNames.length) {
+      args[positionalNames[posIdx]] = parseValue(token);
+      posIdx++;
+    }
+  }
+
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+
+function printHelp(commands: ResolvedCommand[]): void {
+  console.log("Usage: ws <command> [args...]\n");
+
+  // Group by group name
+  const groups = new Map<string, ResolvedCommand[]>();
+  for (const cmd of commands) {
+    const list = groups.get(cmd.group) ?? [];
+    list.push(cmd);
+    groups.set(cmd.group, list);
+  }
+
+  const maxCmd = Math.max(...commands.map((c) => {
+    const pos = c.positional.map((p) => `<${p}>`).join(" ");
+    return (c.name + " " + pos).trim().length;
+  }));
+
+  // Print ungrouped commands first (top-level)
+  const ungrouped = groups.get("");
+  if (ungrouped) {
+    for (const cmd of ungrouped) {
+      const pos = cmd.positional.map((p) => `<${p}>`).join(" ");
+      const left = (cmd.name + " " + pos).trim();
+      console.log(`  ${left.padEnd(maxCmd + 4)} ${cmd.description}`);
+    }
+    console.log();
+  }
+
+  // Then grouped commands
+  for (const [group, cmds] of groups) {
+    if (group === "") continue;
+    console.log(`  ${group}:`);
+    for (const cmd of cmds) {
+      const pos = cmd.positional.map((p) => `<${p}>`).join(" ");
+      const left = (cmd.name + " " + pos).trim();
+      console.log(`    ${left.padEnd(maxCmd + 4)} ${cmd.description}`);
+    }
+    console.log();
+  }
+}
+
+function printCommandHelp(cmd: ResolvedCommand): void {
+  const pos = cmd.positional.map((p) => `<${p}>`).join(" ");
+  console.log(`Usage: ws ${cmd.name} ${pos}\n`);
+  console.log(cmd.description);
+
+  const schema = cmd.inputSchema as {
+    properties?: Record<string, { type?: string; description?: string; enum?: string[]; default?: unknown }>;
+    required?: string[];
+  };
+  const props = schema.properties;
+  if (!props || Object.keys(props).length === 0) return;
+
+  const positionalSet = new Set(cmd.positional);
+  const required = new Set(schema.required ?? []);
+
+  console.log("\nArguments:");
+  for (const [name, prop] of Object.entries(props)) {
+    const isPositional = positionalSet.has(name);
+    const isReq = required.has(name);
+    const flag = isPositional ? `  ${name}` : `  --${name}`;
+    const parts: string[] = [];
+    if (prop.enum) parts.push(`[${prop.enum.join("|")}]`);
+    if (prop.type) parts.push(`(${prop.type})`);
+    if (prop.default !== undefined) parts.push(`default: ${prop.default}`);
+    if (isReq && !isPositional) parts.push("required");
+    const desc = prop.description ?? "";
+    console.log(`${flag.padEnd(20)} ${desc}${parts.length ? "  " + parts.join(", ") : ""}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const [command, ...rest] = process.argv.slice(2);
+
+  const workspace = await loadWorkspace();
+  const commands = await loadCommands(workspace);
+
+  if (!command || command === "--help" || command === "-h") {
+    printHelp(commands);
+    return;
+  }
+
+  // Build lookup: command name → ResolvedCommand
+  const cmdMap = new Map<string, ResolvedCommand>();
+  for (const cmd of commands) {
+    cmdMap.set(cmd.name, cmd);
+  }
+
+  const cmd = cmdMap.get(command);
+  if (!cmd) {
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run 'ws --help' for available commands.`);
+    process.exit(1);
+  }
+
+  // Per-command help
+  if (rest[0] === "--help" || rest[0] === "-h") {
+    printCommandHelp(cmd);
+    return;
+  }
+
+  const args = parseArgs(rest, cmd.positional);
+  const result = await cmd.handler(args);
+
+  for (const content of result.content) {
+    if (content.type === "text") {
+      const stream = result.isError ? process.stderr : process.stdout;
+      stream.write(content.text + "\n");
+    }
+  }
+
+  if (result.isError) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+import { loadCommands } from "./lib/load.js";
+import { loadWorkspace } from "./lib/workspace.js";
+
+async function main(): Promise<void> {
+  const server = new Server(
+    { name: "workmark", version: "1.0.0" },
+    { capabilities: { tools: {} } },
+  );
+
+  const workspace = await loadWorkspace();
+  const commands = await loadCommands(workspace);
+  const handlers = new Map(commands.map((c) => [c.name, c.handler]));
+
+  console.error(`Loaded ${commands.length} commands from ${workspace.projects.length} projects`);
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: commands.map(({ name, description, inputSchema }) => ({
+      name,
+      description,
+      inputSchema,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const handler = handlers.get(request.params.name);
+    if (!handler) {
+      throw new McpError(
+        ErrorCode.MethodNotFound,
+        `Unknown tool: ${request.params.name}`,
+      );
+    }
+    return handler(request.params.arguments ?? {});
+  });
+
+  server.onerror = (error) => console.error("[MCP Error]", error);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("workmark MCP server running on stdio");
+
+  const cleanup = async () => {
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/src/lib/define.ts

@@ -0,0 +1,6 @@
+import type { ProjectDef } from "./types.js";
+
+/** Define a project. Identity function for type safety. */
+export function defineProject(def: ProjectDef): ProjectDef {
+  return def;
+}

package/src/lib/helpers.ts

@@ -0,0 +1,65 @@
+import { execSync, exec as cpExec } from "node:child_process";
+import { promisify } from "node:util";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+
+// --- Response helpers ---
+
+export function ok(data: unknown): CallToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+export function fail(error: unknown): CallToolResult {
+  let msg: string;
+  if (error instanceof Error) {
+    const { stderr, stdout } = error as unknown as Record<string, unknown>;
+    msg =
+      (typeof stderr === "string" && stderr) ||
+      (typeof stdout === "string" && stdout) ||
+      error.message;
+  } else {
+    msg = String(error);
+  }
+  return { content: [{ type: "text", text: msg }], isError: true };
+}
+
+// --- Shell execution ---
+
+export interface ExecOptions {
+  cwd: string;
+  timeout?: number; // ms, default 120_000
+}
+
+export function exec(command: string, opts: ExecOptions): string {
+  const { cwd, timeout = 120_000 } = opts;
+  return execSync(command, {
+    cwd,
+    timeout,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 1024 * 1024 * 10,
+  });
+}
+
+const execPromise = promisify(cpExec);
+
+export async function execAsync(
+  command: string,
+  opts: ExecOptions,
+): Promise<string> {
+  const { cwd, timeout = 120_000 } = opts;
+  const { stdout } = await execPromise(command, {
+    cwd,
+    timeout,
+    encoding: "utf-8",
+    maxBuffer: 1024 * 1024 * 10,
+  });
+  return stdout;
+}

package/src/lib/jiti-options.ts

@@ -0,0 +1,29 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { JitiOptions } from "jiti";
+
+// Resolve the workmark package root from this file's location (src/lib/ or dist/lib/)
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SRC_LIB = join(PKG_ROOT, "src", "lib");
+
+/**
+ * Build jiti options that let ws.ts / command files import from
+ * `@ldlework/workmark/*` and from workmark's own dependencies (zod, etc.)
+ * regardless of how the package is installed or linked.
+ */
+export function jitiOptions(opts?: Partial<JitiOptions>): JitiOptions {
+  return {
+    interopDefault: true,
+    moduleCache: false,
+    alias: {
+      "@ldlework/workmark/types": join(SRC_LIB, "types.ts"),
+      "@ldlework/workmark/helpers": join(SRC_LIB, "helpers.ts"),
+      "@ldlework/workmark/define": join(SRC_LIB, "define.ts"),
+      "@ldlework/workmark/workspace": join(SRC_LIB, "workspace.ts"),
+      "@ldlework/workmark/project": join(SRC_LIB, "project.ts"),
+      "@ldlework/workmark": join(SRC_LIB, "load.ts"),
+    },
+    nativeModules: ["zod", "@modelcontextprotocol/sdk"],
+    ...opts,
+  };
+}

package/src/lib/load.ts

@@ -0,0 +1,122 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createJiti } from "jiti";
+import { z } from "zod";
+import type { CommandDef, IWorkspace, ResolvedCommand, SchemaFields, StaticCommandDef } from "./types.js";
+import { jitiOptions } from "./jiti-options.js";
+
+/** Title-case a folder name: "docker" → "Docker" */
+function titleCase(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function isStatic(def: CommandDef): def is StaticCommandDef {
+  return "handler" in def;
+}
+
+/** Convert a single field (Zod or raw JSON Schema property) to a JSON Schema property. */
+function fieldToJsonSchema(field: z.ZodType | Record<string, unknown>): Record<string, unknown> {
+  if (field instanceof z.ZodType) {
+    return z.toJSONSchema(field) as Record<string, unknown>;
+  }
+  return field;
+}
+
+/** Merge args + flags into a single JSON Schema object and return positional names. */
+function mergeSchemas(
+  args?: SchemaFields,
+  flags?: SchemaFields,
+): { inputSchema: Record<string, unknown>; positional: string[] } {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  const positional: string[] = [];
+
+  // Args are positional, in key order
+  if (args) {
+    for (const [name, field] of Object.entries(args)) {
+      const schema = fieldToJsonSchema(field);
+      properties[name] = schema;
+      positional.push(name);
+      // If no default and not explicitly optional, it's required
+      if (!("default" in schema)) {
+        required.push(name);
+      }
+    }
+  }
+
+  // Flags are named (--key value)
+  if (flags) {
+    for (const [name, field] of Object.entries(flags)) {
+      const schema = fieldToJsonSchema(field);
+      properties[name] = schema;
+      if (!("default" in schema)) {
+        required.push(name);
+      }
+    }
+  }
+
+  const inputSchema: Record<string, unknown> = {
+    type: "object",
+    properties,
+  };
+  if (required.length > 0) {
+    inputSchema.required = required;
+  }
+
+  return { inputSchema, positional };
+}
+
+function resolve(def: CommandDef, workspace: IWorkspace, group: string, sourceFile: string): ResolvedCommand {
+  let args: SchemaFields | undefined;
+  let flags: SchemaFields | undefined;
+  let handler;
+
+  if (isStatic(def)) {
+    args = def.args;
+    flags = def.flags;
+    handler = def.handler;
+  } else {
+    const result = def.factory(workspace);
+    args = result.args;
+    flags = result.flags;
+    handler = result.handler;
+  }
+
+  const { inputSchema, positional } = mergeSchemas(args, flags);
+  return { name: def.name, label: def.label, group, description: def.description, inputSchema, positional, handler, sourceFile };
+}
+
+export async function loadCommands(workspace: IWorkspace): Promise<ResolvedCommand[]> {
+  const commandsDir = join(workspace.root, ".ws", "commands");
+  if (!existsSync(commandsDir)) return [];
+
+  const jiti = createJiti(commandsDir, jitiOptions());
+  const commands: ResolvedCommand[] = [];
+
+  // Ungrouped (root-level) commands first
+  for (const entry of readdirSync(commandsDir)) {
+    const entryPath = join(commandsDir, entry);
+    const stat = statSync(entryPath);
+    if (!stat.isDirectory() && entry.endsWith(".ts") && !entry.endsWith(".d.ts")) {
+      const mod = await jiti.import(entryPath) as { default: CommandDef };
+      commands.push(resolve(mod.default, workspace, "", entryPath));
+    }
+  }
+
+  // Grouped commands (subdirectories)
+  for (const entry of readdirSync(commandsDir)) {
+    const entryPath = join(commandsDir, entry);
+    const stat = statSync(entryPath);
+    if (stat.isDirectory()) {
+      const group = titleCase(entry);
+      for (const file of readdirSync(entryPath)) {
+        if (!file.endsWith(".ts") || file.endsWith(".d.ts")) continue;
+        const filePath = join(entryPath, file);
+        const mod = await jiti.import(filePath) as { default: CommandDef };
+        commands.push(resolve(mod.default, workspace, group, filePath));
+      }
+    }
+  }
+
+  return commands;
+}

package/src/lib/project.ts

@@ -0,0 +1,39 @@
+import { join } from "node:path";
+import type { IProject, ProjectDef } from "./types.js";
+
+export class Project implements IProject {
+  readonly name: string;
+  readonly dir: string;
+  readonly tags: readonly string[];
+  readonly capabilities: Readonly<Record<string, true | Record<string, unknown>>>;
+
+  private readonly paths: Readonly<Record<string, string>>;
+
+  constructor(def: ProjectDef, wsDir: string) {
+    this.name = def.name;
+    this.dir = def.dir ? join(wsDir, def.dir) : wsDir;
+    this.tags = Object.freeze(def.tags ?? []);
+    this.capabilities = Object.freeze(def.capabilities ?? {});
+    this.paths = Object.freeze(def.paths ?? {});
+  }
+
+  has(capability: string): boolean {
+    return capability in this.capabilities;
+  }
+
+  capability<T = true | Record<string, unknown>>(name: string): T {
+    const cap = this.capabilities[name];
+    if (cap === undefined) {
+      throw new Error(`Project "${this.name}" does not have capability "${name}"`);
+    }
+    return cap as T;
+  }
+
+  path(name: string): string {
+    const rel = this.paths[name];
+    if (rel === undefined) {
+      throw new Error(`Project "${this.name}" does not have path "${name}"`);
+    }
+    return join(this.dir, rel);
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,89 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+
+/** An input schema: either a Zod schema (converted automatically) or raw JSON Schema. */
+export type InputSchema = z.ZodType | Record<string, unknown>;
+
+/** A record of named Zod schemas or raw JSON Schema property objects. */
+export type SchemaFields = Record<string, z.ZodType | Record<string, unknown>>;
+
+// ---- Project definitions (used in ws.ts files) ----
+
+export interface ProjectDef {
+  /** Unique identifier. */
+  name: string;
+  /** Project directory relative to the ws.ts location. Defaults to ".". */
+  dir?: string;
+  /** Arbitrary string tags for grouping/filtering. */
+  tags?: string[];
+  /** Named directories, resolved relative to the project dir. */
+  paths?: Record<string, string>;
+  /** Capabilities this project supports. `true` = use convention, object = custom config. */
+  capabilities?: Record<string, true | Record<string, unknown>>;
+}
+
+// ---- Runtime project/workspace interfaces ----
+
+export interface IProject {
+  readonly name: string;
+  readonly dir: string;
+  readonly tags: readonly string[];
+  readonly capabilities: Readonly<Record<string, true | Record<string, unknown>>>;
+
+  has(capability: string): boolean;
+  capability<T = true | Record<string, unknown>>(name: string): T;
+  path(name: string): string;
+}
+
+export interface IWorkspace {
+  readonly root: string;
+  readonly projects: readonly IProject[];
+
+  get(name: string): IProject;
+  withCapability(cap: string): IProject[];
+  withTag(tag: string): IProject[];
+}
+
+// ---- Command definitions ----
+
+export type ToolHandler = (
+  args: Record<string, unknown>,
+) => Promise<CallToolResult>;
+
+export interface StaticCommandDef {
+  name: string;
+  label: string;
+  description: string;
+  /** Positional arguments (order = key order). */
+  args?: SchemaFields;
+  /** Named flags (--key value). */
+  flags?: SchemaFields;
+  handler: ToolHandler;
+}
+
+export interface DynamicCommandDef {
+  name: string;
+  label: string;
+  description: string;
+  factory: (workspace: IWorkspace) => {
+    args?: SchemaFields;
+    flags?: SchemaFields;
+    handler: ToolHandler;
+  };
+}
+
+export type CommandDef = StaticCommandDef | DynamicCommandDef;
+
+export interface ResolvedCommand {
+  name: string;
+  label: string;
+  group: string;
+  description: string;
+  /** Merged JSON Schema from args + flags. */
+  inputSchema: Record<string, unknown>;
+  /** Positional arg names in order. */
+  positional: string[];
+  handler: ToolHandler;
+  /** Absolute path to the command source file. */
+  sourceFile?: string;
+}