@ldlework/workmark 1.2.0 → 1.3.1

package/README.md

@@ -0,0 +1,265 @@
+# @ldlework/workmark
+
+Most workspaces accumulate a graveyard of shell scripts, Makefiles, npm scripts, and "just run this" tribal knowledge. Workmark lets you define these workspace operations in TypeScript and run them from:
+
+- **CLI** — the `wm` command, with auto-generated help and argument parsing
+- **VS Code** — a dashboard extension with auto-generated forms for every command/parameter
+- **AI Agents** — a built-in MCP server so any MCP client can discover and run your commands
+
+## Quick start
+
+### Install
+
+```bash
+pnpm add @ldlework/workmark
+```
+
+### Write a command
+
+Create commands in `.wm/commands/`. Subdirectories become groups in the CLI, dashboard and MCP server.
+
+```ts
+// .wm/commands/art/sprites.ts
+import { exec } from "@ldlework/workmark/helpers";
+import { z } from "zod";
+import type { CommandDef } from "@ldlework/workmark/types";
+
+export default {
+  name: "sprites",
+  label: "Build Sprites",
+  description: "Pack sprite sheets from raw assets",
+  args: {
+    target: z.enum(["all", "characters", "terrain", "ui"]).default("all"),
+  },
+  flags: {
+    watch: z.boolean().default(false),
+  },
+  handler: async ({ target, watch }) => {
+    const cmd = `./tools/pack-sprites.sh ${target}${watch ? " --watch" : ""}`;
+    return exec(cmd, { cwd: process.cwd() });
+  },
+} satisfies CommandDef;
+```
+
+### Run it
+
+```bash
+wm sprites                      # pack all sprite sheets
+wm sprites characters --watch   # pack characters, rebuild on change
+wm --help                       # list all commands
+wm sprites --help               # per-command help
+```
+
+## Projects
+
+If your workspace contains multiple packages or services, you can define **projects** so that commands can discover and operate on them. Drop a `wm.ts` in any project directory:
+
+```ts
+// packages/api/wm.ts
+import { defineProject } from "@ldlework/workmark/define";
+
+export default defineProject({
+  name: "api",
+  tags: ["backend"],
+});
+```
+
+```ts
+// packages/web/wm.ts
+import { defineProject } from "@ldlework/workmark/define";
+
+export default defineProject({
+  name: "web",
+  tags: ["frontend"],
+});
+```
+
+Workmark recursively discovers all `wm.ts` files from the workspace root (respecting `.gitignore`). Projects are available to commands via the workspace object — query them by name with `workspace.get("api")`, by tag with `workspace.withTag("backend")`, or by capability with `workspace.withCapability("deploy")`.
+
+### Capabilities
+
+Capabilities are structured metadata attached to projects. A project declares what it supports, and commands filter by it — this keeps project-specific config out of your command files. For example, marking a project with `deploy: true` advertises that it has the `scripts/deploy.sh` script that the `deploy` command expects.
+
+```ts
+// packages/api/wm.ts
+export default defineProject({
+  name: "api",
+  tags: ["backend"],
+  capabilities: { deploy: true },
+});
+```
+
+```ts
+// packages/web/wm.ts
+export default defineProject({
+  name: "web",
+  tags: ["frontend"],
+  capabilities: { deploy: true },
+});
+```
+
+`workspace.withCapability("deploy")` returns both projects. Capabilities can also carry structured data:
+
+```ts
+export default defineProject({
+  name: "api",
+  capabilities: {
+    deploy: true,
+    build: { targets: ["esm", "cjs"] },
+  },
+});
+```
+
+Commands read this with `project.capability<{ targets: string[] }>("build")`. This pattern works for anything — build targets, test runners, linting rules.
+
+### Dynamic commands
+
+A **dynamic command** receives the workspace and builds its schema from project metadata. Here, the `deploy` command finds all projects with the `deploy` capability and populates its argument from their names:
+
+```ts
+// .wm/commands/deploy.ts
+import { exec } from "@ldlework/workmark/helpers";
+import { z } from "zod";
+import type { DynamicCommandDef } from "@ldlework/workmark/types";
+
+export default {
+  name: "deploy",
+  label: "Deploy",
+  description: "Deploy a project",
+  factory: (workspace) => {
+    const projects = workspace.withCapability("deploy");
+    const names = projects.map((p) => p.name);
+
+    return {
+      args: {
+        project: z.enum(names as [string, ...string[]]),
+      },
+      handler: async ({ project }) => {
+        const p = workspace.get(project as string);
+        return exec(`./scripts/deploy.sh`, { cwd: p.dir });
+      },
+    };
+  },
+} satisfies DynamicCommandDef;
+```
+
+```bash
+wm deploy api
+wm deploy web
+```
+
+The CLI help, VS Code dropdowns, and MCP tool schema all show exactly the valid project names — no impossible combinations, no runtime validation needed.
+
+## Features
+
+### CLI
+
+The `wm` binary auto-discovers your commands and generates help text, argument parsing, and type coercion.
+
+```
+$ wm --help
+
+Usage: wm <command> [args...]
+
+Commands:
+  sprites         Pack sprite sheets from raw assets
+  deploy          Deploy a project to an environment
+  db:migrate      Run database migrations
+
+Run wm <command> --help for details on a specific command.
+```
+
+Arguments support positional args and named flags:
+
+```bash
+wm sprites characters              # positional (from args)
+wm sprites characters --watch      # positional + flag
+wm deploy api                      # dynamic command with project arg
+wm deploy --project api            # everything works as flags too
+```
+
+### VS Code dashboard
+
+Install the [`workmark-vsc`](https://marketplace.visualstudio.com/items?itemName=ldlework.workmark-vsc) extension. It adds a **Workspace** panel to the activity bar showing all your commands grouped by category with auto-generated forms:
+
+- Enum fields become dropdowns
+- Booleans become checkboxes
+- Numbers get validated inputs with min/max
+- Required fields are enforced before execution
+- Double-click any command to jump to its source file
+
+Commands run in the integrated terminal, so you get full color output and interactivity.
+
+### MCP server
+
+Workmark includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) server. Every command you define is automatically exposed as an MCP tool, which means AI assistants like Claude can discover and invoke your workspace commands.
+
+```jsonc
+// claude_desktop_config.json or .mcp.json
+{
+  "mcpServers": {
+    "workspace": {
+      "command": "node",
+      "args": ["./node_modules/@ldlework/workmark/dist/index.js"]
+    }
+  }
+}
+```
+
+Once connected, your assistant can run `wm deploy api` the same way you do — with full schema validation and typed responses.
+
+## Project structure
+
+```
+your-workspace/
+├── .wm/
+│   └── commands/
+│       ├── deploy.ts         # Root-level command
+│       ├── art/
+│       │   └── sprites.ts    # Grouped under "Art"
+│       └── db/
+│           └── migrate.ts    # Grouped under "Db"
+├── packages/
+│   ├── api/
+│   │   └── wm.ts             # Project definition
+│   └── web/
+│       └── wm.ts
+```
+
+- **`wm.ts`** — project definitions, discovered recursively
+- **`.wm/commands/**/*.ts`** — command files, grouped by directory name
+
+## API reference
+
+### Defining
+
+```ts
+import { defineProject } from "@ldlework/workmark/define";
+```
+
+### Helpers
+
+```ts
+import { ok, fail, exec, execAsync } from "@ldlework/workmark/helpers";
+
+ok(data)                     // Wrap data in a success CallToolResult
+fail(error)                  // Wrap error in an error CallToolResult
+exec(cmd, { cwd })           // Synchronous shell exec, returns CallToolResult
+execAsync(cmd, { cwd })      // Async shell exec, returns Promise<CallToolResult>
+execRaw(cmd, { cwd })        // Synchronous shell exec, returns string (throws on error)
+execAsyncRaw(cmd, { cwd })   // Async shell exec, returns Promise<string> (throws on error)
+```
+
+### Loading
+
+```ts
+import { loadWorkspace } from "@ldlework/workmark/workspace";
+import { loadCommands } from "@ldlework/workmark";
+
+const workspace = await loadWorkspace();
+const commands = await loadCommands(workspace);
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -6,7 +6,7 @@ import { parseArgs } from "./lib/parse.js";
 // Help
 // ---------------------------------------------------------------------------
 function printHelp(commands) {
-    console.log("Usage: ws <command> [args...]\n");
+    console.log("Usage: wm <command> [args...]\n");
     // Group by group name
     const groups = new Map();
     for (const cmd of commands) {
@@ -43,7 +43,7 @@ function printHelp(commands) {
 }
 function printCommandHelp(cmd) {
     const pos = cmd.positional.map((p) => `<${p}>`).join(" ");
-    console.log(`Usage: ws ${cmd.name} ${pos}\n`);
+    console.log(`Usage: wm ${cmd.name} ${pos}\n`);
     console.log(cmd.description);
     const schema = cmd.inputSchema;
     const props = schema.properties;
@@ -88,7 +88,7 @@ async function main() {
     const cmd = cmdMap.get(command);
     if (!cmd) {
         console.error(`Unknown command: ${command}`);
-        console.error(`Run 'ws --help' for available commands.`);
+        console.error(`Run 'wm --help' for available commands.`);
         process.exit(1);
     }
     // Per-command help

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

@@ -1,6 +1,6 @@
 import type { JitiOptions } from "jiti";
 /**
- * Build jiti options that let ws.ts / command files import from
+ * Build jiti options that let wm.ts / command files import from
  * `@ldlework/workmark/*` and from workmark's own dependencies (zod, etc.)
  * regardless of how the package is installed or linked.
  */

package/dist/lib/jiti-options.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 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
+ * Build jiti options that let wm.ts / command files import from
  * `@ldlework/workmark/*` and from workmark's own dependencies (zod, etc.)
  * regardless of how the package is installed or linked.
  */

package/dist/lib/load.js

@@ -17,33 +17,33 @@ function fieldToJsonSchema(field) {
     }
     return field;
 }
+/** A field is required unless it has a default or was wrapped with .optional(). */
+function isRequired(field, schema) {
+    if ("default" in schema)
+        return false;
+    if (field instanceof z.ZodType && field.safeParse(undefined).success)
+        return false;
+    return true;
+}
 /** 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 collect = (source, isPositional) => {
+        if (!source)
+            return;
+        for (const [name, field] of Object.entries(source)) {
             const schema = fieldToJsonSchema(field);
             properties[name] = schema;
-            if (!("default" in schema)) {
+            if (isPositional)
+                positional.push(name);
+            if (isRequired(field, schema))
                 required.push(name);
-            }
         }
-    }
+    };
+    collect(args, true);
+    collect(flags, false);
     const inputSchema = {
         type: "object",
         properties,
@@ -72,7 +72,7 @@ function resolve(def, workspace, group, sourceFile) {
     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");
+    const commandsDir = join(workspace.root, ".wm", "commands");
     if (!existsSync(commandsDir))
         return [];
     const jiti = createJiti(commandsDir, jitiOptions());

package/dist/lib/types.d.ts

@@ -7,7 +7,7 @@ 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 ".". */
+    /** Project directory relative to the wm.ts location. Defaults to ".". */
     dir?: string;
     /** Arbitrary string tags for grouping/filtering. */
     tags?: string[];

package/dist/lib/workspace.js

@@ -44,8 +44,8 @@ function loadIgnore(root) {
     }
     return ig;
 }
-/** Recursively find all ws.ts files, respecting .gitignore rules. */
-function findWsFiles(root) {
+/** Recursively find all wm.ts files, respecting .gitignore rules. */
+function findWmFiles(root) {
     const ig = loadIgnore(root);
     const results = [];
     function walk(dir) {
@@ -55,7 +55,7 @@ function findWsFiles(root) {
                 if (!ig.ignores(rel + "/"))
                     walk(join(dir, entry.name));
             }
-            else if (entry.name === "ws.ts") {
+            else if (entry.name === "wm.ts") {
                 results.push(join(dir, entry.name));
             }
         }
@@ -63,35 +63,35 @@ function findWsFiles(root) {
     walk(root);
     return results;
 }
-/** Find the workspace root by walking up from cwd looking for .ws/. */
+/** Find the workspace root by walking up from cwd looking for .wm/. */
 function findRoot(from) {
     let dir = from;
     while (true) {
-        if (existsSync(join(dir, ".ws"))) {
+        if (existsSync(join(dir, ".wm"))) {
             return dir;
         }
         const parent = dirname(dir);
         if (parent === dir)
-            throw new Error("Could not find workspace root (.ws/ directory)");
+            throw new Error("Could not find workspace root (.wm/ 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);
+    // Recursively find all wm.ts files
+    const wmFiles = findWmFiles(root);
     // Import each and build Project instances
     const projects = [];
-    for (const wsFile of wsFiles) {
-        const dir = dirname(wsFile);
+    for (const wmFile of wmFiles) {
+        const dir = dirname(wmFile);
         let exported;
         try {
-            exported = await jiti.import(wsFile);
+            exported = await jiti.import(wmFile);
         }
         catch (err) {
-            // Log import failures — helps debug bad ws.ts files
-            console.error(`[workspace] Skipping ${wsFile}: ${err.message}`);
+            // Log import failures — helps debug bad wm.ts files
+            console.error(`[workspace] Skipping ${wmFile}: ${err.message}`);
             continue;
         }
         // jiti may return { default: ... } when interopDefault doesn't fully unwrap

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ldlework/workmark",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "type": "module",
   "main": "dist/lib/load.js",
   "bin": {
-    "ws": "dist/cli.js"
+    "wm": "dist/cli.js"
   },
   "engines": {
     "node": ">=18"

package/src/cli.ts

@@ -10,7 +10,7 @@ import type { ResolvedCommand } from "./lib/types.js";
 // ---------------------------------------------------------------------------
 
 function printHelp(commands: ResolvedCommand[]): void {
-  console.log("Usage: ws <command> [args...]\n");
+  console.log("Usage: wm <command> [args...]\n");
 
   // Group by group name
   const groups = new Map<string, ResolvedCommand[]>();
@@ -51,7 +51,7 @@ function printHelp(commands: ResolvedCommand[]): void {
 
 function printCommandHelp(cmd: ResolvedCommand): void {
   const pos = cmd.positional.map((p) => `<${p}>`).join(" ");
-  console.log(`Usage: ws ${cmd.name} ${pos}\n`);
+  console.log(`Usage: wm ${cmd.name} ${pos}\n`);
   console.log(cmd.description);
 
   const schema = cmd.inputSchema as {
@@ -103,7 +103,7 @@ async function main(): Promise<void> {
   const cmd = cmdMap.get(command);
   if (!cmd) {
     console.error(`Unknown command: ${command}`);
-    console.error(`Run 'ws --help' for available commands.`);
+    console.error(`Run 'wm --help' for available commands.`);
     process.exit(1);
   }
 

package/src/lib/jiti-options.ts

@@ -7,7 +7,7 @@ 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
+ * Build jiti options that let wm.ts / command files import from
  * `@ldlework/workmark/*` and from workmark's own dependencies (zod, etc.)
  * regardless of how the package is installed or linked.
  */

package/src/lib/load.ts

@@ -22,6 +22,13 @@ function fieldToJsonSchema(field: z.ZodType | Record<string, unknown>): Record<s
   return field;
 }
 
+/** A field is required unless it has a default or was wrapped with .optional(). */
+function isRequired(field: z.ZodType | Record<string, unknown>, schema: Record<string, unknown>): boolean {
+  if ("default" in schema) return false;
+  if (field instanceof z.ZodType && field.safeParse(undefined).success) return false;
+  return true;
+}
+
 /** Merge args + flags into a single JSON Schema object and return positional names. */
 function mergeSchemas(
   args?: SchemaFields,
@@ -31,29 +38,18 @@ function mergeSchemas(
   const required: string[] = [];
   const positional: string[] = [];
 
-  // Args are positional, in key order
-  if (args) {
-    for (const [name, field] of Object.entries(args)) {
+  const collect = (source: SchemaFields | undefined, isPositional: boolean) => {
+    if (!source) return;
+    for (const [name, field] of Object.entries(source)) {
       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);
-      }
+      if (isPositional) positional.push(name);
+      if (isRequired(field, 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);
-      }
-    }
-  }
+  collect(args, true);
+  collect(flags, false);
 
   const inputSchema: Record<string, unknown> = {
     type: "object",
@@ -87,7 +83,7 @@ function resolve(def: CommandDef, workspace: IWorkspace, group: string, sourceFi
 }
 
 export async function loadCommands(workspace: IWorkspace): Promise<ResolvedCommand[]> {
-  const commandsDir = join(workspace.root, ".ws", "commands");
+  const commandsDir = join(workspace.root, ".wm", "commands");
   if (!existsSync(commandsDir)) return [];
 
   const jiti = createJiti(commandsDir, jitiOptions());

package/src/lib/types.ts

@@ -7,12 +7,12 @@ 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) ----
+// ---- Project definitions (used in wm.ts files) ----
 
 export interface ProjectDef {
   /** Unique identifier. */
   name: string;
-  /** Project directory relative to the ws.ts location. Defaults to ".". */
+  /** Project directory relative to the wm.ts location. Defaults to ".". */
   dir?: string;
   /** Arbitrary string tags for grouping/filtering. */
   tags?: string[];

package/src/lib/workspace.ts

@@ -52,8 +52,8 @@ function loadIgnore(root: string): Ignore {
   return ig;
 }
 
-/** Recursively find all ws.ts files, respecting .gitignore rules. */
-function findWsFiles(root: string): string[] {
+/** Recursively find all wm.ts files, respecting .gitignore rules. */
+function findWmFiles(root: string): string[] {
   const ig = loadIgnore(root);
   const results: string[] = [];
 
@@ -62,7 +62,7 @@ function findWsFiles(root: string): string[] {
       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") {
+      } else if (entry.name === "wm.ts") {
         results.push(join(dir, entry.name));
       }
     }
@@ -72,15 +72,15 @@ function findWsFiles(root: string): string[] {
   return results;
 }
 
-/** Find the workspace root by walking up from cwd looking for .ws/. */
+/** Find the workspace root by walking up from cwd looking for .wm/. */
 function findRoot(from: string): string {
   let dir = from;
   while (true) {
-    if (existsSync(join(dir, ".ws"))) {
+    if (existsSync(join(dir, ".wm"))) {
       return dir;
     }
     const parent = dirname(dir);
-    if (parent === dir) throw new Error("Could not find workspace root (.ws/ directory)");
+    if (parent === dir) throw new Error("Could not find workspace root (.wm/ directory)");
     dir = parent;
   }
 }
@@ -89,20 +89,20 @@ export async function loadWorkspace(from?: string): Promise<Workspace> {
   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);
+  // Recursively find all wm.ts files
+  const wmFiles = findWmFiles(root);
 
   // Import each and build Project instances
   const projects: Project[] = [];
 
-  for (const wsFile of wsFiles) {
-    const dir = dirname(wsFile);
+  for (const wmFile of wmFiles) {
+    const dir = dirname(wmFile);
     let exported: unknown;
     try {
-      exported = await jiti.import(wsFile);
+      exported = await jiti.import(wmFile);
     } catch (err) {
-      // Log import failures — helps debug bad ws.ts files
-      console.error(`[workspace] Skipping ${wsFile}: ${(err as Error).message}`);
+      // Log import failures — helps debug bad wm.ts files
+      console.error(`[workspace] Skipping ${wmFile}: ${(err as Error).message}`);
       continue;
     }