@clawmasons/shared 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { appChapterFieldSchema, type AppChapterField, skillChapterFieldSchema, type SkillChapterField, taskChapterFieldSchema, type TaskChapterField, roleChapterFieldSchema, type RoleChapterField, parseChapterField, type ChapterField, } from "./schemas/index.js";
+export { toolPermissionsSchema, roleMetadataSchema, taskRefSchema, skillRefSchema, appConfigSchema, mountConfigSchema, containerRequirementsSchema, governanceConfigSchema, resourceFileSchema, roleSourceSchema, roleSchema, } from "./schemas/index.js";
+export type { Role, RoleMetadata, TaskRef, AppConfig, SkillRef, ContainerRequirements, GovernanceConfig, ResourceFile, RoleSource, MountConfig, ToolPermissions, } from "./types/role.js";
+export type { DiscoveredPackage, ResolvedAgent, ResolvedApp, ResolvedRole, ResolvedSkill, ResolvedTask, } from "./types.js";
+export { computeToolFilters, getAppShortName, type ToolFilter, } from "./toolfilter.js";
+export { registerDialect, getDialect, getDialectByDirectory, getAllDialects, getKnownDirectories, type DialectEntry, type DialectFieldMapping, readMaterializedRole, parseFrontmatter, detectDialect, RoleParseError, scanBundledResources, readPackagedRole, PackageReadError, adaptRoleToResolvedAgent, AdapterError, discoverRoles, resolveRole, RoleDiscoveryError, } from "./role/index.js";
+export { scanProject, type ScanResult, type DiscoveredSkill, type DiscoveredCommand, type DiscoveredMcpServer, proposeRoleMd, type ProposeOptions, } from "./mason/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,iBAAiB,EACjB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,2BAA2B,EAC3B,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,GACX,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,SAAS,EACT,QAAQ,EACR,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,KAAK,UAAU,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,WAAW,EACX,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,aAAa,EACb,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// Schemas
+export { appChapterFieldSchema, skillChapterFieldSchema, taskChapterFieldSchema, roleChapterFieldSchema, parseChapterField, } from "./schemas/index.js";
+// ROLE_TYPES schemas
+export { toolPermissionsSchema, roleMetadataSchema, taskRefSchema, skillRefSchema, appConfigSchema, mountConfigSchema, containerRequirementsSchema, governanceConfigSchema, resourceFileSchema, roleSourceSchema, roleSchema, } from "./schemas/index.js";
+// Tool filtering
+export { computeToolFilters, getAppShortName, } from "./toolfilter.js";
+// Role module (dialect registry, parser, resource scanner)
+export { registerDialect, getDialect, getDialectByDirectory, getAllDialects, getKnownDirectories, readMaterializedRole, parseFrontmatter, detectDialect, RoleParseError, scanBundledResources, readPackagedRole, PackageReadError, adaptRoleToResolvedAgent, AdapterError, discoverRoles, resolveRole, RoleDiscoveryError, } from "./role/index.js";
+// Mason module (project scanner, ROLE.md proposer)
+export { scanProject, proposeRoleMd, } from "./mason/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,OAAO,EACL,qBAAqB,EAErB,uBAAuB,EAEvB,sBAAsB,EAEtB,sBAAsB,EAEtB,iBAAiB,GAElB,MAAM,oBAAoB,CAAC;AAE5B,qBAAqB;AACrB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,2BAA2B,EAC3B,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,GACX,MAAM,oBAAoB,CAAC;AA2B5B,iBAAiB;AACjB,OAAO,EACL,kBAAkB,EAClB,eAAe,GAEhB,MAAM,iBAAiB,CAAC;AAEzB,2DAA2D;AAC3D,OAAO,EACL,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EAGnB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAEzB,mDAAmD;AACnD,OAAO,EACL,WAAW,EAKX,aAAa,GAEd,MAAM,kBAAkB,CAAC"}

package/dist/role/adapter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Role-to-ResolvedAgent Adapter
+ *
+ * Converts a Role (ROLE_TYPES pipeline) into the existing ResolvedAgent
+ * shape that materializers already accept. This is the key migration bridge:
+ * it lets the new role-based pipeline feed into existing materializers without
+ * rewriting them.
+ *
+ * The adapter is stateless — it performs a pure data transformation with no
+ * side effects or I/O.
+ */
+import type { Role } from "../types/role.js";
+import type { ResolvedAgent } from "../types.js";
+/**
+ * Error thrown when the adapter cannot convert a Role.
+ */
+export declare class AdapterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Convert a Role into a ResolvedAgent that existing materializers accept.
+ *
+ * @param role - A validated Role from the ROLE_TYPES pipeline
+ * @param agentType - The target agent dialect name (e.g., "claude-code", "codex", "aider")
+ * @returns A ResolvedAgent suitable for passing to any RuntimeMaterializer
+ * @throws AdapterError if agentType does not match a registered dialect
+ */
+export declare function adaptRoleToResolvedAgent(role: Role, agentType: string): ResolvedAgent;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/role/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/role/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,IAAI,EAIL,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,aAAa,EAKd,MAAM,aAAa,CAAC;AAGrB;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,GAChB,aAAa,CAgCf"}

package/dist/role/adapter.js

@@ -0,0 +1,149 @@
+/**
+ * Role-to-ResolvedAgent Adapter
+ *
+ * Converts a Role (ROLE_TYPES pipeline) into the existing ResolvedAgent
+ * shape that materializers already accept. This is the key migration bridge:
+ * it lets the new role-based pipeline feed into existing materializers without
+ * rewriting them.
+ *
+ * The adapter is stateless — it performs a pure data transformation with no
+ * side effects or I/O.
+ */
+import { getDialect } from "./dialect-registry.js";
+/**
+ * Error thrown when the adapter cannot convert a Role.
+ */
+export class AdapterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AdapterError";
+    }
+}
+/**
+ * Convert a Role into a ResolvedAgent that existing materializers accept.
+ *
+ * @param role - A validated Role from the ROLE_TYPES pipeline
+ * @param agentType - The target agent dialect name (e.g., "claude-code", "codex", "aider")
+ * @returns A ResolvedAgent suitable for passing to any RuntimeMaterializer
+ * @throws AdapterError if agentType does not match a registered dialect
+ */
+export function adaptRoleToResolvedAgent(role, agentType) {
+    // Validate agent type against dialect registry
+    const dialect = getDialect(agentType);
+    if (!dialect) {
+        throw new AdapterError(`Unknown agent type "${agentType}". Must be a registered dialect (e.g., "claude-code", "codex", "aider", "mcp-agent").`);
+    }
+    const name = role.metadata.name;
+    const version = role.metadata.version ?? "0.0.0";
+    // Build the single ResolvedRole from the Role
+    const resolvedRole = buildResolvedRole(role, version);
+    // Build the top-level ResolvedAgent
+    const agent = {
+        name,
+        version,
+        agentName: name,
+        slug: name,
+        description: role.metadata.description,
+        runtimes: [agentType],
+        credentials: [...(role.governance.credentials ?? [])],
+        roles: [resolvedRole],
+        proxy: {
+            port: 9090,
+            type: "streamable-http",
+        },
+    };
+    return agent;
+}
+// ---------------------------------------------------------------------------
+// Internal mapping functions
+// ---------------------------------------------------------------------------
+function buildResolvedRole(role, version) {
+    const permissions = aggregatePermissions(role.apps);
+    const tasks = role.tasks.map((t) => adaptTask(t, role.instructions));
+    const apps = role.apps.map(adaptApp);
+    const skills = role.skills.map(adaptSkill);
+    const resolvedRole = {
+        name: role.metadata.name,
+        version,
+        description: role.metadata.description,
+        instructions: role.instructions,
+        risk: role.governance.risk ?? "LOW",
+        permissions,
+        tasks,
+        apps,
+        skills,
+    };
+    // Container requirements → ResolvedRole fields
+    if (role.container) {
+        const aptPackages = role.container.packages?.apt;
+        if (aptPackages && aptPackages.length > 0) {
+            resolvedRole.aptPackages = aptPackages;
+        }
+        if (role.container.baseImage) {
+            resolvedRole.baseImage = role.container.baseImage;
+        }
+        const mounts = role.container.mounts;
+        if (mounts && mounts.length > 0) {
+            resolvedRole.mounts = mounts.map((m) => ({
+                source: m.source,
+                target: m.target,
+                readonly: m.readonly ?? false,
+            }));
+        }
+    }
+    // Governance constraints
+    if (role.governance.constraints) {
+        resolvedRole.constraints = {
+            ...role.governance.constraints,
+        };
+    }
+    return resolvedRole;
+}
+/**
+ * Aggregate tool permissions from all apps into the permissions map
+ * that ResolvedRole expects: { [appName]: { allow: string[], deny: string[] } }
+ */
+function aggregatePermissions(apps) {
+    const permissions = {};
+    for (const app of apps) {
+        permissions[app.name] = {
+            allow: [...(app.tools?.allow ?? [])],
+            deny: [...(app.tools?.deny ?? [])],
+        };
+    }
+    return permissions;
+}
+function adaptTask(task, instructions) {
+    return {
+        name: task.name,
+        version: "0.0.0",
+        taskType: "subagent",
+        prompt: instructions,
+        apps: [],
+        skills: [],
+        subTasks: [],
+    };
+}
+function adaptApp(app) {
+    return {
+        name: app.name,
+        version: "0.0.0",
+        transport: app.transport ?? "stdio",
+        command: app.command,
+        args: app.args,
+        url: app.url,
+        env: app.env ? { ...app.env } : undefined,
+        tools: [...(app.tools?.allow ?? [])],
+        capabilities: [],
+        credentials: [...(app.credentials ?? [])],
+    };
+}
+function adaptSkill(skill) {
+    return {
+        name: skill.name,
+        version: "0.0.0",
+        artifacts: [],
+        description: skill.name,
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/role/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/role/adapter.ts"],"names":[],"mappings":"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"}

package/dist/role/discovery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Unified Role Discovery — finds roles from all sources, merges with
+ * precedence rules, and presents a unified list.
+ *
+ * Discovery sources (in precedence order):
+ * 1. Local roles: <projectDir>/.<agent>/roles/* /ROLE.md
+ * 2. Packaged roles: node_modules packages with chapter.type === "role"
+ *
+ * Local roles shadow packaged roles with the same name, enabling the
+ * "eject and customize" workflow (PRD §6.3).
+ */
+import type { Role } from "../types/role.js";
+/**
+ * Error thrown when role discovery or resolution fails.
+ */
+export declare class RoleDiscoveryError extends Error {
+    constructor(message: string);
+}
+/**
+ * Discover all available roles from local agent directories and installed
+ * NPM packages. Local roles take precedence over packaged roles with the
+ * same name.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @returns Array of validated Role objects (deduplicated by name)
+ */
+export declare function discoverRoles(projectDir: string): Promise<Role[]>;
+/**
+ * Resolve a single role by name using the same precedence rules as
+ * discoverRoles. Checks local roles first, then packaged roles.
+ *
+ * @param name - Role name to resolve
+ * @param projectDir - Absolute path to the project root
+ * @returns Validated Role
+ * @throws RoleDiscoveryError if the role is not found
+ */
+export declare function resolveRole(name: string, projectDir: string): Promise<Role>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/role/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/role/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAkBvE;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/role/discovery.js

@@ -0,0 +1,209 @@
+/**
+ * Unified Role Discovery — finds roles from all sources, merges with
+ * precedence rules, and presents a unified list.
+ *
+ * Discovery sources (in precedence order):
+ * 1. Local roles: <projectDir>/.<agent>/roles/* /ROLE.md
+ * 2. Packaged roles: node_modules packages with chapter.type === "role"
+ *
+ * Local roles shadow packaged roles with the same name, enabling the
+ * "eject and customize" workflow (PRD §6.3).
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { readMaterializedRole } from "./parser.js";
+import { readPackagedRole } from "./package-reader.js";
+/**
+ * Error thrown when role discovery or resolution fails.
+ */
+export class RoleDiscoveryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RoleDiscoveryError";
+    }
+}
+/**
+ * Discover all available roles from local agent directories and installed
+ * NPM packages. Local roles take precedence over packaged roles with the
+ * same name.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @returns Array of validated Role objects (deduplicated by name)
+ */
+export async function discoverRoles(projectDir) {
+    const localRoles = await discoverLocalRoles(projectDir);
+    const packagedRoles = await discoverPackagedRoles(projectDir);
+    // Merge: local roles take precedence over packaged roles with the same name
+    const merged = new Map();
+    // Add packaged roles first (lower precedence)
+    for (const role of packagedRoles) {
+        merged.set(role.metadata.name, role);
+    }
+    // Add local roles second (higher precedence — overwrites packaged)
+    for (const role of localRoles) {
+        merged.set(role.metadata.name, role);
+    }
+    return [...merged.values()];
+}
+/**
+ * Resolve a single role by name using the same precedence rules as
+ * discoverRoles. Checks local roles first, then packaged roles.
+ *
+ * @param name - Role name to resolve
+ * @param projectDir - Absolute path to the project root
+ * @returns Validated Role
+ * @throws RoleDiscoveryError if the role is not found
+ */
+export async function resolveRole(name, projectDir) {
+    // 1. Check local roles first (higher precedence)
+    const localRole = await findLocalRole(name, projectDir);
+    if (localRole)
+        return localRole;
+    // 2. Check packaged roles
+    const packagedRole = await findPackagedRole(name, projectDir);
+    if (packagedRole)
+        return packagedRole;
+    throw new RoleDiscoveryError(`Role "${name}" not found. It is not a local role and is not installed as a package.`);
+}
+// ---------------------------------------------------------------------------
+// Local role discovery
+// ---------------------------------------------------------------------------
+/**
+ * Scan .mason/roles/ for local ROLE.md files.
+ * Silently skips the directory if it doesn't exist.
+ */
+async function discoverLocalRoles(projectDir) {
+    const roles = [];
+    const rolesDir = join(projectDir, ".mason", "roles");
+    let entries;
+    try {
+        entries = await readdir(rolesDir);
+    }
+    catch {
+        // .mason/roles/ doesn't exist — no local roles
+        return roles;
+    }
+    for (const entry of entries) {
+        const roleMdPath = join(rolesDir, entry, "ROLE.md");
+        try {
+            const s = await stat(roleMdPath);
+            if (!s.isFile())
+                continue;
+        }
+        catch {
+            // No ROLE.md in this subdirectory — skip
+            continue;
+        }
+        try {
+            const role = await readMaterializedRole(roleMdPath);
+            roles.push(role);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[mason] Skipping invalid ROLE.md at ${roleMdPath}: ${msg}`);
+            continue;
+        }
+    }
+    return roles;
+}
+/**
+ * Find a specific local role by name in .mason/roles/.
+ */
+async function findLocalRole(name, projectDir) {
+    const roleMdPath = join(projectDir, ".mason", "roles", name, "ROLE.md");
+    try {
+        const s = await stat(roleMdPath);
+        if (!s.isFile())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return await readMaterializedRole(roleMdPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[mason] Invalid ROLE.md at ${roleMdPath}: ${msg}`);
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Packaged role discovery
+// ---------------------------------------------------------------------------
+/**
+ * Scan node_modules for packages with chapter.type === "role".
+ * Checks both top-level and scoped package directories.
+ */
+async function discoverPackagedRoles(projectDir) {
+    const roles = [];
+    const nodeModulesDir = join(projectDir, "node_modules");
+    let topLevel;
+    try {
+        topLevel = await readdir(nodeModulesDir);
+    }
+    catch {
+        // No node_modules — no packaged roles
+        return roles;
+    }
+    const packageDirs = [];
+    for (const entry of topLevel) {
+        if (entry.startsWith("."))
+            continue;
+        const entryPath = join(nodeModulesDir, entry);
+        if (entry.startsWith("@")) {
+            // Scoped packages: read the scope directory
+            let scopedEntries;
+            try {
+                scopedEntries = await readdir(entryPath);
+            }
+            catch {
+                continue;
+            }
+            for (const scopedEntry of scopedEntries) {
+                if (!scopedEntry.startsWith(".")) {
+                    packageDirs.push(join(entryPath, scopedEntry));
+                }
+            }
+        }
+        else {
+            packageDirs.push(entryPath);
+        }
+    }
+    for (const pkgDir of packageDirs) {
+        if (await isRolePackage(pkgDir)) {
+            try {
+                const role = await readPackagedRole(pkgDir);
+                roles.push(role);
+            }
+            catch {
+                // Malformed package — skip during discovery
+                continue;
+            }
+        }
+    }
+    return roles;
+}
+/**
+ * Find a specific packaged role by name.
+ */
+async function findPackagedRole(name, projectDir) {
+    // First, try to find it among all packaged roles
+    const packagedRoles = await discoverPackagedRoles(projectDir);
+    return packagedRoles.find((r) => r.metadata.name === name);
+}
+/**
+ * Check if a directory is an NPM package with chapter.type === "role".
+ */
+async function isRolePackage(pkgDir) {
+    const pkgJsonPath = join(pkgDir, "package.json");
+    try {
+        const raw = await readFile(pkgJsonPath, "utf-8");
+        const pkg = JSON.parse(raw);
+        return pkg.chapter?.type === "role";
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/role/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/role/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,UAAkB;IACpD,MAAM,UAAU,GAAG,MAAM,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACxD,MAAM,aAAa,GAAG,MAAM,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAE9D,4EAA4E;IAC5E,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgB,CAAC;IAEvC,8CAA8C;IAC9C,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,mEAAmE;IACnE,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,UAAkB;IAElB,iDAAiD;IACjD,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACxD,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhC,0BAA0B;IAC1B,MAAM,YAAY,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC9D,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IAEtC,MAAM,IAAI,kBAAkB,CAC1B,SAAS,IAAI,wEAAwE,CACtF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;GAGG;AACH,KAAK,UAAU,kBAAkB,CAAC,UAAkB;IAClD,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAErD,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC;YACjC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE;gBAAE,SAAS;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,yCAAyC;YACzC,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,oBAAoB,CAAC,UAAU,CAAC,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC,uCAAuC,UAAU,KAAK,GAAG,EAAE,CAAC,CAAC;YAC1E,SAAS;QACX,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,aAAa,CAC1B,IAAY,EACZ,UAAkB;IAElB,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACxE,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC;QACjC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE;YAAE,OAAO,SAAS,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,8BAA8B,UAAU,KAAK,GAAG,EAAE,CAAC,CAAC;QACjE,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;GAGG;AACH,KAAK,UAAU,qBAAqB,CAAC,UAAkB;IACrD,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IAExD,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,sCAAsC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAEpC,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;QAE9C,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,4CAA4C;YAC5C,IAAI,aAAuB,CAAC;YAC5B,IAAI,CAAC;gBACH,aAAa,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;YAC3C,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,KAAK,MAAM,WAAW,IAAI,aAAa,EAAE,CAAC;gBACxC,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACjC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;gBACjD,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;QACjC,IAAI,MAAM,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;gBAC5C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;YAAC,MAAM,CAAC;gBACP,4CAA4C;gBAC5C,SAAS;YACX,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,gBAAgB,CAC7B,IAAY,EACZ,UAAkB;IAElB,iDAAiD;IACjD,MAAM,aAAa,GAAG,MAAM,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC9D,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,aAAa,CAAC,MAAc;IACzC,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAEzB,CAAC;QACF,OAAO,GAAG,CAAC,OAAO,EAAE,IAAI,KAAK,MAAM,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/role/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/role/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGzE,OAAO,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/role/index.js

@@ -0,0 +1,13 @@
+// Dialect Registry
+export { registerDialect, getDialect, getDialectByDirectory, getAllDialects, getKnownDirectories, } from "./dialect-registry.js";
+// Parser
+export { readMaterializedRole, parseFrontmatter, detectDialect, RoleParseError, } from "./parser.js";
+// Resource Scanner
+export { scanBundledResources } from "./resource-scanner.js";
+// Package Reader
+export { readPackagedRole, PackageReadError } from "./package-reader.js";
+// Adapter
+export { adaptRoleToResolvedAgent, AdapterError } from "./adapter.js";
+// Discovery
+export { discoverRoles, resolveRole, RoleDiscoveryError } from "./discovery.js";
+//# sourceMappingURL=index.js.map

package/dist/role/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/role/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,OAAO,EACL,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,cAAc,EACd,mBAAmB,GAGpB,MAAM,uBAAuB,CAAC;AAE/B,SAAS;AACT,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,mBAAmB;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,UAAU;AACV,OAAO,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEtE,YAAY;AACZ,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/role/package-reader.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Package Reader — reads an NPM role package and produces a Role object.
+ *
+ * Steps:
+ * 1. Read package.json and verify chapter.type === "role"
+ * 2. Read the bundled ROLE.md from the package directory
+ * 3. Parse frontmatter and body (reuses parseFrontmatter from parser.ts)
+ * 4. Normalize fields using dialect mapping if chapter.dialect is specified,
+ *    otherwise use generic ROLE_TYPES field names directly
+ * 5. Resolve all paths relative to the package directory
+ * 6. Set source.type = 'package' and source.packageName
+ * 7. Validate through roleSchema
+ */
+import type { Role } from "../types/role.js";
+/**
+ * Error thrown when a role NPM package cannot be read.
+ */
+export declare class PackageReadError extends Error {
+    readonly packagePath: string;
+    constructor(message: string, packagePath: string);
+}
+/**
+ * Read an NPM role package and produce a validated Role object.
+ *
+ * @param packagePath - Absolute path to the package directory (e.g., node_modules/@acme/role-create-prd)
+ * @returns Validated Role with source.type = 'package'
+ * @throws PackageReadError if the package is missing required files or has wrong chapter.type
+ */
+export declare function readPackagedRole(packagePath: string): Promise<Role>;
+//# sourceMappingURL=package-reader.d.ts.map

package/dist/role/package-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-reader.d.ts","sourceRoot":"","sources":["../../src/role/package-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAK7C;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,WAAW,EAAE,MAAM;gBADnC,OAAO,EAAE,MAAM,EACC,WAAW,EAAE,MAAM;CAKtC;AA2BD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwFzE"}