@clawmasons/mason 0.1.1 → 0.1.3

package/dist/generator/mount-volumes.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Utility for resolving role-declared mount volumes into Docker Compose
+ * volume strings.
+ *
+ * Mount sources may contain `${VAR}` references which are resolved from
+ * `process.env` at generation time. Unresolvable variables are left as-is
+ * (so Docker Compose's own env substitution can pick them up).
+ */
+export interface RoleMount {
+    source: string;
+    target: string;
+    readonly: boolean;
+}
+/**
+ * Resolve `${VAR}` placeholders in a string using the given environment map.
+ * Unresolvable references are left as-is.
+ */
+export declare function resolveEnvVars(value: string, env?: Record<string, string | undefined>): string;
+/**
+ * Convert role mounts into Docker Compose volume strings.
+ *
+ * Each mount becomes `"<resolved-source>:<target>"` or
+ * `"<resolved-source>:<target>:ro"` if readonly is true.
+ *
+ * @param mounts  Role mount declarations (may be undefined/empty).
+ * @param env     Environment map for `${VAR}` resolution (defaults to process.env).
+ * @returns Array of volume strings ready for YAML output.
+ */
+export declare function resolveRoleMountVolumes(mounts: RoleMount[] | undefined, env?: Record<string, string | undefined>): string[];
+//# sourceMappingURL=mount-volumes.d.ts.map

package/dist/generator/mount-volumes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-volumes.d.ts","sourceRoot":"","sources":["../../src/generator/mount-volumes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,EAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACvC,MAAM,EAAE,CASV"}

package/dist/generator/mount-volumes.js

@@ -0,0 +1,39 @@
+/**
+ * Utility for resolving role-declared mount volumes into Docker Compose
+ * volume strings.
+ *
+ * Mount sources may contain `${VAR}` references which are resolved from
+ * `process.env` at generation time. Unresolvable variables are left as-is
+ * (so Docker Compose's own env substitution can pick them up).
+ */
+/**
+ * Resolve `${VAR}` placeholders in a string using the given environment map.
+ * Unresolvable references are left as-is.
+ */
+export function resolveEnvVars(value, env = process.env) {
+    return value.replace(/\$\{([^}]+)\}/g, (_match, varName) => {
+        const resolved = env[varName];
+        return resolved !== undefined ? resolved : `\${${varName}}`;
+    });
+}
+/**
+ * Convert role mounts into Docker Compose volume strings.
+ *
+ * Each mount becomes `"<resolved-source>:<target>"` or
+ * `"<resolved-source>:<target>:ro"` if readonly is true.
+ *
+ * @param mounts  Role mount declarations (may be undefined/empty).
+ * @param env     Environment map for `${VAR}` resolution (defaults to process.env).
+ * @returns Array of volume strings ready for YAML output.
+ */
+export function resolveRoleMountVolumes(mounts, env) {
+    if (!mounts || mounts.length === 0)
+        return [];
+    return mounts.map((mount) => {
+        const source = resolveEnvVars(mount.source, env);
+        const target = resolveEnvVars(mount.target, env);
+        const suffix = mount.readonly ? ":ro" : "";
+        return `${source}:${target}${suffix}`;
+    });
+}
+//# sourceMappingURL=mount-volumes.js.map

package/dist/generator/mount-volumes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-volumes.js","sourceRoot":"","sources":["../../src/generator/mount-volumes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAa,EACb,MAA0C,OAAO,CAAC,GAAG;IAErD,OAAO,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,MAAM,EAAE,OAAe,EAAE,EAAE;QACjE,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9B,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,OAAO,GAAG,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAA+B,EAC/B,GAAwC;IAExC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC1B,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,OAAO,GAAG,MAAM,IAAI,MAAM,GAAG,MAAM,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/generator/proxy-dockerfile.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedRole } from "@clawmasons/shared";
+/**
+ * Generate a Dockerfile for a proxy container that serves a single role.
+ *
+ * The proxy image installs all mason packages from the local
+ * `docker/node_modules/` build context (no registry pulls).  It boots
+ * `mason proxy` configured for the given agent, which discovers
+ * packages at runtime from node_modules/.
+ *
+ * All proxy images run as `USER mason`.
+ *
+ * The generated Dockerfile uses `docker/` as its build context
+ * (the Dockerfile lives at `docker/proxy/<role-name>/Dockerfile`).
+ *
+ * @param role       The resolved role this proxy serves.
+ * @param agentName  The agent package name (passed to `mason proxy --agent`).
+ */
+export declare function generateProxyDockerfile(role: ResolvedRole, agentName: string): string;
+//# sourceMappingURL=proxy-dockerfile.d.ts.map

package/dist/generator/proxy-dockerfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-dockerfile.d.ts","sourceRoot":"","sources":["../../src/generator/proxy-dockerfile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAyCR"}

package/dist/generator/proxy-dockerfile.js

@@ -0,0 +1,59 @@
+import { getAppShortName } from "@clawmasons/shared";
+/**
+ * Generate a Dockerfile for a proxy container that serves a single role.
+ *
+ * The proxy image installs all mason packages from the local
+ * `docker/node_modules/` build context (no registry pulls).  It boots
+ * `mason proxy` configured for the given agent, which discovers
+ * packages at runtime from node_modules/.
+ *
+ * All proxy images run as `USER mason`.
+ *
+ * The generated Dockerfile uses `docker/` as its build context
+ * (the Dockerfile lives at `docker/proxy/<role-name>/Dockerfile`).
+ *
+ * @param role       The resolved role this proxy serves.
+ * @param agentName  The agent package name (passed to `mason proxy --agent`).
+ */
+export function generateProxyDockerfile(role, agentName) {
+    const roleShortName = getAppShortName(role.name);
+    return `# Proxy Dockerfile for role: ${roleShortName}
+# Generated by mason chapter build
+FROM node:22-slim
+
+WORKDIR /app
+
+# Cache V8-compiled bytecode across container restarts
+ENV NODE_COMPILE_CACHE=/app/.cache/v8
+# Direct npm/npx package cache into the persistent .cache volume
+ENV NPM_CONFIG_CACHE=/app/.cache/npm
+
+# Install build tools for native addons (e.g., better-sqlite3)
+RUN apt-get update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
+
+# Copy esbuild-bundled proxy entry point (single file, fast boot)
+COPY proxy-bundle.cjs ./
+
+# Copy pre-populated node_modules (native addons + package.json for discovery)
+COPY package.json ./
+COPY node_modules/ ./node_modules/
+
+# Rebuild native addons for the container platform
+RUN npm rebuild better-sqlite3
+
+# Create mason user with host-matching UID/GID
+ARG HOST_UID=1000
+ARG HOST_GID=1000
+RUN (getent group $HOST_GID | cut -d: -f1 | xargs -r groupdel 2>/dev/null || true) \\
+    && (getent passwd $HOST_UID | cut -d: -f1 | xargs -r userdel 2>/dev/null || true) \\
+    && groupadd -g $HOST_GID mason && useradd -m -u $HOST_UID -g $HOST_GID mason \\
+    && mkdir -p /home/mason/data /logs /app/.cache/v8 /app/.cache/npm \\
+    && chown -R mason:mason /app /home/mason/data /logs
+
+USER mason
+
+ENTRYPOINT ["node", "proxy-bundle.cjs"]
+CMD ["--agent", "${agentName}", "--transport", "streamable-http"]
+`;
+}
+//# sourceMappingURL=proxy-dockerfile.js.map

package/dist/generator/proxy-dockerfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-dockerfile.js","sourceRoot":"","sources":["../../src/generator/proxy-dockerfile.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAkB,EAClB,SAAiB;IAEjB,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjD,OAAO,gCAAgC,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAoCnC,SAAS;CAC3B,CAAC;AACF,CAAC"}

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, type DiscoveredPackage, type ResolvedAgent, type ResolvedApp, type ResolvedRole, type ResolvedSkill, type ResolvedTask, computeToolFilters, getAppShortName, type ToolFilter, } from "@clawmasons/shared";
+export { PackageNotFoundError, InvalidChapterFieldError, CircularDependencyError, TypeMismatchError, discoverPackages, resolveRolePackage, } from "./resolver/index.js";
+export { validateAgent, type ValidationResult, type ValidationError, type ValidationErrorCategory, type ValidationWarning, type ValidationWarningCategory, } from "./validator/index.js";
+export { claudeCodeMaterializer, piCodingAgentMaterializer, mcpAgentMaterializer, PROVIDER_ENV_VARS, ACP_RUNTIME_COMMANDS, type RuntimeMaterializer, type MaterializationResult, type MaterializeOptions, } from "./materializer/index.js";
+export { default as claudeCodeAgent } from "@clawmasons/claude-code-agent";
+export { default as piCodingAgentPkg } from "@clawmasons/pi-coding-agent";
+export type { AgentPackage } from "@clawmasons/agent-sdk";
+//# 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":"AAAA,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,EACjB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,kBAAkB,EAClB,eAAe,EACf,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,GAC/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { appChapterFieldSchema, skillChapterFieldSchema, taskChapterFieldSchema, roleChapterFieldSchema, parseChapterField, computeToolFilters, getAppShortName, } from "@clawmasons/shared";
+export { PackageNotFoundError, InvalidChapterFieldError, CircularDependencyError, TypeMismatchError, discoverPackages, resolveRolePackage, } from "./resolver/index.js";
+export { validateAgent, } from "./validator/index.js";
+export { claudeCodeMaterializer, piCodingAgentMaterializer, mcpAgentMaterializer, PROVIDER_ENV_VARS, ACP_RUNTIME_COMMANDS, } from "./materializer/index.js";
+// Re-export agent packages for consumers
+export { default as claudeCodeAgent } from "@clawmasons/claude-code-agent";
+export { default as piCodingAgentPkg } from "@clawmasons/pi-coding-agent";
+//# 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,OAAO,EACL,qBAAqB,EAErB,uBAAuB,EAEvB,sBAAsB,EAEtB,sBAAsB,EAEtB,iBAAiB,EAQjB,kBAAkB,EAClB,eAAe,GAEhB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,GAMd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,GAIrB,MAAM,yBAAyB,CAAC;AAEjC,yCAAyC;AACzC,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/materializer/common.d.ts

@@ -0,0 +1,17 @@
+export { PROVIDER_ENV_VARS, formatPermittedTools, findRolesForTask, collectAllSkills, collectAllTasks, generateSkillReadme, } from "@clawmasons/agent-sdk";
+export type { LaunchCredentialConfig } from "@clawmasons/agent-sdk";
+/**
+ * Legacy ACP_RUNTIME_COMMANDS map.
+ * @deprecated Use AgentPackage.acp.command instead via the agent registry.
+ */
+export declare const ACP_RUNTIME_COMMANDS: Record<string, string>;
+/**
+ * Generate agent-launch.json content.
+ *
+ * Legacy wrapper that resolves the AgentPackage from the registry
+ * and delegates to the SDK's generateAgentLaunchJson.
+ *
+ * @deprecated Import from agent packages directly.
+ */
+export declare function generateAgentLaunchJson(runtime: string, roleCredentials: string[], acpMode?: boolean, instructions?: string): string;
+//# sourceMappingURL=common.d.ts.map

package/dist/materializer/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/materializer/common.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAQpE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKvD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EAAE,EACzB,OAAO,CAAC,EAAE,OAAO,EACjB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAcR"}

package/dist/materializer/common.js

@@ -0,0 +1,37 @@
+// Re-export helpers from the agent SDK for backward compatibility
+export { PROVIDER_ENV_VARS, formatPermittedTools, findRolesForTask, collectAllSkills, collectAllTasks, generateSkillReadme, } from "@clawmasons/agent-sdk";
+import { generateAgentLaunchJson as sdkGenerateAgentLaunchJson } from "@clawmasons/agent-sdk";
+import { getAgentFromRegistry } from "./role-materializer.js";
+/**
+ * Legacy ACP_RUNTIME_COMMANDS map.
+ * @deprecated Use AgentPackage.acp.command instead via the agent registry.
+ */
+export const ACP_RUNTIME_COMMANDS = {
+    "claude-code-agent": "claude-agent-acp",
+    "pi-coding-agent": "pi-agent-acp",
+    "node": "node src/index.js --acp",
+    "mcp-agent": "mcp-agent --acp",
+};
+/**
+ * Generate agent-launch.json content.
+ *
+ * Legacy wrapper that resolves the AgentPackage from the registry
+ * and delegates to the SDK's generateAgentLaunchJson.
+ *
+ * @deprecated Import from agent packages directly.
+ */
+export function generateAgentLaunchJson(runtime, roleCredentials, acpMode, instructions) {
+    const agentPkg = getAgentFromRegistry(runtime);
+    if (agentPkg) {
+        return sdkGenerateAgentLaunchJson(agentPkg, roleCredentials, acpMode, instructions);
+    }
+    // Fallback for unknown runtimes: create a minimal AgentPackage-like object
+    const fallbackPkg = {
+        name: runtime,
+        materializer: { name: runtime, materializeWorkspace: () => new Map() },
+        runtime: { command: runtime },
+        acp: ACP_RUNTIME_COMMANDS[runtime] ? { command: ACP_RUNTIME_COMMANDS[runtime] } : undefined,
+    };
+    return sdkGenerateAgentLaunchJson(fallbackPkg, roleCredentials, acpMode, instructions);
+}
+//# sourceMappingURL=common.js.map

package/dist/materializer/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/materializer/common.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EAAE,uBAAuB,IAAI,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA2B;IAC1D,mBAAmB,EAAE,kBAAkB;IACvC,iBAAiB,EAAE,cAAc;IACjC,MAAM,EAAE,yBAAyB;IACjC,WAAW,EAAE,iBAAiB;CAC/B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,eAAyB,EACzB,OAAiB,EACjB,YAAqB;IAErB,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,0BAA0B,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IACtF,CAAC;IAED,2EAA2E;IAC3E,MAAM,WAAW,GAAiB;QAChC,IAAI,EAAE,OAAO;QACb,YAAY,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,EAAE,CAAC,IAAI,GAAG,EAAE,EAAE;QACtE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;QAC7B,GAAG,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS;KAC5F,CAAC;IACF,OAAO,0BAA0B,CAAC,WAAW,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;AACzF,CAAC"}

package/dist/materializer/docker-generator.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Role-centric Docker build directory and session generation.
+ *
+ * Generates:
+ * 1. Docker build directories at `.mason/docker/<role-name>/` (PRD §7.1)
+ * 2. Volume masking for container.ignore.paths (PRD §7.3)
+ * 3. Sentinel empty file for file-level volume masking
+ * 4. Session directories with self-contained compose files (PRD §7.5)
+ *
+ * @module docker-generator
+ */
+import type { Role } from "@clawmasons/shared";
+import { type RoleMount } from "../generator/mount-volumes.js";
+import type { DevContainerCustomizations } from "@clawmasons/agent-sdk";
+/**
+ * Get the current host user's UID and GID.
+ * Returns string values suitable for Docker build args.
+ */
+export declare function getHostIds(): {
+    uid: string;
+    gid: string;
+};
+export interface VolumeMaskEntry {
+    /** Whether this mask targets a directory or a file. */
+    type: "directory" | "file";
+    /** The original path from container.ignore.paths. */
+    hostPath: string;
+    /** The container path (under project mount). */
+    containerPath: string;
+    /** Named volume name for directory masks. */
+    volumeName?: string;
+}
+/**
+ * Sanitize a path into a valid Docker volume name.
+ *
+ * Replaces non-alphanumeric characters with hyphens, strips leading/trailing
+ * hyphens, and prefixes with "ignore-".
+ */
+export declare function sanitizeVolumeName(ignorePath: string): string;
+/**
+ * Classify ignore paths and generate volume mask entries.
+ *
+ * - Paths ending with `/` are classified as directories (masked with named empty volumes).
+ * - Paths without trailing `/` are classified as files (masked with bind mount of sentinel file).
+ *
+ * All container paths target the project mount at `/home/mason/workspace/project/`.
+ *
+ * @param ignorePaths - Array of paths from container.ignore.paths
+ * @returns Array of VolumeMaskEntry objects
+ */
+export declare function generateVolumeMasks(ignorePaths: string[]): VolumeMaskEntry[];
+/**
+ * Ensure the sentinel empty file exists at `.mason/empty-file`.
+ *
+ * The file is 0 bytes with permissions `0o444` (read-only for all).
+ * Idempotent — does nothing if the file already exists.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @returns Absolute path to the sentinel file
+ */
+export declare function ensureSentinelFile(projectDir: string, fsDeps?: {
+    existsSync?: (p: string) => boolean;
+    mkdirSync?: (p: string, opts?: {
+        recursive?: boolean;
+    }) => void;
+    writeFileSync?: (p: string, data: string, opts?: {
+        mode?: number;
+    }) => void;
+    chmodSync?: (p: string, mode: number) => void;
+}): string;
+export interface GenerateBuildDirOptions {
+    /** The resolved Role to generate for. */
+    role: Role;
+    /** Target agent type (e.g., "claude-code-agent"). */
+    agentType: string;
+    /** Absolute path to the project root. */
+    projectDir: string;
+    /** Root of docker build output (defaults to `<projectDir>/.mason/docker`). */
+    dockerBuildRoot?: string;
+    /** Agent name for the proxy CMD (the npm agent package name). */
+    agentName: string;
+    /** Optional: override the proxy endpoint for workspace materialization. */
+    proxyEndpoint?: string;
+    /** Dev-container customizations to embed in the agent Dockerfile LABEL. */
+    devContainerCustomizations?: DevContainerCustomizations;
+    /** Additional credential env var keys from agent config (.mason/config.json) to include in agent-launch.json. */
+    agentConfigCredentials?: string[];
+    /** Extra args from alias config to append to the agent invocation. */
+    agentArgs?: string[];
+}
+export interface BuildDirResult {
+    /** Absolute path to the generated build directory. */
+    buildDir: string;
+    /** Relative path from build dir to the agent Dockerfile. */
+    agentDockerfilePath: string;
+    /** Relative path from build dir to the proxy Dockerfile. */
+    proxyDockerfilePath: string;
+}
+/**
+ * Generate the role-centric Docker build directory at
+ * `.mason/docker/<role-name>/`.
+ *
+ * Structure (PRD §7.1):
+ * ```
+ * <role-name>/
+ * ├── <agent-type>/
+ * │   ├── Dockerfile
+ * │   └── workspace/
+ * │       └── (materialized files)
+ * ├── mcp-proxy/
+ * │   └── Dockerfile
+ * └── docker-compose.yaml
+ * ```
+ */
+export declare function generateRoleDockerBuildDir(opts: GenerateBuildDirOptions, fsDeps?: {
+    mkdirSync?: (p: string, opts?: {
+        recursive?: boolean;
+    }) => void;
+    writeFileSync?: (p: string, data: string) => void;
+}): BuildDirResult;
+export interface SessionComposeOptions {
+    /** Absolute path to the project root. */
+    projectDir: string;
+    /** Absolute path to the role's Docker build directory. */
+    dockerBuildDir: string;
+    /** Absolute path to the docker/ dir (for proxy build context). */
+    dockerDir: string;
+    /** Role short name. */
+    roleName: string;
+    /** Agent type (e.g., "claude-code-agent"). */
+    agentType: string;
+    /** Agent name for service naming. */
+    agentName: string;
+    /** Proxy authentication token. */
+    proxyToken: string;
+    /** Credential proxy token. */
+    credentialProxyToken: string;
+    /** Proxy port on host. */
+    proxyPort?: number;
+    /** Volume mask entries from generateVolumeMasks(). */
+    volumeMasks?: VolumeMaskEntry[];
+    /** Role-declared extra mounts. */
+    roleMounts?: RoleMount[];
+    /** Declared credential keys. */
+    credentialKeys?: string[];
+    /** Session type (e.g., "interactive", "acp"). */
+    sessionType?: string;
+    /** ACP command args. */
+    acpCommand?: string[];
+    /** Absolute path to the session directory (for relative path computation). */
+    sessionDir: string;
+    /** Absolute path to logs directory. */
+    logsDir: string;
+    /** Absolute path to the materialized agent home directory (if exists). */
+    homePath?: string;
+    /** Host user UID for container user matching. */
+    hostUid?: string;
+    /** Host user GID for container user matching. */
+    hostGid?: string;
+    /** Absolute path to {agentDir}/workspace/ — live-mounted to /home/mason/workspace/. */
+    workspacePath?: string;
+    /** Absolute path to {agentDir}/build/workspace/project/ — files here get per-entry overlay mounts. */
+    buildWorkspaceProjectPath?: string;
+    /** File entries inside buildWorkspaceProjectPath — mounted via Docker Compose configs (VirtioFS-safe). */
+    buildWorkspaceProjectFileEntries?: string[];
+    /** Directory entries inside buildWorkspaceProjectPath — mounted as bind-mount overlays. */
+    buildWorkspaceProjectDirEntries?: string[];
+    /** Override bind-mount path for /home/mason/ (e.g. --home flag). */
+    homeOverride?: string;
+    /** VS Code server host path to mount at /home/mason/.vscode-server. */
+    vscodeServerHostPath?: string;
+    /** Set AGENT_COMMAND_OVERRIDE=bash in agent environment. */
+    bashMode?: boolean;
+    /** Set AGENT_ENTRY_VERBOSE=1 in agent environment. */
+    verbose?: boolean;
+}
+/**
+ * Generate a self-contained docker-compose.yaml for a session directory.
+ *
+ * All paths are relative to the session directory, making the session dir
+ * a fully functional Docker Compose project. Users can run:
+ * - `docker compose logs -f`
+ * - `docker compose ps`
+ * - `docker compose exec agent sh`
+ * - `docker compose down`
+ *
+ * from the session directory.
+ */
+export declare function generateSessionComposeYml(opts: SessionComposeOptions): string;
+export interface CreateSessionOptions {
+    /** Absolute path to the project root. */
+    projectDir: string;
+    /** Absolute path to the role's Docker build directory. */
+    dockerBuildDir: string;
+    /** Absolute path to the docker/ dir (for proxy build context). */
+    dockerDir: string;
+    /** Role definition. */
+    role: Role;
+    /** Agent type (e.g., "claude-code-agent"). */
+    agentType: string;
+    /** Agent name for proxy CMD. */
+    agentName: string;
+    /** Proxy port. */
+    proxyPort?: number;
+    /** Role-declared mounts. */
+    roleMounts?: RoleMount[];
+    /** Declared credential keys. */
+    credentialKeys?: string[];
+    /** Session type. */
+    sessionType?: string;
+    /** ACP command args. */
+    acpCommand?: string[];
+    /** Host user UID for container user matching. */
+    hostUid?: string;
+    /** Host user GID for container user matching. */
+    hostGid?: string;
+    /** Override bind-mount path for /home/mason/ (e.g. --home flag). */
+    homeOverride?: string;
+    /** VS Code server host path to mount at /home/mason/.vscode-server. */
+    vscodeServerHostPath?: string;
+    /** Set AGENT_COMMAND_OVERRIDE=bash in agent environment. */
+    bashMode?: boolean;
+    /** Set AGENT_ENTRY_VERBOSE=1 in agent environment. */
+    verbose?: boolean;
+    /** Pre-determined session ID (overrides random generation, for testing). */
+    sessionId?: string;
+}
+export interface SessionResult {
+    /** Unique session ID. */
+    sessionId: string;
+    /** Absolute path to the session directory. */
+    sessionDir: string;
+    /** Absolute path to the compose file. */
+    composeFile: string;
+    /** Absolute path to the logs directory. */
+    logsDir: string;
+    /** Generated proxy token. */
+    proxyToken: string;
+    /** Generated credential proxy token. */
+    credentialProxyToken: string;
+    /** Proxy service name. */
+    proxyServiceName: string;
+    /** Agent service name. */
+    agentServiceName: string;
+}
+/**
+ * Create a session directory with a self-contained docker-compose.yaml.
+ *
+ * @returns Session metadata including paths, tokens, and service names.
+ */
+export declare function createSessionDirectory(opts: CreateSessionOptions, fsDeps?: {
+    mkdirSync?: (p: string, opts?: {
+        recursive?: boolean;
+    }) => void;
+    writeFileSync?: (p: string, data: string) => void;
+    randomBytes?: (n: number) => Buffer;
+}): SessionResult;
+//# sourceMappingURL=docker-generator.d.ts.map

package/dist/materializer/docker-generator.d.ts.map

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