@minionry/minion 0.7.36

package/dist/server/services/plan/template-instantiator.js

@@ -0,0 +1,516 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { compareTemplates } from './template-diff.js';
+import { readTemplateManifest, writeTemplateManifest } from './template-manifest.js';
+export function parseTemplate(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Template is not valid JSON: ${msg}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Template root must be a JSON object');
+    }
+    return parsed;
+}
+export function loadTemplate(filePath) {
+    if (!existsSync(filePath)) {
+        throw new Error(`Template file not found: ${filePath}`);
+    }
+    return parseTemplate(readFileSync(filePath, 'utf-8'));
+}
+const VALID_TYPES = new Set(['issue', 'epic', 'bug', 'task']);
+const VALID_PRIORITIES = new Set(['P0', 'P1', 'P2', 'P3']);
+const VALID_REVIEW_GATES = new Set(['none', 'auto', 'required']);
+const VALID_OUTPUT_TYPES = new Set(['code', 'document', 'auto']);
+const VALID_BOARD_STATUSES = new Set(['draft', 'active', 'completed', 'archived']);
+function validateTopLevel(template, push) {
+    if (!template.template_id || typeof template.template_id !== 'string') {
+        push('missing_field', 'template_id is required and must be a string', 'template_id');
+    }
+    if (!template.name || typeof template.name !== 'string') {
+        push('missing_field', 'name is required and must be a string', 'name');
+    }
+}
+function validateBoard(template, push) {
+    if (!template.board || typeof template.board !== 'object') {
+        push('missing_field', 'board object is required', 'board');
+        return;
+    }
+    if (!template.board.title || typeof template.board.title !== 'string') {
+        push('missing_field', 'board.title is required', 'board.title');
+    }
+    if (typeof template.board.goal !== 'string') {
+        push('missing_field', 'board.goal is required', 'board.goal');
+    }
+    if (template.board.status && !VALID_BOARD_STATUSES.has(template.board.status)) {
+        push('invalid_value', `board.status must be one of draft|active|completed|archived`, 'board.status');
+    }
+}
+function validateVariables(template, push) {
+    if (!template.variables)
+        return;
+    if (!Array.isArray(template.variables)) {
+        push('invalid_value', 'variables must be an array', 'variables');
+        return;
+    }
+    const declared = new Set();
+    template.variables.forEach((v, idx) => {
+        if (!v || typeof v !== 'object') {
+            push('invalid_value', `variables[${idx}] must be an object`, `variables[${idx}]`);
+            return;
+        }
+        if (!v.name || typeof v.name !== 'string') {
+            push('missing_field', `variables[${idx}].name is required`, `variables[${idx}].name`);
+            return;
+        }
+        if (declared.has(v.name)) {
+            push('duplicate_id', `Duplicate variable name: ${v.name}`, `variables[${idx}].name`);
+        }
+        declared.add(v.name);
+    });
+}
+function validateIssueId(issue, ptr, seenIds, push) {
+    if (!issue.id || typeof issue.id !== 'string') {
+        push('missing_field', `issue id is required`, ptr('id'));
+        return;
+    }
+    if (seenIds.has(issue.id)) {
+        push('duplicate_id', `Duplicate issue id: ${issue.id}`, ptr('id'));
+        return;
+    }
+    seenIds.add(issue.id);
+}
+function validateIssueEnums(issue, ptr, push) {
+    if (issue.type && !VALID_TYPES.has(issue.type)) {
+        push('invalid_value', `issue.type must be issue|epic|bug|task`, ptr('type'));
+    }
+    if (issue.priority && !VALID_PRIORITIES.has(issue.priority)) {
+        push('invalid_value', `issue.priority must be P0|P1|P2|P3`, ptr('priority'));
+    }
+    if (issue.review_gate && !VALID_REVIEW_GATES.has(issue.review_gate)) {
+        push('invalid_value', `issue.review_gate must be none|auto|required`, ptr('review_gate'));
+    }
+    if (issue.output_type && !VALID_OUTPUT_TYPES.has(issue.output_type)) {
+        push('invalid_value', `issue.output_type must be code|document|auto`, ptr('output_type'));
+    }
+}
+function validateIssueFields(issue, idx, seenIds, push) {
+    const ptr = (f) => `issues[${idx}].${f}`;
+    if (!issue || typeof issue !== 'object') {
+        push('invalid_value', `issues[${idx}] must be an object`, `issues[${idx}]`);
+        return;
+    }
+    validateIssueId(issue, ptr, seenIds, push);
+    if (!issue.title || typeof issue.title !== 'string') {
+        push('missing_field', `issue.title is required`, ptr('title'));
+    }
+    validateIssueEnums(issue, ptr, push);
+}
+function validateIdList(ids, field, ptr, seenIds, push) {
+    for (const id of ids ?? []) {
+        if (!seenIds.has(id)) {
+            push('bad_dependency', `${field} "${id}" not defined in template`, ptr(field));
+        }
+    }
+}
+function validateIssueRefs(issue, idx, seenIds, push) {
+    const ptr = (f) => `issues[${idx}].${f}`;
+    if (issue.epic && !seenIds.has(issue.epic)) {
+        push('bad_dependency', `epic "${issue.epic}" not defined in template`, ptr('epic'));
+    }
+    validateIdList(issue.blocked_by, 'blocked_by', ptr, seenIds, push);
+    validateIdList(issue.blocks, 'blocks', ptr, seenIds, push);
+    validateIdList(issue.children, 'children', ptr, seenIds, push);
+    for (const dep of issue.blocked_by ?? []) {
+        if (dep === issue.id) {
+            push('bad_dependency', `issue cannot block itself`, ptr('blocked_by'));
+        }
+    }
+}
+export function validateTemplate(template) {
+    const errors = [];
+    const push = (code, message, pointer) => {
+        errors.push(pointer ? { code, message, pointer } : { code, message });
+    };
+    validateTopLevel(template, push);
+    validateBoard(template, push);
+    validateVariables(template, push);
+    if (!Array.isArray(template.issues)) {
+        push('missing_field', 'issues must be an array', 'issues');
+        return { valid: errors.length === 0, errors };
+    }
+    if (template.issues.length === 0) {
+        push('missing_field', 'issues must contain at least one entry', 'issues');
+    }
+    const seenIds = new Set();
+    for (let i = 0; i < template.issues.length; i++) {
+        validateIssueFields(template.issues[i], i, seenIds, push);
+    }
+    for (let i = 0; i < template.issues.length; i++) {
+        validateIssueRefs(template.issues[i], i, seenIds, push);
+    }
+    return { valid: errors.length === 0, errors };
+}
+const VAR_PATTERN = /\{\{\s*(\w+)\s*\}\}/g;
+export function resolveVariables(template, supplied = {}) {
+    const resolved = {};
+    for (const v of template.variables ?? []) {
+        const value = supplied[v.name] ?? v.default;
+        if (value === undefined) {
+            if (v.required) {
+                throw new Error(`Template variable "${v.name}" is required but no value was supplied`);
+            }
+            continue;
+        }
+        resolved[v.name] = String(value);
+    }
+    for (const [k, val] of Object.entries(supplied)) {
+        if (!(k in resolved))
+            resolved[k] = String(val);
+    }
+    return resolved;
+}
+export function substitute(input, variables) {
+    if (!input)
+        return input;
+    return input.replace(VAR_PATTERN, (match, key) => key in variables ? variables[key] : match);
+}
+function quoteYamlString(value) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+function yamlList(items) {
+    if (items.length === 0)
+        return '[]';
+    return `[${items.map(i => quoteYamlString(i)).join(', ')}]`;
+}
+function renderAcceptanceCriteria(items) {
+    if (items.length === 0)
+        return '';
+    return items.map(c => `- [ ] ${c}`).join('\n');
+}
+function renderFilesToModify(items) {
+    if (items.length === 0)
+        return '';
+    return items.map(f => `- ${f}`).join('\n');
+}
+function renderOutputHistory(entries) {
+    if (entries.length === 0)
+        return '';
+    return entries
+        .map(e => {
+        const linkText = e.title ?? e.sessionId;
+        return `- ${e.timestamp} — [${linkText}](minionry://output/${e.sessionId}) — ${e.status}`;
+    })
+        .join('\n');
+}
+function resolveIssueRefs(issue, issuePaths) {
+    const map = (ids) => (ids ?? []).map(id => issuePaths[id]).filter((p) => Boolean(p));
+    return {
+        epicPath: issue.epic ? (issuePaths[issue.epic] ?? null) : null,
+        blockedByPaths: map(issue.blocked_by),
+        blocksPaths: map(issue.blocks),
+        childrenPaths: map(issue.children),
+    };
+}
+function renderIssueFrontMatter(issue, title, refs, created) {
+    const type = issue.type ?? 'issue';
+    const priority = issue.priority ?? 'P2';
+    const reviewGate = issue.review_gate ?? 'auto';
+    const outputType = issue.output_type ?? 'auto';
+    const lines = [
+        '---',
+        `id: ${issue.id}`,
+        `title: ${quoteYamlString(title)}`,
+        `type: ${type}`,
+        `status: todo`,
+        `priority: ${priority}`,
+    ];
+    if (issue.estimate != null)
+        lines.push(`estimate: ${issue.estimate}`);
+    lines.push(`labels: ${yamlList(issue.labels ?? [])}`);
+    if (refs.epicPath)
+        lines.push(`epic: ${refs.epicPath}`);
+    lines.push(`created: ${quoteYamlString(created)}`);
+    lines.push(`blocked_by: ${yamlList(refs.blockedByPaths)}`);
+    lines.push(`blocks: ${yamlList(refs.blocksPaths)}`);
+    if (type === 'epic')
+        lines.push(`children: ${yamlList(refs.childrenPaths)}`);
+    lines.push(`review_gate: ${reviewGate}`);
+    lines.push(`output_type: ${outputType}`);
+    if (issue.output_file)
+        lines.push(`output_file: ${quoteYamlString(issue.output_file)}`);
+    if (issue.model)
+        lines.push(`model: ${issue.model}`);
+    if (issue.effort_level)
+        lines.push(`effort_level: ${issue.effort_level}`);
+    if (issue.fast_mode != null)
+        lines.push(`fast_mode: ${issue.fast_mode}`);
+    lines.push('---');
+    return lines.join('\n');
+}
+export function renderIssueMarkdown(issue, variables, issuePaths, created) {
+    const title = substitute(issue.title, variables);
+    const description = substitute(issue.description ?? '', variables);
+    const technicalNotes = substitute(issue.technical_notes ?? '', variables);
+    const refs = resolveIssueRefs(issue, issuePaths);
+    const fm = renderIssueFrontMatter(issue, title, refs, created);
+    const body = ['', `# ${issue.id}: ${title}`, ''];
+    body.push('## Description', '', description || '(see parent epic or board goal)', '');
+    body.push('## Acceptance Criteria', '');
+    const ac = renderAcceptanceCriteria(issue.acceptance_criteria ?? []);
+    body.push(ac || '- [ ] (define acceptance criteria)', '');
+    if (technicalNotes) {
+        body.push('## Technical Notes', '', technicalNotes, '');
+    }
+    const files = renderFilesToModify(issue.files_to_modify ?? []);
+    if (files) {
+        body.push('## Files to Modify', '', files, '');
+    }
+    const historyEntries = issue.output_history ?? [];
+    const historyContent = renderOutputHistory(historyEntries);
+    body.push('## Output History', '');
+    if (historyContent)
+        body.push(historyContent, '');
+    return `${fm}\n${body.join('\n')}`;
+}
+function renderBoardMarkdown(template, boardId, variables, created) {
+    const title = substitute(template.board.title, variables);
+    const goal = substitute(template.board.goal, variables);
+    const status = template.board.status ?? 'draft';
+    const fmLines = [
+        '---',
+        `id: ${boardId}`,
+        `title: ${quoteYamlString(title)}`,
+        `status: ${status}`,
+        `created: ${quoteYamlString(created)}`,
+        `completed_at: null`,
+        `goal: ${quoteYamlString(goal)}`,
+    ];
+    if (template.board.max_parallel_agents != null) {
+        fmLines.push(`max_parallel_agents: ${template.board.max_parallel_agents}`);
+    }
+    if (template.board.quality_gate != null) {
+        fmLines.push(`quality_gate: ${template.board.quality_gate}`);
+    }
+    fmLines.push('---');
+    const body = ['', `# ${title}`, '', '## Goal', '', goal, ''];
+    return `${fmLines.join('\n')}\n${body.join('\n')}`;
+}
+function renderStateMarkdown(template, issuePaths, variables) {
+    const issuesById = new Map(template.issues.map(i => [i.id, i]));
+    const ready = [];
+    const blocked = [];
+    for (const issue of template.issues) {
+        const path = issuePaths[issue.id];
+        const title = substitute(issue.title, variables);
+        const blockers = issue.blocked_by ?? [];
+        const unmetBlockers = blockers.filter(b => {
+            const dep = issuesById.get(b);
+            return !!dep;
+        });
+        const line = `- [${issue.id}](${path}) — ${title}`;
+        if (unmetBlockers.length > 0) {
+            blocked.push(`${line} ← blocked by ${unmetBlockers.join(', ')}`);
+        }
+        else {
+            ready.push(line);
+        }
+    }
+    const fm = [
+        '---',
+        `project: ../../project.md`,
+        `board: board.md`,
+        `paused: false`,
+        '---',
+    ].join('\n');
+    const body = [
+        '',
+        `# Board State`,
+        '',
+        '## Ready to Work',
+        '',
+        ready.join('\n') || '_(empty — all issues are blocked)_',
+        '',
+        '## In Progress',
+        '',
+        '## Blocked',
+        '',
+        blocked.join('\n') || '_(none)_',
+        '',
+        '## Recently Completed',
+        '',
+        '## Warnings',
+        '',
+    ].join('\n');
+    return `${fm}\n${body}`;
+}
+export function instantiateTemplate(template, options) {
+    const validation = validateTemplate(template);
+    if (!validation.valid) {
+        const summary = validation.errors.map(e => `${e.pointer ?? '<root>'}: ${e.message}`).join('; ');
+        throw new Error(`Template is invalid: ${summary}`);
+    }
+    const { pmDir, boardId } = options;
+    const failIfExists = options.failIfExists ?? true;
+    const variables = resolveVariables(template, options.variables);
+    const source = options.source;
+    const boardDir = join(pmDir, 'boards', boardId);
+    if (existsSync(boardDir) && failIfExists) {
+        throw new Error(`Board directory already exists: ${boardDir}`);
+    }
+    const backlogDir = join(boardDir, 'backlog');
+    const outDir = join(boardDir, 'out');
+    const reviewsDir = join(boardDir, 'reviews');
+    const logsDir = join(boardDir, 'logs');
+    for (const dir of [backlogDir, outDir, reviewsDir, logsDir]) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const issuePaths = {};
+    for (const issue of template.issues) {
+        issuePaths[issue.id] = `backlog/${issue.id}.md`;
+    }
+    const created = new Date().toISOString().split('T')[0];
+    const filesWritten = [];
+    const boardPath = join(boardDir, 'board.md');
+    writeFileSync(boardPath, renderBoardMarkdown(template, boardId, variables, created), 'utf-8');
+    filesWritten.push(boardPath);
+    const statePath = join(boardDir, 'STATE.md');
+    writeFileSync(statePath, renderStateMarkdown(template, issuePaths, variables), 'utf-8');
+    filesWritten.push(statePath);
+    for (const issue of template.issues) {
+        const filePath = join(backlogDir, `${issue.id}.md`);
+        writeFileSync(filePath, renderIssueMarkdown(issue, variables, issuePaths, created), 'utf-8');
+        filesWritten.push(filePath);
+    }
+    if (source || template.version) {
+        const manifest = {
+            templateId: template.template_id,
+            version: template.version ?? '0.0.0',
+            installedAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            pinned: false,
+            source,
+            history: [],
+        };
+        const manifestPath = writeTemplateManifest(boardDir, manifest);
+        filesWritten.push(manifestPath);
+    }
+    return { boardId, boardDir, filesWritten, issuePaths };
+}
+export { compareSemver, isSemver, parseSemver, } from './template-diff.js';
+export { setTemplateInstallPinned, templateManifestPath } from './template-manifest.js';
+export { compareTemplates, readTemplateManifest, writeTemplateManifest };
+function issueHasProgress(content) {
+    const match = content.match(/^status:\s*([a-z_-]+)\s*$/im);
+    if (!match)
+        return false;
+    const status = match[1].trim().toLowerCase();
+    return status !== 'todo';
+}
+function applyIssueUpdate(issue, filePath, ctx) {
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, renderIssueMarkdown(issue, ctx.variables, ctx.issuePaths, ctx.now), 'utf-8');
+        return 'added';
+    }
+    const content = readFileSync(filePath, 'utf-8');
+    if (ctx.preserveProgress && issueHasProgress(content)) {
+        return 'preserved';
+    }
+    writeFileSync(filePath, renderIssueMarkdown(issue, ctx.variables, ctx.issuePaths, ctx.now), 'utf-8');
+    return 'updated';
+}
+function validateUpdatePreconditions(newTemplate, pmDir, boardId) {
+    const validation = validateTemplate(newTemplate);
+    if (!validation.valid) {
+        const summary = validation.errors.map(e => `${e.pointer ?? '<root>'}: ${e.message}`).join('; ');
+        throw new Error(`New template is invalid: ${summary}`);
+    }
+    const boardDir = join(pmDir, 'boards', boardId);
+    if (!existsSync(boardDir)) {
+        throw new Error(`Board directory does not exist: ${boardDir}`);
+    }
+    const manifest = readTemplateManifest(pmDir, boardId);
+    if (!manifest) {
+        throw new Error(`No install manifest found for ${boardId} — nothing to update`);
+    }
+    if (manifest.templateId !== newTemplate.template_id) {
+        throw new Error(`Cannot update: manifest templateId (${manifest.templateId}) does not match new template (${newTemplate.template_id})`);
+    }
+    return { boardDir, manifest };
+}
+export function updateInstantiatedBoard(newTemplate, options) {
+    const { pmDir, boardId } = options;
+    const preserveProgress = options.preserveProgress ?? true;
+    const kind = options.kind ?? 'update';
+    const { boardDir, manifest } = validateUpdatePreconditions(newTemplate, pmDir, boardId);
+    const oldTemplateStub = {
+        template_id: manifest.templateId,
+        name: manifest.templateId,
+        version: manifest.version,
+        board: { title: '', goal: '' },
+        issues: [],
+    };
+    const variables = resolveVariables(newTemplate, options.variables);
+    const issuePaths = {};
+    for (const issue of newTemplate.issues) {
+        issuePaths[issue.id] = `backlog/${issue.id}.md`;
+    }
+    const backlogDir = join(boardDir, 'backlog');
+    if (!existsSync(backlogDir))
+        mkdirSync(backlogDir, { recursive: true });
+    const added = [];
+    const updated = [];
+    const preserved = [];
+    const filesWritten = [];
+    const now = new Date().toISOString().split('T')[0];
+    const boardPath = join(boardDir, 'board.md');
+    writeFileSync(boardPath, renderBoardMarkdown(newTemplate, boardId, variables, now), 'utf-8');
+    filesWritten.push(boardPath);
+    for (const issue of newTemplate.issues) {
+        const filePath = join(backlogDir, `${issue.id}.md`);
+        const outcome = applyIssueUpdate(issue, filePath, { variables, issuePaths, now, preserveProgress });
+        if (outcome === 'preserved') {
+            preserved.push(issue.id);
+            continue;
+        }
+        filesWritten.push(filePath);
+        (outcome === 'added' ? added : updated).push(issue.id);
+    }
+    const diff = compareTemplates(oldTemplateStub, newTemplate);
+    const nowIso = new Date().toISOString();
+    const nextManifest = {
+        ...manifest,
+        version: newTemplate.version ?? manifest.version,
+        updatedAt: nowIso,
+        source: options.source ?? manifest.source,
+        history: [
+            ...manifest.history,
+            {
+                version: manifest.version,
+                switchedAt: nowIso,
+                kind,
+                templateRowId: manifest.source?.templateRowId,
+            },
+        ],
+    };
+    const manifestPath = writeTemplateManifest(boardDir, nextManifest);
+    filesWritten.push(manifestPath);
+    return {
+        boardId,
+        boardDir,
+        from: { templateId: manifest.templateId, version: manifest.version },
+        to: { templateId: newTemplate.template_id, version: newTemplate.version ?? manifest.version },
+        added,
+        updated,
+        preserved,
+        removed: diff.issuesRemoved.map(i => i.id),
+        filesWritten,
+        diff,
+    };
+}

package/dist/server/services/plan/template-manifest.js

@@ -0,0 +1,56 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const MANIFEST_FILENAME = '.template.json';
+export function templateManifestPath(pmDir, boardId) {
+    return join(pmDir, 'boards', boardId, MANIFEST_FILENAME);
+}
+export function readTemplateManifest(pmDir, boardId) {
+    const path = templateManifestPath(pmDir, boardId);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (typeof parsed.templateId !== 'string' || typeof parsed.version !== 'string')
+            return null;
+        return {
+            templateId: parsed.templateId,
+            version: parsed.version,
+            installedAt: parsed.installedAt ?? new Date().toISOString(),
+            updatedAt: parsed.updatedAt ?? parsed.installedAt ?? new Date().toISOString(),
+            pinned: Boolean(parsed.pinned),
+            source: parsed.source,
+            history: Array.isArray(parsed.history) ? parsed.history : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeTemplateManifest(boardDir, manifest) {
+    const path = join(boardDir, MANIFEST_FILENAME);
+    writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+    return path;
+}
+export function setTemplateInstallPinned(pmDir, boardId, pinned) {
+    const manifest = readTemplateManifest(pmDir, boardId);
+    if (!manifest)
+        return null;
+    const next = {
+        ...manifest,
+        pinned,
+        updatedAt: new Date().toISOString(),
+    };
+    writeTemplateManifest(join(pmDir, 'boards', boardId), next);
+    return next;
+}

package/dist/server/services/plan/template-types.js

@@ -0,0 +1,3 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export {};