@ldlework/workmark 1.3.1 → 1.4.1

package/README.md

@@ -16,29 +16,33 @@ pnpm add @ldlework/workmark
 
 ### Write a command
 
-Create commands in `.wm/commands/`. Subdirectories become groups in the CLI, dashboard and MCP server.
+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
-import { exec } from "@ldlework/workmark/helpers";
+/** Pack sprite sheets from raw assets */
+import { cmd } from "@ldlework/workmark/define";
 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",
+export default cmd({
   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;
+  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
@@ -118,25 +122,19 @@ A **dynamic command** receives the workspace and builds its schema from project
 
 ```ts
 // .wm/commands/deploy.ts
-import { exec } from "@ldlework/workmark/helpers";
+/** Deploy a project */
 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);
-
+    const names = workspace.withCapability("deploy").map((p) => p.name);
     return {
-      args: {
-        project: z.enum(names as [string, ...string[]]),
-      },
-      handler: async ({ project }) => {
+      args: { project: z.enum(names as [string, ...string[]]) },
+      handler: ({ project }) => {
         const p = workspace.get(project as string);
-        return exec(`./scripts/deploy.sh`, { cwd: p.dir });
+        return { content: [{ type: "text", text: `deploying ${p.name}` }] };
+        // or: return `./scripts/deploy.sh` (with cwd resolved to workspace root by default)
       },
     };
   },

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[]>;