@ldlework/workmark 1.3.1 → 1.4.1

package/dist/lib/load.js

@@ -1,23 +1,140 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
 import { createJiti } from "jiti";
 import { z } from "zod";
+import { execAsync, ok, fail, shSeq } from "./helpers.js";
+import { FROM_ARGS, FROM_WORKSPACE } from "./types.js";
 import { jitiOptions } from "./jiti-options.js";
-/** Title-case a folder name: "docker" → "Docker" */
+// --- Metadata derivation -------------------------------------------------
 function titleCase(s) {
-    return s.charAt(0).toUpperCase() + s.slice(1);
+    return s
+        .split(/[_\s-]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
 }
-function isStatic(def) {
-    return "handler" in def;
+function extractLeadingJsDoc(source) {
+    const exportIdx = source.indexOf("export default");
+    const before = exportIdx < 0 ? source : source.slice(0, exportIdx);
+    const blocks = [...before.matchAll(/\/\*\*([\s\S]*?)\*\//g)];
+    if (blocks.length === 0)
+        return undefined;
+    const last = blocks[blocks.length - 1][1];
+    return last
+        .split("\n")
+        .map((line) => line.replace(/^\s*\*\s?/, "").trimEnd())
+        .join(" ")
+        .trim() || undefined;
 }
-/** Convert a single field (Zod or raw JSON Schema property) to a JSON Schema property. */
+function deriveMetadata(def, sourceFile) {
+    const filenameName = basename(sourceFile, extname(sourceFile));
+    const meta = def.meta ?? {};
+    const name = meta.name ?? filenameName;
+    const label = meta.label ?? titleCase(name);
+    const description = meta.description ?? extractLeadingJsDoc(readFileSync(sourceFile, "utf-8")) ?? "";
+    return { name, label, description };
+}
+/** Detect whether a schema (or any of its wrappers) carries a FROM_ARGS marker.
+ * Such fields are resolved at invocation time, not load time. */
+function hasFromArgs(field) {
+    if (!(field instanceof z.ZodType))
+        return false;
+    return walkForFromArgs(field);
+}
+function walkForFromArgs(node) {
+    if (node[FROM_ARGS])
+        return true;
+    if (node instanceof z.ZodOptional)
+        return walkForFromArgs(node.unwrap());
+    if (node instanceof z.ZodNullable)
+        return walkForFromArgs(node.unwrap());
+    if (node instanceof z.ZodDefault)
+        return walkForFromArgs(node.unwrap());
+    if (node instanceof z.ZodArray)
+        return walkForFromArgs(node.element);
+    return false;
+}
+function resolveFromWorkspace(field, ws) {
+    if (!(field instanceof z.ZodType))
+        return field;
+    return walk(field, ws);
+}
+function walk(node, ws) {
+    // Leave FROM_ARGS markers alone — they resolve per-invocation.
+    if (node[FROM_ARGS])
+        return node;
+    const marked = node[FROM_WORKSPACE];
+    if (marked)
+        return marked(ws);
+    if (node instanceof z.ZodOptional)
+        return walk(node.unwrap(), ws).optional();
+    if (node instanceof z.ZodNullable)
+        return walk(node.unwrap(), ws).nullable();
+    if (node instanceof z.ZodDefault) {
+        const def = node._def.defaultValue;
+        return walk(node.unwrap(), ws).default(def);
+    }
+    if (node instanceof z.ZodArray) {
+        return z.array(walk(node.element, ws));
+    }
+    return node;
+}
+function resolveFields(fields, ws) {
+    if (!fields)
+        return fields;
+    const out = {};
+    for (const [k, v] of Object.entries(fields)) {
+        out[k] = resolveFromWorkspace(v, ws);
+    }
+    return out;
+}
+/** Resolve FROM_ARGS markers in a walked schema tree against a specific args object. */
+function walkWithArgs(node, ws, args) {
+    const marked = node[FROM_ARGS];
+    if (marked)
+        return marked(ws, args);
+    if (node instanceof z.ZodOptional)
+        return walkWithArgs(node.unwrap(), ws, args).optional();
+    if (node instanceof z.ZodNullable)
+        return walkWithArgs(node.unwrap(), ws, args).nullable();
+    if (node instanceof z.ZodDefault) {
+        const def = node._def.defaultValue;
+        return walkWithArgs(node.unwrap(), ws, args).default(def);
+    }
+    if (node instanceof z.ZodArray) {
+        return z.array(walkWithArgs(node.element, ws, args));
+    }
+    return node;
+}
+/** Per-invocation: validate any FROM_ARGS fields against the resolved schema.
+ * Returns the parsed args (with fromArgs fields replaced by validated values). */
+function validateFromArgsFields(args, fromArgsFields, ws) {
+    if (fromArgsFields.length === 0)
+        return args;
+    const out = { ...args };
+    for (const { name, schema } of fromArgsFields) {
+        const resolved = walkWithArgs(schema, ws, args);
+        const raw = args[name];
+        if (raw === undefined)
+            continue;
+        const result = resolved.safeParse(raw);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`)
+                .join("\n");
+            throw new Error(`Field "${name}" failed validation:\n${issues}`);
+        }
+        out[name] = result.data;
+    }
+    return out;
+}
+// --- Schema merging + project-arg synthesis ------------------------------
 function fieldToJsonSchema(field) {
     if (field instanceof z.ZodType) {
         return z.toJSONSchema(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;
@@ -25,15 +142,44 @@ function isRequired(field, schema) {
         return false;
     return true;
 }
-/** Merge args + flags into a single JSON Schema object and return positional names. */
-function mergeSchemas(args, flags) {
+function projectArgFor(needs, select, workspace) {
+    if (needs.length === 0)
+        return null;
+    if (select === "all")
+        return null; // framework selects; no user input
+    const eligible = workspace.projects
+        .filter((p) => needs.every((t) => p.hasTrait(t)))
+        .map((p) => p.name);
+    if (eligible.length === 0) {
+        const traits = needs.map((t) => t.name).join(", ");
+        throw new Error(`Command requires needs [${traits}] but no projects fulfill all of them`);
+    }
+    const enum_ = z.enum(eligible);
+    if (select === "one-or-many") {
+        // accept string or array; we'll coerce at parse time
+        return { schema: z.union([enum_, z.array(enum_)]), required: false, eligible };
+    }
+    return { schema: enum_, required: true, eligible };
+}
+function buildSchema(args, flags, projectArg) {
     const properties = {};
     const required = [];
     const positional = [];
-    const collect = (source, isPositional) => {
-        if (!source)
+    let projectArgName = null;
+    if (projectArg) {
+        projectArgName = "project";
+        properties.project = fieldToJsonSchema(projectArg.schema);
+        positional.push("project");
+        if (projectArg.required)
+            required.push("project");
+    }
+    const collect = (src, isPositional) => {
+        if (!src)
             return;
-        for (const [name, field] of Object.entries(source)) {
+        for (const [name, field] of Object.entries(src)) {
+            if (name === "project" && projectArgName) {
+                throw new Error(`Field "project" collides with framework-injected ctx.project.\n  hint: rename the field; ctx.project is always present under needs`);
+            }
             const schema = fieldToJsonSchema(field);
             properties[name] = schema;
             if (isPositional)
@@ -44,32 +190,245 @@ function mergeSchemas(args, flags) {
     };
     collect(args, true);
     collect(flags, false);
-    const inputSchema = {
-        type: "object",
-        properties,
-    };
-    if (required.length > 0) {
+    const inputSchema = { type: "object", properties };
+    if (required.length > 0)
         inputSchema.required = required;
+    return { inputSchema, positional, projectArgName };
+}
+function makeBaseCtx(ws, cwdResolver, host) {
+    return {
+        workspace: ws,
+        ok,
+        fail,
+        sh: (cmd, opts) => {
+            const options = { cwd: cwdResolver(), timeout: opts?.timeout, env: opts?.env };
+            return Array.isArray(cmd)
+                ? shSeq(cmd, options)
+                : execAsync(cmd, options);
+        },
+        exec: (cmd, opts) => execAsync(cmd, opts),
+        invoke: host.invoke,
+    };
+}
+function makeNeedsCtx(ws, project, needs, host) {
+    const traits = {};
+    for (const t of needs)
+        traits[t.name] = project.trait(t);
+    return {
+        ...makeBaseCtx(ws, () => project.dir, host),
+        project,
+        traits,
+    };
+}
+// --- Handler wrapping ----------------------------------------------------
+function stripProjectArg(args) {
+    const { project: _drop, ...rest } = args;
+    return rest;
+}
+function isCallToolResult(v) {
+    return typeof v === "object" && v !== null && "content" in v;
+}
+async function runHandler(raw, args, ctx) {
+    try {
+        const out = await raw(args, ctx);
+        if (isCallToolResult(out))
+            return out;
+        return { content: [{ type: "text", text: String(out) }] };
+    }
+    catch (e) {
+        return fail(e);
+    }
+}
+function resolveProjects(needs, select, workspace, argsValue) {
+    const eligible = workspace.projects.filter((p) => needs.every((t) => p.hasTrait(t)));
+    const eligibleList = eligible.map((p) => p.name).join(", ");
+    const traitList = needs.map((t) => t.name).join(", ");
+    if (select === "all")
+        return eligible;
+    const names = Array.isArray(argsValue)
+        ? argsValue
+        : typeof argsValue === "string"
+            ? [argsValue]
+            : [];
+    if (names.length === 0) {
+        if (select === "one") {
+            throw new Error(`Missing project argument.\n  needs: [${traitList}]\n  eligible: ${eligibleList}`);
+        }
+        throw new Error(`Missing project argument — select "${select}" requires 1+ project names.\n  needs: [${traitList}]\n  eligible: ${eligibleList}`);
     }
-    return { inputSchema, positional };
+    const resolved = [];
+    for (const n of names) {
+        let p;
+        try {
+            p = workspace.get(n);
+        }
+        catch {
+            throw new Error(`Unknown project "${n}".\n  available: ${workspace.projects.map((p) => p.name).join(", ")}\n  eligible for this command: ${eligibleList}`);
+        }
+        const missing = needs.filter((t) => !p.hasTrait(t)).map((t) => t.name);
+        if (missing.length > 0) {
+            throw new Error(`Project "${p.name}" does not fulfill required trait(s) [${missing.join(", ")}].\n  eligible projects: ${eligibleList}`);
+        }
+        resolved.push(p);
+    }
+    return resolved;
 }
-function resolve(def, workspace, group, sourceFile) {
-    let args;
-    let flags;
-    let handler;
-    if (isStatic(def)) {
-        args = def.args;
-        flags = def.flags;
-        handler = def.handler;
+async function runMultiple(raw, args, projects, needs, workspace, run, host) {
+    const callerArgs = stripProjectArg(args);
+    const runOne = async (p) => {
+        const ctx = makeNeedsCtx(workspace, p, needs, host);
+        const res = await runHandler(raw, callerArgs, ctx);
+        const text = res.content.map((c) => (c.type === "text" ? c.text : "")).join("\n");
+        return { project: p.name, ok: !res.isError, output: text, error: res.isError ? text : undefined };
+    };
+    // serial when requested; otherwise parallel with concurrency cap
+    const serial = run?.order === "serial";
+    const concurrency = serial ? 1 : (run?.concurrency ?? 4);
+    const results = new Array(projects.length);
+    let idx = 0;
+    const workers = Array.from({ length: Math.min(concurrency, projects.length) }, async () => {
+        while (true) {
+            const i = idx++;
+            if (i >= projects.length)
+                return;
+            results[i] = await runOne(projects[i]);
+            if (run?.stopOnFailure && !results[i].ok) {
+                idx = projects.length;
+                return;
+            }
+        }
+    });
+    await Promise.all(workers);
+    const realResults = results.filter(Boolean);
+    if (run?.reduce) {
+        return run.reduce(realResults);
     }
-    else {
-        const result = def.factory(workspace);
-        args = result.args;
-        flags = result.flags;
-        handler = result.handler;
+    // default aggregation — if only one ran, return its output directly
+    if (realResults.length === 1) {
+        const r = realResults[0];
+        return r.ok ? ok(r.output ?? "") : fail(r.error ?? r.output ?? "");
     }
-    const { inputSchema, positional } = mergeSchemas(args, flags);
-    return { name: def.name, label: def.label, group, description: def.description, inputSchema, positional, handler, sourceFile };
+    const parts = [];
+    let anyError = false;
+    for (const r of realResults) {
+        parts.push(`--- ${r.project} ---\n${r.output ?? ""}`);
+        if (!r.ok)
+            anyError = true;
+    }
+    const text = parts.join("\n\n");
+    return anyError ? fail(text) : ok(text);
+}
+// --- Main resolve --------------------------------------------------------
+function collectFromArgsFields(fields) {
+    const out = [];
+    if (!fields)
+        return out;
+    for (const [name, field] of Object.entries(fields)) {
+        if (field instanceof z.ZodType && hasFromArgs(field))
+            out.push({ name, schema: field });
+    }
+    return out;
+}
+function resolve(def, workspace, group, sourceFile, host) {
+    const meta = deriveMetadata(def, sourceFile);
+    const rawNeeds = def.needs ?? [];
+    const needs = rawNeeds.map((t) => typeof t === "string" ? workspace.traits.require(t) : t);
+    const select = def.select ?? (needs.length > 0 ? "one-or-many" : "one");
+    if (needs.length === 0 && select !== "one") {
+        throw new Error(`Command "${meta.name}": select requires needs (at ${sourceFile})`);
+    }
+    // `for` binds this command to a named project. No project arg is exposed on
+    // any surface; ctx.project is the bound project.
+    let boundProject = null;
+    if (def.for !== undefined) {
+        if (needs.length === 0) {
+            throw new Error(`Command "${meta.name}": \`for\` requires \`needs\` (a fixed project without required traits is meaningless)\n  at ${sourceFile}`);
+        }
+        try {
+            boundProject = workspace.get(def.for);
+        }
+        catch {
+            throw new Error(`Command "${meta.name}": \`for: "${def.for}"\` — project not found\n  at ${sourceFile}\n  available: ${workspace.projects.map(p => p.name).join(", ")}`);
+        }
+        for (const t of needs) {
+            if (!boundProject.hasTrait(t)) {
+                throw new Error(`Command "${meta.name}": bound project "${def.for}" does not fulfill trait "${t.name}"\n  at ${sourceFile}`);
+            }
+        }
+    }
+    const resolvedArgs = resolveFields(def.args, workspace);
+    const resolvedFlags = resolveFields(def.flags, workspace);
+    // Collect invocation-time-resolved fields for per-call validation.
+    const fromArgsFields = [
+        ...collectFromArgsFields(resolvedArgs),
+        ...collectFromArgsFields(resolvedFlags),
+    ];
+    // `for` suppresses the user-facing project arg.
+    const projectArg = boundProject ? null : projectArgFor(needs, select, workspace);
+    const { inputSchema, positional } = buildSchema(resolvedArgs, resolvedFlags, projectArg);
+    const handler = async (args) => {
+        const validated = validateFromArgsFields(args, fromArgsFields, workspace);
+        if (needs.length === 0) {
+            const ctx = makeBaseCtx(workspace, () => workspace.root, host);
+            return runHandler(def.handler, validated, ctx);
+        }
+        if (boundProject) {
+            const ctx = makeNeedsCtx(workspace, boundProject, needs, host);
+            return runHandler(def.handler, validated, ctx);
+        }
+        const projects = resolveProjects(needs, select, workspace, validated.project);
+        if (select === "one") {
+            const ctx = makeNeedsCtx(workspace, projects[0], needs, host);
+            return runHandler(def.handler, stripProjectArg(validated), ctx);
+        }
+        return runMultiple(def.handler, validated, projects, needs, workspace, def.run, host);
+    };
+    return {
+        name: meta.name,
+        label: meta.label,
+        group,
+        description: meta.description,
+        inputSchema,
+        positional,
+        handler,
+        sourceFile,
+        select,
+        needs: needs.map((t) => t.name),
+    };
+}
+// --- Discovery -----------------------------------------------------------
+async function importCommand(jiti, filePath) {
+    const mod = (await jiti.import(filePath));
+    return mod.default;
+}
+function isCommandFile(name) {
+    return name.endsWith(".ts") && !name.endsWith(".d.ts");
+}
+/** Walk the commands dir recursively. Maps paths to colon-joined command names. */
+function walkCommands(root) {
+    const out = [];
+    function walk(dir, prefix) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full, [...prefix, entry.name]);
+            }
+            else if (isCommandFile(entry.name)) {
+                const base = entry.name.replace(/\.ts$/, "");
+                if (base.includes(":")) {
+                    throw new Error(`Command filename contains ':' which is reserved: ${full}`);
+                }
+                const parts = base === "index" ? prefix : [...prefix, base];
+                if (parts.length === 0)
+                    continue; // bare root index.ts not allowed
+                const resolvedName = parts.join(":");
+                const group = prefix.length > 0 ? titleCase(prefix[0]) : "";
+                out.push({ filePath: full, resolvedName, group });
+            }
+        }
+    }
+    walk(root, []);
+    return out;
 }
 export async function loadCommands(workspace) {
     const commandsDir = join(workspace.root, ".wm", "commands");
@@ -77,29 +436,43 @@ export async function loadCommands(workspace) {
         return [];
     const jiti = createJiti(commandsDir, jitiOptions());
     const commands = [];
-    // Ungrouped (root-level) commands first
-    for (const entry of readdirSync(commandsDir)) {
-        const entryPath = join(commandsDir, entry);
-        const stat = statSync(entryPath);
-        if (!stat.isDirectory() && entry.endsWith(".ts") && !entry.endsWith(".d.ts")) {
-            const mod = await jiti.import(entryPath);
-            commands.push(resolve(mod.default, workspace, "", entryPath));
-        }
-    }
-    // Grouped commands (subdirectories)
-    for (const entry of readdirSync(commandsDir)) {
-        const entryPath = join(commandsDir, entry);
-        const stat = statSync(entryPath);
-        if (stat.isDirectory()) {
-            const group = titleCase(entry);
-            for (const file of readdirSync(entryPath)) {
-                if (!file.endsWith(".ts") || file.endsWith(".d.ts"))
-                    continue;
-                const filePath = join(entryPath, file);
-                const mod = await jiti.import(filePath);
-                commands.push(resolve(mod.default, workspace, group, filePath));
+    const byName = new Map();
+    // Invocation host: commands map is populated progressively; cycle-detected per-call.
+    const activeStack = new Set();
+    const host = {
+        invoke: async (name, args) => {
+            if (activeStack.has(name)) {
+                const trace = [...activeStack, name].join(" → ");
+                return fail(`Cyclic invocation: ${trace}`);
+            }
+            const target = byName.get(name);
+            if (!target)
+                return fail(`Unknown command: "${name}"`);
+            activeStack.add(name);
+            try {
+                return await target.handler(args);
             }
+            finally {
+                activeStack.delete(name);
+            }
+        },
+    };
+    const discovered = walkCommands(commandsDir);
+    for (const d of discovered) {
+        const def = await importCommand(jiti, d.filePath);
+        if (!def)
+            continue;
+        const cmd = resolve(def, workspace, d.group, d.filePath, host);
+        // Override resolved name from path-derived name (filename was the fallback in meta).
+        // Meta.name wins if explicitly set; otherwise use the discovered name.
+        const userProvidedName = def.meta?.name;
+        if (!userProvidedName)
+            cmd.name = d.resolvedName;
+        if (byName.has(cmd.name)) {
+            throw new Error(`Duplicate command name "${cmd.name}": ${d.filePath} collides with ${byName.get(cmd.name).sourceFile}`);
         }
+        byName.set(cmd.name, cmd);
+        commands.push(cmd);
     }
     return commands;
 }

package/dist/lib/parse.d.ts

@@ -3,11 +3,9 @@
  *
  *   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.
  */
 export declare function parseArgs(argv: string[], positional: string[], schema: Record<string, unknown>): Record<string, unknown>;

package/dist/lib/parse.js

@@ -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.
  */
 // --- 1. tokenize ---------------------------------------------------------
 function tokenize(argv) {
@@ -38,7 +36,19 @@ function tokenize(argv) {
 }
 // --- 2. dispatch ---------------------------------------------------------
 function isArrayField(schema, name) {
-    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.type === "array")
+                return true;
+        }
+    }
+    return false;
 }
 function appendToArray(out, key, value) {
     const prev = out[key];
@@ -55,17 +65,28 @@ function assignFlag(out, schema, key, value) {
     }
     out[key] = value;
 }
+function assignPositional(out, schema, key, value) {
+    if (isArrayField(schema, key)) {
+        appendToArray(out, key, value);
+        return;
+    }
+    out[key] = value;
+}
 function dispatch(tokens, positional, schema) {
     const out = {};
     let posIdx = 0;
     for (const tok of tokens) {
         if (tok.kind === "flag") {
             assignFlag(out, schema, tok.key, tok.value);
+            continue;
         }
-        else if (posIdx < positional.length) {
-            out[positional[posIdx]] = tok.value;
+        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;
 }
@@ -92,12 +113,23 @@ function coerceField(value, prop) {
         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.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) {
+    if (!Array.isArray(prop.anyOf))
+        return undefined;
+    for (const alt of prop.anyOf) {
+        const a = alt;
+        if (a.type === "array")
+            return a.items?.type;
+    }
+    return undefined;
+}
 function coerce(raw, schema) {
     const out = {};
     const props = schema.properties ?? {};

package/dist/lib/project.d.ts

@@ -1,12 +1,17 @@
-import type { IProject, ProjectDef } from "./types.js";
+import type { IProject, ProjectDef, Trait } from "./types.js";
+import type { TraitRegistry } from "./registry.js";
 export declare 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;
     private readonly paths;
-    constructor(def: ProjectDef, wsDir: string);
-    has(capability: string): boolean;
-    capability<T = true | Record<string, unknown>>(name: string): T;
+    constructor(def: ProjectDef, wsDir: string, traitData: Record<string, unknown>);
+    hasTrait(trait: Trait | string): boolean;
+    trait<T>(trait: Trait<string, T>): T;
     path(name: string): string;
 }
+/** Validate a project's `has` against the registry, returning parsed data. */
+export declare function validateHas(def: ProjectDef, registry: TraitRegistry, sourceFile: string): Record<string, unknown>;