@ldlework/workmark 1.3.1 → 1.4.1

package/dist/lib/project.js

@@ -3,24 +3,28 @@ export class Project {
     name;
     dir;
     tags;
-    capabilities;
+    description;
+    /** Parsed (defaulted) trait data, keyed by trait name. */
+    traitData;
     paths;
-    constructor(def, wsDir) {
+    constructor(def, wsDir, traitData) {
         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 ?? {});
+        this.tags = Object.freeze([...(def.tags ?? [])]);
+        this.description = def.description;
+        this.traitData = Object.freeze(traitData);
+        this.paths = Object.freeze({ ...(def.paths ?? {}) });
     }
-    has(capability) {
-        return capability in this.capabilities;
+    hasTrait(trait) {
+        const name = typeof trait === "string" ? trait : trait.name;
+        return name in this.traitData;
     }
-    capability(name) {
-        const cap = this.capabilities[name];
-        if (cap === undefined) {
-            throw new Error(`Project "${this.name}" does not have capability "${name}"`);
+    trait(trait) {
+        const data = this.traitData[trait.name];
+        if (data === undefined) {
+            throw new Error(`Project "${this.name}" does not fulfill trait "${trait.name}"`);
         }
-        return cap;
+        return data;
     }
     path(name) {
         const rel = this.paths[name];
@@ -30,3 +34,32 @@ export class Project {
         return join(this.dir, rel);
     }
 }
+/** Validate a project's `has` against the registry, returning parsed data. */
+export function validateHas(def, registry, sourceFile) {
+    const out = {};
+    const has = def.has ?? {};
+    for (const [traitName, raw] of Object.entries(has)) {
+        const trait = registry.get(traitName);
+        if (!trait) {
+            const known = registry.all().map((t) => t.name).join(", ") || "(none)";
+            throw new Error(`Project "${def.name}" declares has.${traitName}, but no such trait is defined\n  at ${sourceFile}\n  known traits: ${known}`);
+        }
+        // Marker-trait sugar: `has: { x: true }` parses the trait with `{}`, which
+        // triggers per-field defaults. Zod 4's outer `.default({})` returns `{}`
+        // for undefined input — useful but NOT deeply defaulted — so we pass `{}`
+        // explicitly to get nested defaults.
+        const input = raw === true ? {} : raw;
+        const result = trait.schema.safeParse(input);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`)
+                .join("\n");
+            const hint = raw === true
+                ? `\n  hint: "true" is sugar for defaults; trait "${traitName}" has no top-level .default(). Provide an object literal.`
+                : "";
+            throw new Error(`Project "${def.name}" has.${traitName} failed validation:\n${issues}\n  at ${sourceFile}${hint}`);
+        }
+        out[traitName] = result.data;
+    }
+    return out;
+}

package/dist/lib/registry.d.ts

@@ -0,0 +1,15 @@
+import type { Trait } from "./types.js";
+/** Per-load trait registry. A fresh instance is created for each `loadWorkspace`
+ * call so reloads don't trip duplicate-name checks against prior state. */
+export declare class TraitRegistry {
+    private readonly traits;
+    private readonly sources;
+    register(trait: Trait, sourceFile?: string): void;
+    get(name: string): Trait | undefined;
+    require(name: string): Trait;
+    has(name: string): boolean;
+    all(): readonly Trait[];
+}
+export declare function installRegistry(reg: TraitRegistry): void;
+export declare function uninstallRegistry(): void;
+export declare function registerAmbient(trait: Trait, sourceFile?: string): void;

package/dist/lib/registry.js

@@ -0,0 +1,64 @@
+/** Per-load trait registry. A fresh instance is created for each `loadWorkspace`
+ * call so reloads don't trip duplicate-name checks against prior state. */
+export class TraitRegistry {
+    traits = new Map();
+    sources = new Map();
+    register(trait, sourceFile) {
+        const existing = this.traits.get(trait.name);
+        const prevSource = this.sources.get(trait.name);
+        if (existing) {
+            // Same source file re-executed (jiti moduleCache:false) is idempotent.
+            // Different source files with the same name is an error.
+            if (sourceFile && prevSource && sourceFile !== prevSource) {
+                throw new Error(`Trait "${trait.name}" defined twice:\n  ${prevSource}\n  ${sourceFile}`);
+            }
+            // Keep the first-registered trait object as canonical.
+            return;
+        }
+        this.traits.set(trait.name, trait);
+        if (sourceFile)
+            this.sources.set(trait.name, sourceFile);
+    }
+    get(name) {
+        return this.traits.get(name);
+    }
+    require(name) {
+        const t = this.traits.get(name);
+        if (!t) {
+            const known = [...this.traits.keys()].join(", ") || "(none)";
+            throw new Error(`Unknown trait "${name}". Known: ${known}`);
+        }
+        return t;
+    }
+    has(name) {
+        return this.traits.has(name);
+    }
+    all() {
+        return [...this.traits.values()];
+    }
+}
+/** Ambient registry used by `defineTrait` at module-import time.
+ *
+ * Stored on `globalThis` so it survives the pnpm+jiti module-duplication problem:
+ * the CLI's workmark module and the jiti-loaded trait file's workmark module are
+ * distinct instances, but both see the same globalThis slot.
+ *
+ * The loader installs a fresh registry, imports trait files (which call
+ * defineTrait → registerAmbient → reads this slot), then uninstalls. */
+const GLOBAL_KEY = Symbol.for("workmark.ambientRegistry");
+function slot() {
+    return globalThis;
+}
+export function installRegistry(reg) {
+    slot()[GLOBAL_KEY] = reg;
+}
+export function uninstallRegistry() {
+    delete slot()[GLOBAL_KEY];
+}
+export function registerAmbient(trait, sourceFile) {
+    const reg = slot()[GLOBAL_KEY];
+    if (!reg) {
+        throw new Error(`defineTrait called outside of a workspace load. Traits must live in .wm/traits/*.ts files.`);
+    }
+    reg.register(trait, sourceFile);
+}

package/dist/lib/types.d.ts

@@ -1,69 +1,120 @@
 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>>;
+/** A named, schema-backed contract that projects fulfill and commands require.
+ *
+ * Identity is `name`. Created via `defineTrait`; the returned object carries a
+ * phantom type so `cmd({ needs: [docker] })` can infer trait-data types into
+ * the handler's `ctx.traits`. */
+export interface Trait<N extends string = string, T = unknown> {
+    readonly name: N;
+    readonly schema: z.ZodType;
+    readonly description?: string;
+    /** Phantom for inference. Never accessed at runtime. */
+    readonly __brand?: readonly ["trait", N, T];
+}
+/** A field schema: a zod type or raw JSON Schema object. */
+export type SchemaField = z.ZodType | Record<string, unknown>;
+/** A record of named field schemas. */
+export type SchemaFields = Record<string, SchemaField>;
 export interface ProjectDef {
     /** Unique identifier. */
     name: string;
     /** Project directory relative to the wm.ts location. Defaults to ".". */
     dir?: string;
-    /** Arbitrary string tags for grouping/filtering. */
+    /** Free-form labels. Filter only — no handler injection. */
     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>>;
+    /** Trait fulfillments. Keys are trait names; values are validated against
+     * the trait schema at load time. */
+    has?: Record<string, unknown>;
+    /** Optional human-readable description. */
+    description?: string;
 }
 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;
+    readonly description?: string;
+    /** Check whether this project fulfills a trait (by object or name). */
+    hasTrait(trait: Trait | string): boolean;
+    /** Get the parsed trait data. Throws if the project does not fulfill it. */
+    trait<T>(trait: Trait<string, T>): T;
+    /** Resolve a named path relative to this project's directory. */
     path(name: string): string;
 }
 export interface IWorkspace {
     readonly root: string;
     readonly projects: readonly IProject[];
     get(name: string): IProject;
-    withCapability(cap: string): IProject[];
+    withTrait(trait: Trait | 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;
+/** How many projects a command runs against. */
+export type SelectMode = "one" | "one-or-many" | "all";
+/** Framework-standard context passed to every handler. */
+export interface BaseCtx {
+    workspace: IWorkspace;
+    /** Run a shell command (or sequence) in the resolved cwd. An array is executed
+     * sequentially; fails fast; output is concatenated. */
+    sh: (cmd: string | readonly string[], opts?: {
+        timeout?: number;
+        env?: Record<string, string>;
+    }) => Promise<CallToolResult>;
+    /** Run a shell command with explicit options (cwd, timeout, env). */
+    exec: (cmd: string, opts: {
+        cwd: string;
+        timeout?: number;
+        env?: Record<string, string>;
+    }) => Promise<CallToolResult>;
+    ok: (data: unknown) => CallToolResult;
+    fail: (error: unknown) => CallToolResult;
+    /** Invoke another command by name with wire-shape args. */
+    invoke: (name: string, args: Record<string, unknown>) => Promise<CallToolResult>;
 }
-export interface DynamicCommandDef {
-    name: string;
-    label: string;
-    description: string;
-    factory: (workspace: IWorkspace) => {
-        args?: SchemaFields;
-        flags?: SchemaFields;
-        handler: ToolHandler;
-    };
+/** Context for commands with `needs`. Adds `project` and `traits`. */
+export interface NeedsCtx<Traits extends Record<string, unknown>> extends BaseCtx {
+    project: IProject;
+    traits: Traits;
 }
-export type CommandDef = StaticCommandDef | DynamicCommandDef;
+export type HandlerReturn = CallToolResult;
+/** A resolved, runnable command — what the framework holds after load. */
 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. */
+    handler: ResolvedHandler;
     sourceFile?: string;
+    select: SelectMode;
+    /** Names of traits this command requires. Empty array = no needs. */
+    needs: string[];
+}
+export type ResolvedHandler = (args: Record<string, unknown>) => Promise<CallToolResult>;
+/** Per-project result shape for multi-target commands. */
+export interface ProjectResult {
+    project: string;
+    ok: boolean;
+    output?: string;
+    error?: string;
+}
+/** Optional reducer for custom multi-target aggregation. */
+export type ReduceFn = (results: ProjectResult[]) => HandlerReturn | Promise<HandlerReturn>;
+export interface RunOptions {
+    order?: "parallel" | "serial";
+    concurrency?: number;
+    stopOnFailure?: boolean;
+    reduce?: ReduceFn;
+}
+/** Internal marker stamped on schemas produced by `fromWorkspace`. */
+export declare const FROM_WORKSPACE: unique symbol;
+/** Marker for invocation-time (args-dependent) schemas — resolved per-call. */
+export declare const FROM_ARGS: unique symbol;
+export interface FromWorkspaceResolver {
+    (ws: IWorkspace): z.ZodType;
+}
+export interface FromArgsResolver {
+    (ws: IWorkspace, args: Record<string, unknown>): z.ZodType;
 }

package/dist/lib/types.js

@@ -1 +1,5 @@
-export {};
+// ---- fromWorkspace marker ----------------------------------------------
+/** Internal marker stamped on schemas produced by `fromWorkspace`. */
+export const FROM_WORKSPACE = Symbol.for("workmark.fromWorkspace");
+/** Marker for invocation-time (args-dependent) schemas — resolved per-call. */
+export const FROM_ARGS = Symbol.for("workmark.fromArgs");

package/dist/lib/workspace.d.ts

@@ -1,11 +1,14 @@
-import type { IProject, IWorkspace } from "./types.js";
+import type { IProject, IWorkspace, Trait } from "./types.js";
+import { TraitRegistry } from "./registry.js";
 export declare class Workspace implements IWorkspace {
     readonly root: string;
     readonly projects: readonly IProject[];
+    /** Trait registry populated during load. Exposed for command-load phase. */
+    readonly traits: TraitRegistry;
     private readonly byName;
-    constructor(root: string, projects: IProject[]);
+    constructor(root: string, projects: IProject[], traits: TraitRegistry);
     get(name: string): IProject;
-    withCapability(cap: string): IProject[];
+    withTrait(trait: Trait | string): IProject[];
     withTag(tag: string): IProject[];
 }
 export declare function loadWorkspace(from?: string): Promise<Workspace>;

package/dist/lib/workspace.js

@@ -2,17 +2,20 @@ 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 { Project, validateHas } from "./project.js";
+import { TraitRegistry, installRegistry, uninstallRegistry } from "./registry.js";
 import { jitiOptions } from "./jiti-options.js";
 export class Workspace {
     root;
     projects;
+    /** Trait registry populated during load. Exposed for command-load phase. */
+    traits;
     byName;
-    constructor(root, projects) {
+    constructor(root, projects, traits) {
         this.root = root;
-        this.projects = Object.freeze(projects);
+        this.projects = Object.freeze([...projects]);
+        this.traits = traits;
         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) {
@@ -28,14 +31,15 @@ export class Workspace {
             throw new Error(`Unknown project: "${name}"`);
         return p;
     }
-    withCapability(cap) {
-        return this.projects.filter((p) => p.has(cap));
+    withTrait(trait) {
+        const name = typeof trait === "string" ? trait : trait.name;
+        return this.projects.filter((p) => p.hasTrait(name));
     }
     withTag(tag) {
         return this.projects.filter((p) => p.tags.includes(tag));
     }
 }
-/** Build an Ignore instance from .gitignore (if present) + hardcoded defaults. */
+// ---- Discovery ---------------------------------------------------------
 function loadIgnore(root) {
     const ig = ignore().add(["node_modules", "dist"]);
     const gitignorePath = join(root, ".gitignore");
@@ -44,7 +48,6 @@ function loadIgnore(root) {
     }
     return ig;
 }
-/** Recursively find all wm.ts files, respecting .gitignore rules. */
 function findWmFiles(root) {
     const ig = loadIgnore(root);
     const results = [];
@@ -63,47 +66,81 @@ function findWmFiles(root) {
     walk(root);
     return results;
 }
-/** Find the workspace root by walking up from cwd looking for .wm/. */
+function findTraitFiles(root) {
+    const traitsDir = join(root, ".wm", "traits");
+    if (!existsSync(traitsDir))
+        return [];
+    const out = [];
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".d.ts")) {
+                out.push(full);
+            }
+        }
+    }
+    walk(traitsDir);
+    return out;
+}
 function findRoot(from) {
     let dir = from;
     while (true) {
-        if (existsSync(join(dir, ".wm"))) {
+        if (existsSync(join(dir, ".wm")))
             return dir;
-        }
         const parent = dirname(dir);
         if (parent === dir)
             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 wm.ts files
-    const wmFiles = findWmFiles(root);
-    // Import each and build Project instances
+// ---- Load --------------------------------------------------------------
+async function loadTraits(root, jiti) {
+    const registry = new TraitRegistry();
+    installRegistry(registry);
+    for (const file of findTraitFiles(root)) {
+        try {
+            await jiti.import(file);
+        }
+        catch (err) {
+            uninstallRegistry();
+            throw new Error(`Failed to import trait file ${file}: ${err.message}`);
+        }
+    }
+    // Registry stays installed — command loading re-executes trait files
+    // under jiti moduleCache:false, and those defineTrait calls need it.
+    return registry;
+}
+async function loadProjects(root, jiti, registry) {
     const projects = [];
-    for (const wmFile of wmFiles) {
+    for (const wmFile of findWmFiles(root)) {
         const dir = dirname(wmFile);
         let exported;
         try {
             exported = await jiti.import(wmFile);
         }
         catch (err) {
-            // Log import failures — helps debug bad wm.ts files
-            console.error(`[workspace] Skipping ${wmFile}: ${err.message}`);
-            continue;
+            throw new Error(`Failed to import ${wmFile}: ${err.message}`);
         }
-        // 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));
+                const def = item;
+                const traitData = validateHas(def, registry, wmFile);
+                projects.push(new Project(def, dir, traitData));
             }
         }
     }
-    return new Workspace(root, projects);
+    return projects;
+}
+export async function loadWorkspace(from) {
+    const root = from ?? process.env.WORKSPACE_ROOT ?? findRoot(process.cwd());
+    const jiti = createJiti(root, jitiOptions());
+    const registry = await loadTraits(root, jiti);
+    const projects = await loadProjects(root, jiti, registry);
+    return new Workspace(root, projects, registry);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldlework/workmark",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "type": "module",
   "main": "dist/lib/load.js",
   "bin": {

package/src/cli.ts

@@ -114,7 +114,13 @@ async function main(): Promise<void> {
   }
 
   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") {
@@ -127,6 +133,6 @@ async function main(): Promise<void> {
 }
 
 main().catch((err) => {
-  console.error("Fatal:", err);
+  process.stderr.write((err instanceof Error ? err.message : String(err)) + "\n");
   process.exit(1);
 });