@ldlework/workmark 1.3.0 → 1.4.1

package/README.md

@@ -0,0 +1,263 @@
+# @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. The filename becomes the command name, a leading JSDoc becomes the description, and a string return is executed as a shell command in the workspace root.
+
+```ts
+// .wm/commands/art/sprites.ts
+/** Pack sprite sheets from raw assets */
+import { cmd } from "@ldlework/workmark/define";
+import { z } from "zod";
+
+export default cmd({
+  args: {
+    target: z.enum(["all", "characters", "terrain", "ui"]).default("all"),
+  },
+  flags: {
+    watch: z.boolean().default(false),
+  },
+  handler: ({ target, watch }) =>
+    `./tools/pack-sprites.sh ${target}${watch ? " --watch" : ""}`,
+});
+```
+
+For a bare shell alias:
+
+```ts
+// .wm/commands/build.ts
+/** Build the project */
+import { cmd } from "@ldlework/workmark/define";
+export default cmd({ handler: () => "cargo build" });
+```
+
+### 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
+/** Deploy a project */
+import { z } from "zod";
+import type { DynamicCommandDef } from "@ldlework/workmark/types";
+
+export default {
+  factory: (workspace) => {
+    const names = workspace.withCapability("deploy").map((p) => p.name);
+    return {
+      args: { project: z.enum(names as [string, ...string[]]) },
+      handler: ({ project }) => {
+        const p = workspace.get(project as string);
+        return { content: [{ type: "text", text: `deploying ${p.name}` }] };
+        // or: return `./scripts/deploy.sh` (with cwd resolved to workspace root by default)
+      },
+    };
+  },
+} 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

@@ -97,7 +97,14 @@ async function main() {
         return;
     }
     const args = parseArgs(rest, cmd.positional, cmd.inputSchema);
-    const result = await cmd.handler(args);
+    let result;
+    try {
+        result = await cmd.handler(args);
+    }
+    catch (e) {
+        process.stderr.write((e instanceof Error ? e.message : String(e)) + "\n");
+        process.exit(1);
+    }
     for (const content of result.content) {
         if (content.type === "text") {
             const stream = result.isError ? process.stderr : process.stdout;
@@ -108,6 +115,6 @@ async function main() {
         process.exit(1);
 }
 main().catch((err) => {
-    console.error("Fatal:", err);
+    process.stderr.write((err instanceof Error ? err.message : String(err)) + "\n");
     process.exit(1);
 });

package/dist/lib/define.d.ts

@@ -1,3 +1,72 @@
-import type { ProjectDef } from "./types.js";
-/** Define a project. Identity function for type safety. */
+import { z } from "zod";
+import type { BaseCtx, FromArgsResolver, FromWorkspaceResolver, HandlerReturn, NeedsCtx, ProjectDef, ReduceFn, RunOptions, SchemaFields, SelectMode, Trait } from "./types.js";
+/** Declare a trait: a named schema that projects fulfill and commands require. */
+export declare function defineTrait<N extends string, S extends z.ZodType>(def: {
+    name: N;
+    schema: S;
+    description?: string;
+}): Trait<N, z.output<S>>;
 export declare function defineProject(def: ProjectDef): ProjectDef;
+type TraitsOf<N extends readonly Trait<string, unknown>[]> = {
+    [K in N[number] as K["name"]]: K extends Trait<string, infer T> ? T : never;
+};
+type InferField<F> = F extends z.ZodType ? z.output<F> : unknown;
+type InferFields<R extends SchemaFields | undefined> = R extends SchemaFields ? {
+    [K in keyof R]: InferField<R[K]>;
+} : Record<string, never>;
+type CtxFor<N extends readonly Trait<string, unknown>[]> = N extends readonly [] ? BaseCtx : NeedsCtx<TraitsOf<N>>;
+export interface StaticCommandDef {
+    needs?: readonly Trait[];
+    select?: SelectMode;
+    for?: string;
+    run?: RunOptions;
+    args?: SchemaFields;
+    flags?: SchemaFields;
+    meta?: {
+        name?: string;
+        label?: string;
+        description?: string;
+    };
+    handler: (args: Record<string, unknown>, ctx: BaseCtx | NeedsCtx<Record<string, unknown>>) => HandlerReturn | Promise<HandlerReturn>;
+}
+/** Declare a command. `needs`, `args`, and `flags` are inferred for handler
+ * typing; the framework manages the auto-generated `project` arg separately.
+ *
+ * `for`: bind the command to a named project. No project arg is exposed on any
+ * surface; `ctx.project` is the bound project. Validated at load.
+ */
+export declare function cmd<const N extends readonly Trait<string, unknown>[] = readonly [], const A extends SchemaFields = Record<string, never>, const F extends SchemaFields = Record<string, never>>(def: {
+    needs?: N;
+    select?: SelectMode;
+    for?: string;
+    run?: RunOptions;
+    args?: A;
+    flags?: F;
+    meta?: {
+        name?: string;
+        label?: string;
+        description?: string;
+    };
+    handler: (args: InferFields<A> & InferFields<F>, ctx: CtxFor<N>) => HandlerReturn | Promise<HandlerReturn>;
+}): StaticCommandDef;
+export declare const defineCommand: typeof cmd;
+/** Declare a schema that depends on workspace state. The framework resolves
+ * the marker during command load and substitutes the returned zod schema. */
+export declare function fromWorkspace(resolver: FromWorkspaceResolver): z.ZodType;
+/** Declare a schema whose shape depends on other args supplied at invocation.
+ * The framework resolves this per-call, AFTER other args are parsed. The
+ * field's load-time JSON Schema is permissive (type-agnostic) — validation
+ * runs at invocation with the resolved schema. */
+export declare function fromArgs(resolver: FromArgsResolver): z.ZodType;
+/** Shortcut: enum of project names fulfilling a trait. */
+export declare function projectsOf(trait: Trait): z.ZodType;
+/** Build a schema whose shape depends on a specific project's trait data.
+ *
+ * Usage: `traitField(docker, d => z.enum(d.buildable)).forProject("ghost")`.
+ */
+export declare function traitField<T extends Trait<string, unknown>>(trait: T, selector: (data: unknown) => z.ZodType): TraitFieldBuilder;
+export interface TraitFieldBuilder {
+    forProject(name: string): z.ZodType;
+    fromArg(argName: string): z.ZodType;
+}
+export type { SelectMode, RunOptions, ReduceFn };

package/dist/lib/define.js

@@ -1,4 +1,90 @@
-/** Define a project. Identity function for type safety. */
+import { z } from "zod";
+import { FROM_ARGS, FROM_WORKSPACE } from "./types.js";
+import { registerAmbient } from "./registry.js";
+// ---- defineTrait -------------------------------------------------------
+/** Declare a trait: a named schema that projects fulfill and commands require. */
+export function defineTrait(def) {
+    const trait = {
+        name: def.name,
+        schema: def.schema,
+        description: def.description,
+    };
+    // Register into ambient registry (installed by the loader during trait import).
+    registerAmbient(trait);
+    return trait;
+}
+// ---- defineProject -----------------------------------------------------
 export function defineProject(def) {
     return def;
 }
+/** Declare a command. `needs`, `args`, and `flags` are inferred for handler
+ * typing; the framework manages the auto-generated `project` arg separately.
+ *
+ * `for`: bind the command to a named project. No project arg is exposed on any
+ * surface; `ctx.project` is the bound project. Validated at load.
+ */
+export function cmd(def) {
+    return def;
+}
+export const defineCommand = cmd;
+// ---- fromWorkspace ------------------------------------------------------
+/** Declare a schema that depends on workspace state. The framework resolves
+ * the marker during command load and substitutes the returned zod schema. */
+export function fromWorkspace(resolver) {
+    const marker = z.lazy(() => {
+        throw new Error("fromWorkspace marker used at runtime — the framework should have replaced it at load time");
+    });
+    marker[FROM_WORKSPACE] = resolver;
+    return marker;
+}
+/** Declare a schema whose shape depends on other args supplied at invocation.
+ * The framework resolves this per-call, AFTER other args are parsed. The
+ * field's load-time JSON Schema is permissive (type-agnostic) — validation
+ * runs at invocation with the resolved schema. */
+export function fromArgs(resolver) {
+    const marker = z.any();
+    marker[FROM_ARGS] = resolver;
+    return marker;
+}
+/** Shortcut: enum of project names fulfilling a trait. */
+export function projectsOf(trait) {
+    return fromWorkspace((ws) => {
+        const names = ws.withTrait(trait).map((p) => p.name);
+        if (names.length === 0) {
+            throw new Error(`No projects fulfill trait "${trait.name}"`);
+        }
+        return z.enum(names);
+    });
+}
+/** Build a schema whose shape depends on a specific project's trait data.
+ *
+ * Usage: `traitField(docker, d => z.enum(d.buildable)).forProject("ghost")`.
+ */
+export function traitField(trait, selector) {
+    return {
+        forProject(name) {
+            return fromWorkspace((ws) => {
+                const project = ws.get(name);
+                if (!project.hasTrait(trait)) {
+                    throw new Error(`traitField(${trait.name}).forProject("${name}") — project does not fulfill trait "${trait.name}"`);
+                }
+                const data = project.trait(trait);
+                return selector(data);
+            });
+        },
+        fromArg(argName) {
+            return fromArgs((ws, args) => {
+                const target = args[argName];
+                if (typeof target !== "string") {
+                    throw new Error(`traitField(${trait.name}).fromArg("${argName}") — expected arg "${argName}" to be a project name string, got ${typeof target}`);
+                }
+                const project = ws.get(target);
+                if (!project.hasTrait(trait)) {
+                    throw new Error(`traitField(${trait.name}).fromArg("${argName}") — project "${target}" does not fulfill trait "${trait.name}"`);
+                }
+                const data = project.trait(trait);
+                return selector(data);
+            });
+        },
+    };
+}

package/dist/lib/helpers.d.ts

@@ -4,8 +4,11 @@ export declare function fail(error: unknown): CallToolResult;
 export interface ExecOptions {
     cwd: string;
     timeout?: number;
+    env?: Record<string, string>;
 }
 export declare function execRaw(command: string, opts: ExecOptions): string;
 export declare function exec(command: string, opts: ExecOptions): CallToolResult;
 export declare function execAsyncRaw(command: string, opts: ExecOptions): Promise<string>;
+/** Run a sequence of shell commands. Fails fast; concatenates outputs. */
+export declare function shSeq(commands: readonly string[], opts: ExecOptions): Promise<CallToolResult>;
 export declare function execAsync(command: string, opts: ExecOptions): Promise<CallToolResult>;

package/dist/lib/helpers.js

@@ -26,13 +26,14 @@ export function fail(error) {
     return { content: [{ type: "text", text: msg }], isError: true };
 }
 export function execRaw(command, opts) {
-    const { cwd, timeout = 120_000 } = opts;
+    const { cwd, timeout = 120_000, env } = opts;
     return execSync(command, {
         cwd,
         timeout,
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "pipe"],
         maxBuffer: 1024 * 1024 * 10,
+        env: env ? { ...process.env, ...env } : process.env,
     });
 }
 export function exec(command, opts) {
@@ -45,15 +46,32 @@ export function exec(command, opts) {
 }
 const execPromise = promisify(cpExec);
 export async function execAsyncRaw(command, opts) {
-    const { cwd, timeout = 120_000 } = opts;
+    const { cwd, timeout = 120_000, env } = opts;
     const { stdout } = await execPromise(command, {
         cwd,
         timeout,
         encoding: "utf-8",
         maxBuffer: 1024 * 1024 * 10,
+        env: env ? { ...process.env, ...env } : process.env,
     });
     return stdout;
 }
+/** Run a sequence of shell commands. Fails fast; concatenates outputs. */
+export async function shSeq(commands, opts) {
+    const outputs = [];
+    for (const cmd of commands) {
+        try {
+            outputs.push(await execAsyncRaw(cmd, opts));
+        }
+        catch (e) {
+            const prior = outputs.join("\n");
+            const err = e instanceof Error ? e : null;
+            const errText = err?.stderr || err?.stdout || (err?.message ?? String(e));
+            return fail(prior ? `${prior}\n${errText}` : errText);
+        }
+    }
+    return ok(outputs.join("\n"));
+}
 export async function execAsync(command, opts) {
     try {
         return ok(await execAsyncRaw(command, opts));

package/dist/lib/load.d.ts

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