@ldlework/workmark 1.0.0

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { loadCommands } from "./lib/load.js";
+import { loadWorkspace } from "./lib/workspace.js";
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+function parseValue(raw) {
+    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, positionalNames) {
+    const args = {};
+    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) {
+    console.log("Usage: ws <command> [args...]\n");
+    // Group by group name
+    const groups = new Map();
+    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) {
+    const pos = cmd.positional.map((p) => `<${p}>`).join(" ");
+    console.log(`Usage: ws ${cmd.name} ${pos}\n`);
+    console.log(cmd.description);
+    const schema = cmd.inputSchema;
+    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 = [];
+        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() {
+    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();
+    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/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/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() {
+    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/dist/lib/define.d.ts

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

package/dist/lib/define.js

@@ -0,0 +1,4 @@
+/** Define a project. Identity function for type safety. */
+export function defineProject(def) {
+    return def;
+}

package/dist/lib/helpers.d.ts

@@ -0,0 +1,9 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function ok(data: unknown): CallToolResult;
+export declare function fail(error: unknown): CallToolResult;
+export interface ExecOptions {
+    cwd: string;
+    timeout?: number;
+}
+export declare function exec(command: string, opts: ExecOptions): string;
+export declare function execAsync(command: string, opts: ExecOptions): Promise<string>;

package/dist/lib/helpers.js

@@ -0,0 +1,48 @@
+import { execSync, exec as cpExec } from "node:child_process";
+import { promisify } from "node:util";
+// --- Response helpers ---
+export function ok(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+export function fail(error) {
+    let msg;
+    if (error instanceof Error) {
+        const { stderr, stdout } = error;
+        msg =
+            (typeof stderr === "string" && stderr) ||
+                (typeof stdout === "string" && stdout) ||
+                error.message;
+    }
+    else {
+        msg = String(error);
+    }
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+export function exec(command, opts) {
+    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, opts) {
+    const { cwd, timeout = 120_000 } = opts;
+    const { stdout } = await execPromise(command, {
+        cwd,
+        timeout,
+        encoding: "utf-8",
+        maxBuffer: 1024 * 1024 * 10,
+    });
+    return stdout;
+}

package/dist/lib/jiti-options.d.ts

@@ -0,0 +1,7 @@
+import type { JitiOptions } from "jiti";
+/**
+ * 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 declare function jitiOptions(opts?: Partial<JitiOptions>): JitiOptions;

package/dist/lib/jiti-options.js

@@ -0,0 +1,26 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// 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) {
+    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/dist/lib/load.d.ts

@@ -0,0 +1,2 @@
+import type { IWorkspace, ResolvedCommand } from "./types.js";
+export declare function loadCommands(workspace: IWorkspace): Promise<ResolvedCommand[]>;

package/dist/lib/load.js

@@ -0,0 +1,105 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createJiti } from "jiti";
+import { z } from "zod";
+import { jitiOptions } from "./jiti-options.js";
+/** Title-case a folder name: "docker" → "Docker" */
+function titleCase(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function isStatic(def) {
+    return "handler" in def;
+}
+/** Convert a single field (Zod or raw JSON Schema property) to a JSON Schema property. */
+function fieldToJsonSchema(field) {
+    if (field instanceof z.ZodType) {
+        return z.toJSONSchema(field);
+    }
+    return field;
+}
+/** Merge args + flags into a single JSON Schema object and return positional names. */
+function mergeSchemas(args, flags) {
+    const properties = {};
+    const required = [];
+    const positional = [];
+    // 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 = {
+        type: "object",
+        properties,
+    };
+    if (required.length > 0) {
+        inputSchema.required = required;
+    }
+    return { inputSchema, positional };
+}
+function resolve(def, workspace, group, sourceFile) {
+    let args;
+    let flags;
+    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) {
+    const commandsDir = join(workspace.root, ".ws", "commands");
+    if (!existsSync(commandsDir))
+        return [];
+    const jiti = createJiti(commandsDir, jitiOptions());
+    const commands = [];
+    // 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);
+            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);
+                commands.push(resolve(mod.default, workspace, group, filePath));
+            }
+        }
+    }
+    return commands;
+}

package/dist/lib/project.d.ts

@@ -0,0 +1,12 @@
+import type { IProject, ProjectDef } from "./types.js";
+export declare 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;
+    constructor(def: ProjectDef, wsDir: string);
+    has(capability: string): boolean;
+    capability<T = true | Record<string, unknown>>(name: string): T;
+    path(name: string): string;
+}

package/dist/lib/project.js

@@ -0,0 +1,32 @@
+import { join } from "node:path";
+export class Project {
+    name;
+    dir;
+    tags;
+    capabilities;
+    paths;
+    constructor(def, wsDir) {
+        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) {
+        return capability in this.capabilities;
+    }
+    capability(name) {
+        const cap = this.capabilities[name];
+        if (cap === undefined) {
+            throw new Error(`Project "${this.name}" does not have capability "${name}"`);
+        }
+        return cap;
+    }
+    path(name) {
+        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/dist/lib/types.d.ts

@@ -0,0 +1,69 @@
+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>>;
+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>>;
+}
+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[];
+}
+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;
+}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/workspace.d.ts

@@ -0,0 +1,11 @@
+import type { IProject, IWorkspace } from "./types.js";
+export declare class Workspace implements IWorkspace {
+    readonly root: string;
+    readonly projects: readonly IProject[];
+    private readonly byName;
+    constructor(root: string, projects: IProject[]);
+    get(name: string): IProject;
+    withCapability(cap: string): IProject[];
+    withTag(tag: string): IProject[];
+}
+export declare function loadWorkspace(from?: string): Promise<Workspace>;

package/dist/lib/workspace.js

@@ -0,0 +1,109 @@
+import { dirname, join, relative } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { createJiti } from "jiti";
+import ignore from "ignore";
+import { Project } from "./project.js";
+import { jitiOptions } from "./jiti-options.js";
+export class Workspace {
+    root;
+    projects;
+    byName;
+    constructor(root, projects) {
+        this.root = root;
+        this.projects = Object.freeze(projects);
+        this.byName = new Map(projects.map((p) => [p.name, p]));
+        // Validate unique names
+        if (this.byName.size !== projects.length) {
+            const seen = new Set();
+            for (const p of projects) {
+                if (seen.has(p.name))
+                    throw new Error(`Duplicate project name: "${p.name}"`);
+                seen.add(p.name);
+            }
+        }
+    }
+    get(name) {
+        const p = this.byName.get(name);
+        if (!p)
+            throw new Error(`Unknown project: "${name}"`);
+        return p;
+    }
+    withCapability(cap) {
+        return this.projects.filter((p) => p.has(cap));
+    }
+    withTag(tag) {
+        return this.projects.filter((p) => p.tags.includes(tag));
+    }
+}
+/** Build an Ignore instance from .gitignore (if present) + hardcoded defaults. */
+function loadIgnore(root) {
+    const ig = ignore().add(["node_modules", "dist"]);
+    const gitignorePath = join(root, ".gitignore");
+    if (existsSync(gitignorePath)) {
+        ig.add(readFileSync(gitignorePath, "utf-8"));
+    }
+    return ig;
+}
+/** Recursively find all ws.ts files, respecting .gitignore rules. */
+function findWsFiles(root) {
+    const ig = loadIgnore(root);
+    const results = [];
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const rel = relative(root, join(dir, entry.name));
+            if (entry.isDirectory()) {
+                if (!ig.ignores(rel + "/"))
+                    walk(join(dir, entry.name));
+            }
+            else if (entry.name === "ws.ts") {
+                results.push(join(dir, entry.name));
+            }
+        }
+    }
+    walk(root);
+    return results;
+}
+/** Find the workspace root by walking up from cwd looking for .ws/. */
+function findRoot(from) {
+    let dir = from;
+    while (true) {
+        if (existsSync(join(dir, ".ws"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error("Could not find workspace root (.ws/ directory)");
+        dir = parent;
+    }
+}
+export async function loadWorkspace(from) {
+    const root = from ?? process.env.WORKSPACE_ROOT ?? findRoot(process.cwd());
+    const jiti = createJiti(root, jitiOptions());
+    // Recursively find all ws.ts files
+    const wsFiles = findWsFiles(root);
+    // Import each and build Project instances
+    const projects = [];
+    for (const wsFile of wsFiles) {
+        const dir = dirname(wsFile);
+        let exported;
+        try {
+            exported = await jiti.import(wsFile);
+        }
+        catch (err) {
+            // Log import failures — helps debug bad ws.ts files
+            console.error(`[workspace] Skipping ${wsFile}: ${err.message}`);
+            continue;
+        }
+        // jiti may return { default: ... } when interopDefault doesn't fully unwrap
+        if (exported && typeof exported === "object" && "default" in exported) {
+            exported = exported.default;
+        }
+        const items = Array.isArray(exported) ? exported : [exported];
+        for (const item of items) {
+            if (item && typeof item === "object" && typeof item.name === "string") {
+                projects.push(new Project(item, dir));
+            }
+        }
+    }
+    return new Workspace(root, projects);
+}