kairn-cli 1.10.0 → 1.10.1

package/dist/cli.js

@@ -460,17 +460,72 @@ import Anthropic2 from "@anthropic-ai/sdk";
 import OpenAI2 from "openai";
 
 // src/compiler/prompt.ts
-var SYSTEM_PROMPT = `You are the Kairn environment compiler. Your job is to generate a minimal, optimal Claude Code agent environment from a user's natural language description of what they want their agent to do.
+var SKELETON_PROMPT = `You are the Kairn skeleton compiler. Your job is to select tools and outline the project structure from a user's natural language description.
 
 You will receive:
 1. The user's intent (what they want to build/do)
 2. A tool registry (available MCP servers, plugins, and hooks)
 
-You must output a JSON object matching the EnvironmentSpec schema.
+You must output a JSON object matching the SkeletonSpec schema.
 
 ## Core Principles
 
 - **Minimalism over completeness.** Fewer, well-chosen tools beat many generic ones. Each MCP server costs 500-2000 context tokens.
+- **Workflow-specific, not generic.** Select tools that directly support the user's actual workflow.
+- **Security by default.** Essential for all projects.
+
+## Tool Selection Rules
+
+- Only select tools directly relevant to the described workflow
+- Prefer free tools (auth: "none") when quality is comparable
+- Tier 1 tools (Context7, Sequential Thinking, security-guidance) should be included in most environments
+- For tools requiring API keys (auth: "api_key"), use \${ENV_VAR} syntax \u2014 never hardcode keys
+- Maximum 6-8 MCP servers to avoid context bloat
+- Include a \`reason\` for each selected tool explaining why it fits this workflow
+
+## Context Budget (STRICT)
+
+- MCP servers: maximum 6. Prefer fewer.
+- Skills: maximum 3. Only include directly relevant ones.
+- Agents: maximum 3. QA pipeline + one specialist.
+- Hooks: maximum 4 (auto-format, block-destructive, PostCompact, plus one contextual).
+
+If the workflow doesn't clearly need a tool, DO NOT include it.
+Each MCP server costs 500-2000 tokens of context window.
+
+## Output Schema
+
+Return ONLY valid JSON matching this structure:
+
+\`\`\`json
+{
+  "name": "short-kebab-case-name",
+  "description": "One-line description",
+  "tools": [
+    { "tool_id": "id-from-registry", "reason": "why this tool fits" }
+  ],
+  "outline": {
+    "tech_stack": ["Python", "pandas"],
+    "workflow_type": "data-analysis",
+    "key_commands": ["ingest", "analyze", "report"],
+    "custom_rules": ["data-integrity"],
+    "custom_agents": ["data-reviewer"],
+    "custom_skills": ["ms-data-analysis"]
+  }
+}
+\`\`\`
+
+Return ONLY valid JSON. No markdown fences. No text outside the JSON.`;
+var HARNESS_PROMPT = `You are the Kairn harness compiler. Your job is to generate the full environment content from a project skeleton.
+
+You will receive:
+1. The skeleton (tool selections + project outline)
+2. The user's original intent
+
+You must generate all harness content: CLAUDE.md, commands, rules, agents, skills, and docs.
+
+## Core Principles
+
 - **Workflow-specific, not generic.** Every instruction, command, and rule must relate to the user's actual workflow.
 - **Concise CLAUDE.md.** Under 120 lines. No generic text like "be helpful." Include build/test commands, reference docs/ and skills/.
 - **Security by default.** Always include deny rules for destructive commands and secret file access.
@@ -656,28 +711,6 @@ All projects should include a PostCompact hook to restore context after compacti
 
 Merge this into the settings hooks alongside the PreToolUse and PostToolUse hooks.
 
-## Tool Selection Rules
-
-- Only select tools directly relevant to the described workflow
-- Prefer free tools (auth: "none") when quality is comparable
-- Tier 1 tools (Context7, Sequential Thinking, security-guidance) should be included in most environments
-- For tools requiring API keys (auth: "api_key"), use \${ENV_VAR} syntax \u2014 never hardcode keys
-- Maximum 6-8 MCP servers to avoid context bloat
-- Include a \`reason\` for each selected tool explaining why it fits this workflow
-
-## Context Budget (STRICT)
-
-- MCP servers: maximum 6. Prefer fewer.
-- CLAUDE.md: maximum 120 lines.
-- Rules: maximum 5 files, each under 20 lines.
-- Skills: maximum 3. Only include directly relevant ones.
-- Agents: maximum 3. QA pipeline + one specialist.
-- Commands: no limit (loaded on demand, zero context cost).
-- Hooks: maximum 4 (auto-format, block-destructive, PostCompact, plus one contextual).
-
-If the workflow doesn't clearly need a tool, DO NOT include it.
-Each MCP server costs 500-2000 tokens of context window.
-
 ## For Code Projects, Additionally Include
 
 - \`/project:plan\` command (plan before coding)
@@ -741,6 +774,133 @@ If no autonomy level is specified, assume Level 1 (Guided).
 
 Return ONLY valid JSON matching this structure:
 
+\`\`\`json
+{
+  "claude_md": "Full CLAUDE.md content (under 120 lines)",
+  "commands": { "help": "...", "tasks": "...", "status": "...", "fix": "...", "sprint": "...", "spec": "...", "prove": "...", "grill": "...", "reset": "..." },
+  "rules": { "continuity": "...", "security": "..." },
+  "agents": { "qa-orchestrator": "...", "linter": "...", "e2e-tester": "..." },
+  "skills": { "skill-name/SKILL": "..." },
+  "docs": { "TODO": "...", "DECISIONS": "...", "LEARNINGS": "...", "SPRINT": "..." }
+}
+\`\`\`
+
+Return ONLY valid JSON. No markdown fences. No text outside the JSON.`;
+var SYSTEM_PROMPT = `You are the Kairn environment compiler. Your job is to generate a minimal, optimal Claude Code agent environment from a user's natural language description of what they want their agent to do.
+
+You will receive:
+1. The user's intent (what they want to build/do)
+2. A tool registry (available MCP servers, plugins, and hooks)
+
+You must output a JSON object matching the EnvironmentSpec schema.
+
+## Core Principles
+
+- **Minimalism over completeness.** Fewer, well-chosen tools beat many generic ones. Each MCP server costs 500-2000 context tokens.
+- **Workflow-specific, not generic.** Every instruction, command, and rule must relate to the user's actual workflow.
+- **Concise CLAUDE.md.** Under 120 lines. No generic text like "be helpful." Include build/test commands, reference docs/ and skills/.
+- **Security by default.** Always include deny rules for destructive commands and secret file access.
+
+## CLAUDE.md Template (mandatory structure)
+
+The \`claude_md\` field MUST follow this exact structure (max 120 lines):
+
+\`\`\`
+# {Project Name}
+
+## Purpose
+{one-line description}
+
+## Tech Stack
+{bullet list of frameworks/languages}
+
+## Commands
+{concrete build/test/lint/dev commands}
+
+## Architecture
+{brief folder structure, max 10 lines}
+
+## Conventions
+{3-5 specific coding rules}
+
+## Key Commands
+{list /project: commands with descriptions}
+
+## Output
+{where results go, key files}
+
+## Verification
+After implementing any change, verify it works:
+- {build command} \u2014 must pass with no errors
+- {test command} \u2014 all tests must pass
+- {lint command} \u2014 no warnings or errors
+- {type check command} \u2014 no type errors
+
+If any verification step fails, fix the issue before moving on.
+Do NOT skip verification steps.
+
+## Known Gotchas
+<!-- After any correction, add it here: "Update CLAUDE.md so you don't make that mistake again." -->
+<!-- Prune this section when it exceeds 10 items \u2014 keep only the recurring ones. -->
+- (none yet \u2014 this section grows as you work)
+
+## Debugging
+When debugging, paste raw error output. Don't summarize \u2014 Claude works better with raw data.
+Use subagents for deep investigation to keep main context clean.
+
+## Git Workflow
+- Prefer small, focused commits (one feature or fix per commit)
+- Use conventional commits: feat:, fix:, docs:, refactor:, test:
+- Target < 200 lines per PR when possible
+\`\`\`
+
+Do not add generic filler. Every line must be specific to the user's workflow.
+
+## What You Must Always Include
+
+1. A concise, workflow-specific \`claude_md\` (the CLAUDE.md content)
+2. A \`/project:help\` command that explains the environment
+3. A \`/project:tasks\` command for task management via TODO.md
+4. A \`docs/TODO.md\` file for continuity
+5. A \`docs/DECISIONS.md\` file for architectural decisions
+6. A \`docs/LEARNINGS.md\` file for non-obvious discoveries
+7. A \`rules/continuity.md\` rule encouraging updates to DECISIONS.md and LEARNINGS.md
+8. A \`rules/security.md\` rule with essential security instructions
+9. settings.json with deny rules for \`rm -rf\`, \`curl|sh\`, reading \`.env\` and \`secrets/\`
+10. A \`/project:status\` command for code projects (uses ! for live git/test output)
+11. A \`/project:fix\` command for code projects (uses $ARGUMENTS for issue number)
+12. A \`docs/SPRINT.md\` file for sprint contracts (acceptance criteria, verification steps)
+13. A "Verification" section in CLAUDE.md with concrete verify commands for the project
+14. A "Known Gotchas" section in CLAUDE.md (starts empty, grows with corrections)
+15. A "Debugging" section in CLAUDE.md (2 lines: paste raw errors, use subagents)
+16. A "Git Workflow" section in CLAUDE.md (3 rules: small commits, conventional format, <200 lines PR)
+
+## Tool Selection Rules
+
+- Only select tools directly relevant to the described workflow
+- Prefer free tools (auth: "none") when quality is comparable
+- Tier 1 tools (Context7, Sequential Thinking, security-guidance) should be included in most environments
+- For tools requiring API keys (auth: "api_key"), use \${ENV_VAR} syntax \u2014 never hardcode keys
+- Maximum 6-8 MCP servers to avoid context bloat
+- Include a \`reason\` for each selected tool explaining why it fits this workflow
+
+## Context Budget (STRICT)
+
+- MCP servers: maximum 6. Prefer fewer.
+- CLAUDE.md: maximum 120 lines.
+- Rules: maximum 5 files, each under 20 lines.
+- Skills: maximum 3. Only include directly relevant ones.
+- Agents: maximum 3. QA pipeline + one specialist.
+- Commands: no limit (loaded on demand, zero context cost).
+- Hooks: maximum 4 (auto-format, block-destructive, PostCompact, plus one contextual).
+
+If the workflow doesn't clearly need a tool, DO NOT include it.
+Each MCP server costs 500-2000 tokens of context window.
+
+## Output Schema
+
+Return ONLY valid JSON matching this structure:
+
 \`\`\`json
 {
   "name": "short-kebab-case-name",
@@ -761,14 +921,7 @@ Return ONLY valid JSON matching this structure:
     },
     "commands": {
       "help": "markdown content for /project:help",
-      "tasks": "markdown content for /project:tasks",
-      "status": "Show project status:\\n\\n!git status --short\\n\\n!git log --oneline -5\\n\\nRead TODO.md and summarize progress.",
-      "fix": "Fix issue #$ARGUMENTS:\\n\\n1. Read the issue and understand the problem\\n2. Plan the fix\\n3. Implement the fix\\n4. Run tests:\\n\\n!npm test 2>&1 | tail -20\\n\\n5. Commit with: fix: resolve #$ARGUMENTS",
-      "sprint": "Define a sprint contract for the next feature:\\n\\n1. Read docs/TODO.md for context:\\n\\n!cat docs/TODO.md 2>/dev/null\\n\\n2. Write a CONTRACT to docs/SPRINT.md with: feature name, acceptance criteria, verification steps, files to modify, scope estimate.\\n3. Do NOT start coding until contract is confirmed.",
-      "spec": "Before building this feature, interview me to create a complete spec.\\n\\nAsk me 5-8 questions, one at a time:\\n1. What specifically should this feature do?\\n2. Who uses it and how?\\n3. What are the edge cases or error states?\\n4. How will we know it works? (acceptance criteria)\\n5. What should it explicitly NOT do? (scope boundaries)\\n6. Any dependencies, APIs, or constraints?\\n7. How does it fit with existing code?\\n8. Priority: speed, quality, or flexibility?\\n\\nAfter my answers, write a structured spec to docs/SPRINT.md:\\n- Feature name\\n- Description (from my answers, not invented)\\n- Acceptance criteria (testable)\\n- Out of scope\\n- Technical approach\\n\\nDo NOT start coding until I confirm the spec.",
-      "prove": "Prove the current implementation works.\\n\\n1. Run the full test suite:\\n\\n!npm test 2>&1\\n\\n2. Compare against main:\\n\\n!git diff main --stat 2>/dev/null\\n\\n3. Show evidence:\\n   - Test results (pass/fail counts)\\n   - Behavioral diff (main vs this branch)\\n   - Edge cases tested\\n   - Error handling verified\\n\\n4. Rate confidence:\\n   - HIGH: All tests pass, edge cases covered, no regressions\\n   - MEDIUM: Core works, some edges untested\\n   - LOW: Needs more verification\\n\\nIf LOW or MEDIUM, explain what's missing and fix it.",
-      "grill": "Review the current changes adversarially.\\n\\n!git diff --staged 2>/dev/null || git diff HEAD 2>/dev/null\\n\\nAct as a senior engineer. For each file changed:\\n\\n1. \\"Why this approach over X?\\"\\n2. \\"What happens if Y input?\\"\\n3. \\"Performance impact of Z?\\"\\n4. \\"This could break if...\\"\\n\\nFor each concern:\\n- Severity: BLOCKER / SHOULD-FIX / NITPICK\\n- The exact scenario that could fail\\n- A suggested alternative\\n\\nDo NOT approve until all BLOCKERs are resolved.",
-      "reset": "Stop. Read docs/DECISIONS.md and docs/LEARNINGS.md.\\n\\nConsidering everything we've learned:\\n1. What was the original approach?\\n2. What went wrong or feels inelegant?\\n3. What would the clean solution look like?\\n\\nPropose the new approach. Do NOT implement yet.\\nIf I approve, stash current changes:\\n  git stash -m \\"pre-reset: $(date +%Y%m%d-%H%M)\\"\\n\\nThen implement the elegant solution."
+      "tasks": "markdown content for /project:tasks"
     },
     "rules": {
       "continuity": "markdown content for continuity rule",
@@ -778,15 +931,13 @@ Return ONLY valid JSON matching this structure:
       "skill-name/SKILL": "markdown content with YAML frontmatter"
     },
     "agents": {
-      "qa-orchestrator": "---\\nname: qa-orchestrator\\ndescription: Orchestrates QA pipeline\\nmodel: sonnet\\n---\\nRun QA: delegate to @linter for static analysis, @e2e-tester for browser tests. Compile consolidated report.",
-      "linter": "---\\nname: linter\\ndescription: Fast static analysis\\nmodel: haiku\\n---\\nRun available linters (eslint, prettier, biome, ruff, mypy, semgrep). Report issues.",
-      "e2e-tester": "---\\nname: e2e-tester\\ndescription: Browser-based QA via Playwright\\nmodel: sonnet\\n---\\nTest user flows via Playwright. Verify behavior, not just DOM. Screenshot failures."
+      "qa-orchestrator": "agent markdown with YAML frontmatter"
     },
     "docs": {
-      "TODO": "# TODO\\n\\n- [ ] First task based on workflow",
-      "DECISIONS": "# Decisions\\n\\nArchitectural decisions for this project.",
-      "LEARNINGS": "# Learnings\\n\\nNon-obvious discoveries and gotchas.",
-      "SPRINT": "# Sprint Contract\\n\\nDefine acceptance criteria before starting work."
+      "TODO": "# TODO\\n\\n- [ ] First task",
+      "DECISIONS": "# Decisions\\n\\nArchitectural decisions.",
+      "LEARNINGS": "# Learnings\\n\\nNon-obvious discoveries.",
+      "SPRINT": "# Sprint Contract\\n\\nDefine acceptance criteria."
     }
   }
 }
@@ -864,7 +1015,7 @@ async function loadRegistry() {
 }
 
 // src/compiler/compile.ts
-function buildUserMessage(intent, registry) {
+function buildSkeletonMessage(intent, registry) {
   const registrySummary = registry.map(
     (t) => `- ${t.id} (${t.type}, tier ${t.tier}, auth: ${t.auth}): ${t.description} [best_for: ${t.best_for.join(", ")}]`
   ).join("\n");
@@ -876,25 +1027,60 @@ ${intent}
 
 ${registrySummary}
 
-Generate the EnvironmentSpec JSON now.`;
+Generate the skeleton JSON now.`;
+}
+function buildHarnessMessage(intent, skeleton, concise) {
+  const skeletonJson = JSON.stringify(skeleton, null, 2);
+  const conciseNote = concise ? "\n\nIMPORTANT: Be concise. Maximum 80 lines for claude_md. Maximum 5 commands. Keep all content brief." : "";
+  return `## User Intent
+
+${intent}
+
+## Project Skeleton
+
+${skeletonJson}
+
+Generate the harness content JSON now.${conciseNote}`;
 }
-function parseSpecResponse(text) {
+function parseSkeletonResponse(text) {
   let cleaned = text.trim();
   if (cleaned.startsWith("```")) {
     cleaned = cleaned.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
   }
   const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
   if (!jsonMatch) {
+    throw new Error("Pass 1 (skeleton) did not return valid JSON.");
+  }
+  try {
+    const parsed = JSON.parse(jsonMatch[0]);
+    if (!parsed.name || !parsed.tools || !Array.isArray(parsed.tools)) {
+      throw new Error("Skeleton missing required fields: name, tools");
+    }
+    return parsed;
+  } catch (err) {
     throw new Error(
-      "LLM response did not contain valid JSON. Try again or use a different model."
+      `Failed to parse skeleton JSON: ${err instanceof Error ? err.message : String(err)}`
     );
   }
+}
+function parseHarnessResponse(text) {
+  let cleaned = text.trim();
+  if (cleaned.startsWith("```")) {
+    cleaned = cleaned.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
+  }
+  const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) {
+    throw new Error("Pass 2 (harness) did not return valid JSON.");
+  }
   try {
-    return JSON.parse(jsonMatch[0]);
+    const parsed = JSON.parse(jsonMatch[0]);
+    if (!parsed.claude_md || !parsed.commands) {
+      throw new Error("Harness missing required fields: claude_md, commands");
+    }
+    return parsed;
   } catch (err) {
     throw new Error(
-      `Failed to parse LLM response as JSON: ${err instanceof Error ? err.message : String(err)}
-Response started with: ${cleaned.slice(0, 200)}...`
+      `Failed to parse harness JSON: ${err instanceof Error ? err.message : String(err)}`
     );
   }
 }
@@ -928,15 +1114,17 @@ function classifyError(err, provider) {
   }
   return `${provider} API error: ${msg}`;
 }
-async function callLLM(config, userMessage) {
+async function callLLM(config, userMessage, options) {
+  const maxTokens = options?.maxTokens ?? 8192;
+  const systemPrompt = options?.systemPrompt ?? SYSTEM_PROMPT;
   const providerName = getProviderName(config.provider);
   if (config.provider === "anthropic") {
     const client2 = new Anthropic2({ apiKey: config.api_key });
     try {
       const response = await client2.messages.create({
         model: config.model,
-        max_tokens: 8192,
-        system: SYSTEM_PROMPT,
+        max_tokens: maxTokens,
+        system: systemPrompt,
         messages: [{ role: "user", content: userMessage }]
       });
       const textBlock = response.content.find((block) => block.type === "text");
@@ -955,9 +1143,9 @@ async function callLLM(config, userMessage) {
   try {
     const response = await client.chat.completions.create({
       model: config.model,
-      max_tokens: 8192,
+      max_tokens: maxTokens,
       messages: [
-        { role: "system", content: SYSTEM_PROMPT },
+        { role: "system", content: systemPrompt },
         { role: "user", content: userMessage }
       ]
     });
@@ -970,6 +1158,66 @@ async function callLLM(config, userMessage) {
     throw new Error(classifyError(err, providerName));
   }
 }
+function buildSettings(skeleton, registry) {
+  const selectedTools = skeleton.tools.map((t) => registry.find((r) => r.id === t.tool_id)).filter(Boolean);
+  const allow = ["Read", "Write", "Edit", "Bash(npm run *)", "Bash(npx *)"];
+  const deny = [
+    "Bash(rm -rf *)",
+    "Bash(curl * | sh)",
+    "Bash(wget * | sh)",
+    "Read(./.env)",
+    "Read(./secrets/**)"
+  ];
+  const hooks = {
+    PreToolUse: [
+      {
+        matcher: "Bash",
+        hooks: [
+          {
+            type: "command",
+            command: `CMD=$(cat | jq -r '.tool_input.command // empty') && echo "$CMD" | grep -qiE 'rm\\s+-rf\\s+/|DROP\\s+TABLE|curl.*\\|\\s*sh' && echo 'Blocked destructive command' >&2 && exit 2 || true`
+          }
+        ]
+      }
+    ],
+    PostCompact: [
+      {
+        matcher: "",
+        hooks: [
+          {
+            type: "prompt",
+            prompt: "Re-read CLAUDE.md and docs/SPRINT.md (if it exists) to restore project context after compaction."
+          }
+        ]
+      }
+    ]
+  };
+  const techStack = skeleton.outline.tech_stack.map((t) => t.toLowerCase());
+  if (techStack.some((t) => t.includes("typescript") || t.includes("javascript") || t.includes("react") || t.includes("next"))) {
+    hooks.PostToolUse = [
+      {
+        matcher: "Edit|Write",
+        hooks: [
+          {
+            type: "command",
+            command: `FILE=$(cat | jq -r '.tool_input.file_path // empty') && [ -n "$FILE" ] && npx prettier --write "$FILE" 2>/dev/null || true`
+          }
+        ]
+      }
+    ];
+  }
+  return { permissions: { allow, deny }, hooks };
+}
+function buildMcpConfig(skeleton, registry) {
+  const config = {};
+  for (const tool of skeleton.tools) {
+    const reg = registry.find((r) => r.id === tool.tool_id);
+    if (reg?.install.mcp_config) {
+      config[tool.tool_id] = reg.install.mcp_config;
+    }
+  }
+  return config;
+}
 function validateSpec(spec, onProgress) {
   const warnings = [];
   if (spec.tools.length > 8) {
@@ -995,17 +1243,52 @@ async function compile(intent, onProgress) {
   }
   onProgress?.("Loading tool registry...");
   const registry = await loadRegistry();
-  onProgress?.(`Compiling with ${config.provider} (${config.model})...`);
-  const userMessage = buildUserMessage(intent, registry);
-  const responseText = await callLLM(config, userMessage);
-  onProgress?.("Parsing environment spec...");
-  const parsed = parseSpecResponse(responseText);
+  onProgress?.("Analyzing workflow...");
+  const skeletonMsg = buildSkeletonMessage(intent, registry);
+  const skeletonText = await callLLM(config, skeletonMsg, {
+    maxTokens: 2048,
+    systemPrompt: SKELETON_PROMPT
+  });
+  const skeleton = parseSkeletonResponse(skeletonText);
+  onProgress?.("Generating environment...");
+  const harnessMsg = buildHarnessMessage(intent, skeleton);
+  let harness;
+  try {
+    const harnessText = await callLLM(config, harnessMsg, {
+      maxTokens: 8192,
+      systemPrompt: HARNESS_PROMPT
+    });
+    harness = parseHarnessResponse(harnessText);
+  } catch {
+    onProgress?.("Retrying with concise mode...");
+    const retryMsg = buildHarnessMessage(intent, skeleton, true);
+    const retryText = await callLLM(config, retryMsg, {
+      maxTokens: 8192,
+      systemPrompt: HARNESS_PROMPT
+    });
+    harness = parseHarnessResponse(retryText);
+  }
+  onProgress?.("Configuring tools...");
+  const settings = buildSettings(skeleton, registry);
+  const mcpConfig = buildMcpConfig(skeleton, registry);
   const spec = {
     id: `env_${crypto.randomUUID()}`,
     intent,
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
-    ...parsed,
-    autonomy_level: parsed.autonomy_level ?? 1
+    name: skeleton.name,
+    description: skeleton.description,
+    autonomy_level: 1,
+    tools: skeleton.tools,
+    harness: {
+      claude_md: harness.claude_md,
+      settings,
+      mcp_config: mcpConfig,
+      commands: harness.commands,
+      rules: harness.rules,
+      skills: harness.skills ?? {},
+      agents: harness.agents ?? {},
+      docs: harness.docs
+    }
   };
   validateSpec(spec, onProgress);
   await ensureDirs();