@ldlework/workmark 1.3.1 → 1.4.1

package/src/lib/parse.ts

@@ -3,12 +3,10 @@
  *
  *   1. tokenize  — turn argv into a structured token stream (flags vs. positionals)
  *   2. dispatch  — bind tokens to parameter names using positional order and
- *                  schema-declared array flags (repeats accumulate)
+ *                  schema-declared array fields (repeats/multiples accumulate)
  *   3. coerce    — convert raw strings to JSON Schema-declared types
  *
- * Each phase is independently testable and has one job. Coercion is driven by
- * the command's JSON Schema rather than heuristics, so `z.string()` fields
- * always stay strings and `z.array(...)` fields always come out as arrays.
+ * Each phase is independently testable and has one job.
  */
 
 type Token =
@@ -19,6 +17,7 @@ type SchemaProp = {
   type?: string;
   items?: { type?: string; enum?: unknown[] };
   enum?: unknown[];
+  anyOf?: unknown[];
 };
 
 type SchemaObject = {
@@ -57,7 +56,16 @@ function tokenize(argv: string[]): Token[] {
 // --- 2. dispatch ---------------------------------------------------------
 
 function isArrayField(schema: SchemaObject, name: string): boolean {
-  return schema.properties?.[name]?.type === "array";
+  const prop = schema.properties?.[name];
+  if (!prop) return false;
+  if (prop.type === "array") return true;
+  // union: accept array as one option
+  if (Array.isArray(prop.anyOf)) {
+    for (const alt of prop.anyOf) {
+      if ((alt as SchemaProp).type === "array") return true;
+    }
+  }
+  return false;
 }
 
 function appendToArray(out: Record<string, unknown>, key: string, value: string): void {
@@ -82,6 +90,19 @@ function assignFlag(
   out[key] = value;
 }
 
+function assignPositional(
+  out: Record<string, unknown>,
+  schema: SchemaObject,
+  key: string,
+  value: string,
+): void {
+  if (isArrayField(schema, key)) {
+    appendToArray(out, key, value);
+    return;
+  }
+  out[key] = value;
+}
+
 function dispatch(
   tokens: Token[],
   positional: string[],
@@ -93,10 +114,16 @@ function dispatch(
   for (const tok of tokens) {
     if (tok.kind === "flag") {
       assignFlag(out, schema, tok.key, tok.value);
-    } else if (posIdx < positional.length) {
-      out[positional[posIdx]] = tok.value;
-      posIdx++;
+      continue;
     }
+
+    if (posIdx >= positional.length) continue;
+
+    const currentKey = positional[posIdx];
+    assignPositional(out, schema, currentKey, tok.value);
+
+    // If the current positional is array-valued, stay on it; else advance.
+    if (!isArrayField(schema, currentKey)) posIdx++;
   }
   return out;
 }
@@ -123,14 +150,24 @@ function coerceField(value: unknown, prop: SchemaProp | undefined): unknown {
   if (prop === undefined) return value;
   if (typeof value === "boolean") return value;
 
-  if (prop.type === "array") {
+  if (prop.type === "array" || (Array.isArray(prop.anyOf) && prop.anyOf.some((a) => (a as SchemaProp).type === "array"))) {
     const items = Array.isArray(value) ? value : [value];
-    return items.map((item) => coerceScalar(String(item), prop.items?.type));
+    const innerType = prop.items?.type ?? extractArrayItemType(prop);
+    return items.map((item) => coerceScalar(String(item), innerType));
   }
 
   return coerceScalar(String(value), prop.type);
 }
 
+function extractArrayItemType(prop: SchemaProp): string | undefined {
+  if (!Array.isArray(prop.anyOf)) return undefined;
+  for (const alt of prop.anyOf) {
+    const a = alt as SchemaProp;
+    if (a.type === "array") return a.items?.type;
+  }
+  return undefined;
+}
+
 function coerce(
   raw: Record<string, unknown>,
   schema: SchemaObject,

package/src/lib/project.ts

@@ -1,32 +1,39 @@
 import { join } from "node:path";
-import type { IProject, ProjectDef } from "./types.js";
+import type { IProject, ProjectDef, Trait } from "./types.js";
+import type { TraitRegistry } from "./registry.js";
 
 export class Project implements IProject {
   readonly name: string;
   readonly dir: string;
   readonly tags: readonly string[];
-  readonly capabilities: Readonly<Record<string, true | Record<string, unknown>>>;
+  readonly description?: string;
 
+  /** Parsed (defaulted) trait data, keyed by trait name. */
+  private readonly traitData: Readonly<Record<string, unknown>>;
   private readonly paths: Readonly<Record<string, string>>;
 
-  constructor(def: ProjectDef, wsDir: string) {
+  constructor(def: ProjectDef, wsDir: string, traitData: Record<string, unknown>) {
     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: string): boolean {
-    return capability in this.capabilities;
+  hasTrait(trait: Trait | string): boolean {
+    const name = typeof trait === "string" ? trait : trait.name;
+    return name in this.traitData;
   }
 
-  capability<T = true | Record<string, unknown>>(name: string): T {
-    const cap = this.capabilities[name];
-    if (cap === undefined) {
-      throw new Error(`Project "${this.name}" does not have capability "${name}"`);
+  trait<T>(trait: Trait<string, T>): T {
+    const data = this.traitData[trait.name];
+    if (data === undefined) {
+      throw new Error(
+        `Project "${this.name}" does not fulfill trait "${trait.name}"`,
+      );
     }
-    return cap as T;
+    return data as T;
   }
 
   path(name: string): string {
@@ -37,3 +44,41 @@ export class Project implements IProject {
     return join(this.dir, rel);
   }
 }
+
+/** Validate a project's `has` against the registry, returning parsed data. */
+export function validateHas(
+  def: ProjectDef,
+  registry: TraitRegistry,
+  sourceFile: string,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  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/src/lib/registry.ts

@@ -0,0 +1,80 @@
+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 class TraitRegistry {
+  private readonly traits = new Map<string, Trait>();
+  private readonly sources = new Map<string, string>();
+
+  register(trait: Trait, sourceFile?: string): void {
+    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: string): Trait | undefined {
+    return this.traits.get(name);
+  }
+
+  require(name: string): Trait {
+    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: string): boolean {
+    return this.traits.has(name);
+  }
+
+  all(): readonly Trait[] {
+    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");
+type GlobalSlot = { [K in typeof GLOBAL_KEY]?: TraitRegistry };
+
+function slot(): GlobalSlot {
+  return globalThis as unknown as GlobalSlot;
+}
+
+export function installRegistry(reg: TraitRegistry): void {
+  slot()[GLOBAL_KEY] = reg;
+}
+
+export function uninstallRegistry(): void {
+  delete slot()[GLOBAL_KEY];
+}
+
+export function registerAmbient(trait: Trait, sourceFile?: string): void {
+  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/src/lib/types.ts

@@ -1,37 +1,58 @@
 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>;
+// ---- Traits ------------------------------------------------------------
 
-/** 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];
+}
+
+// ---- Schema fields ------------------------------------------------------
+
+/** 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>;
 
-// ---- Project definitions (used in wm.ts files) ----
+// ---- Projects -----------------------------------------------------------
 
 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;
 }
 
-// ---- Runtime project/workspace interfaces ----
-
 export interface IProject {
   readonly name: string;
   readonly dir: string;
   readonly tags: readonly string[];
-  readonly capabilities: Readonly<Record<string, true | Record<string, unknown>>>;
+  readonly description?: string;
 
-  has(capability: string): boolean;
-  capability<T = true | Record<string, unknown>>(name: string): T;
+  /** 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;
 }
 
@@ -40,50 +61,87 @@ export interface IWorkspace {
   readonly projects: readonly IProject[];
 
   get(name: string): IProject;
-  withCapability(cap: string): IProject[];
+  withTrait(trait: Trait | string): IProject[];
   withTag(tag: string): IProject[];
 }
 
-// ---- Command definitions ----
+// ---- Commands -----------------------------------------------------------
 
-export type ToolHandler = (
-  args: Record<string, unknown>,
-) => Promise<CallToolResult>;
+/** How many projects a command runs against. */
+export type SelectMode = "one" | "one-or-many" | "all";
 
-export interface StaticCommandDef {
-  name: string;
-  label: string;
-  description: string;
-  /** Positional arguments (order = key order). */
-  args?: SchemaFields;
-  /** Named flags (--key value). */
-  flags?: SchemaFields;
-  handler: ToolHandler;
+/** 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>;
+
+// ---- Result aggregation -------------------------------------------------
+
+/** 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;
+}
+
+// ---- 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");
+
+export interface FromWorkspaceResolver {
+  (ws: IWorkspace): z.ZodType;
+}
+
+export interface FromArgsResolver {
+  (ws: IWorkspace, args: Record<string, unknown>): z.ZodType;
 }

package/src/lib/workspace.ts

@@ -2,22 +2,25 @@ import { dirname, join, relative } from "node:path";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { createJiti } from "jiti";
 import ignore, { type Ignore } from "ignore";
-import { Project } from "./project.js";
-import type { IProject, IWorkspace, ProjectDef } from "./types.js";
+import { Project, validateHas } from "./project.js";
+import type { IProject, IWorkspace, ProjectDef, Trait } from "./types.js";
+import { TraitRegistry, installRegistry, uninstallRegistry } from "./registry.js";
 import { jitiOptions } from "./jiti-options.js";
 
 export 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: Map<string, IProject>;
 
-  constructor(root: string, projects: IProject[]) {
+  constructor(root: string, projects: IProject[], traits: TraitRegistry) {
     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<string>();
       for (const p of projects) {
@@ -33,8 +36,9 @@ export class Workspace implements IWorkspace {
     return p;
   }
 
-  withCapability(cap: string): IProject[] {
-    return this.projects.filter((p) => p.has(cap));
+  withTrait(trait: Trait | string): IProject[] {
+    const name = typeof trait === "string" ? trait : trait.name;
+    return this.projects.filter((p) => p.hasTrait(name));
   }
 
   withTag(tag: string): IProject[] {
@@ -42,7 +46,8 @@ export class Workspace implements IWorkspace {
   }
 }
 
-/** Build an Ignore instance from .gitignore (if present) + hardcoded defaults. */
+// ---- Discovery ---------------------------------------------------------
+
 function loadIgnore(root: string): Ignore {
   const ig = ignore().add(["node_modules", "dist"]);
   const gitignorePath = join(root, ".gitignore");
@@ -52,7 +57,6 @@ function loadIgnore(root: string): Ignore {
   return ig;
 }
 
-/** Recursively find all wm.ts files, respecting .gitignore rules. */
 function findWmFiles(root: string): string[] {
   const ig = loadIgnore(root);
   const results: string[] = [];
@@ -72,53 +76,86 @@ function findWmFiles(root: string): string[] {
   return results;
 }
 
-/** Find the workspace root by walking up from cwd looking for .wm/. */
+function findTraitFiles(root: string): string[] {
+  const traitsDir = join(root, ".wm", "traits");
+  if (!existsSync(traitsDir)) return [];
+  const out: string[] = [];
+  function walk(dir: string): void {
+    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: string): string {
   let dir = from;
   while (true) {
-    if (existsSync(join(dir, ".wm"))) {
-      return dir;
-    }
+    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?: string): Promise<Workspace> {
-  const root = from ?? process.env.WORKSPACE_ROOT ?? findRoot(process.cwd());
-  const jiti = createJiti(root, jitiOptions());
+// ---- Load --------------------------------------------------------------
 
-  // Recursively find all wm.ts files
-  const wmFiles = findWmFiles(root);
+async function loadTraits(root: string, jiti: ReturnType<typeof createJiti>): Promise<TraitRegistry> {
+  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 as Error).message}`);
+    }
+  }
+  // Registry stays installed — command loading re-executes trait files
+  // under jiti moduleCache:false, and those defineTrait calls need it.
+  return registry;
+}
 
-  // Import each and build Project instances
+async function loadProjects(
+  root: string,
+  jiti: ReturnType<typeof createJiti>,
+  registry: TraitRegistry,
+): Promise<Project[]> {
   const projects: Project[] = [];
-
-  for (const wmFile of wmFiles) {
+  for (const wmFile of findWmFiles(root)) {
     const dir = dirname(wmFile);
     let exported: unknown;
     try {
       exported = await jiti.import(wmFile);
     } catch (err) {
-      // Log import failures — helps debug bad wm.ts files
-      console.error(`[workspace] Skipping ${wmFile}: ${(err as Error).message}`);
-      continue;
+      throw new Error(`Failed to import ${wmFile}: ${(err as Error).message}`);
     }
-
-    // jiti may return { default: ... } when interopDefault doesn't fully unwrap
     if (exported && typeof exported === "object" && "default" in (exported as Record<string, unknown>)) {
       exported = (exported as Record<string, unknown>).default;
     }
-
     const items: unknown[] = Array.isArray(exported) ? exported : [exported];
-
     for (const item of items) {
       if (item && typeof item === "object" && typeof (item as Record<string, unknown>).name === "string") {
-        projects.push(new Project(item as ProjectDef, dir));
+        const def = item as ProjectDef;
+        const traitData = validateHas(def, registry, wmFile);
+        projects.push(new Project(def, dir, traitData));
       }
     }
   }
+  return projects;
+}
+
+export async function loadWorkspace(from?: string): Promise<Workspace> {
+  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);
+  return new Workspace(root, projects, registry);
 }