mustflow 1.15.97

package/dist/cli/lib/template-i18n.js

@@ -0,0 +1,265 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord } from './command-contract.js';
+import { readTomlFile } from './toml.js';
+const REQUIRED_STATUS_VALUES = ['current', 'stale', 'needs_review', 'missing'];
+function hasOwn(table, key) {
+    return Object.prototype.hasOwnProperty.call(table, key);
+}
+function isPositiveInteger(value) {
+    return Number.isInteger(value) && Number(value) > 0;
+}
+function isSafeRelativePath(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return false;
+    }
+    const normalized = value.replace(/\\/g, '/');
+    const segments = normalized.split('/').filter(Boolean);
+    if (path.posix.isAbsolute(normalized) || path.win32.isAbsolute(value)) {
+        return false;
+    }
+    return segments.length > 0 && segments.every((segment) => segment !== '.' && segment !== '..');
+}
+function readTable(table, key, label, issues) {
+    if (!hasOwn(table, key)) {
+        issues.push(`${label} is required`);
+        return undefined;
+    }
+    const value = table[key];
+    if (!isRecord(value)) {
+        issues.push(`${label} must be a TOML table`);
+        return undefined;
+    }
+    return value;
+}
+function readOptionalTable(table, key, label, issues) {
+    if (!hasOwn(table, key)) {
+        return undefined;
+    }
+    const value = table[key];
+    if (!isRecord(value)) {
+        issues.push(`${label} must be a TOML table`);
+        return undefined;
+    }
+    return value;
+}
+function readString(table, key, label, issues) {
+    if (typeof table[key] !== 'string' || table[key].trim().length === 0) {
+        issues.push(`${label} must be a string`);
+        return undefined;
+    }
+    return table[key];
+}
+function readPositiveInteger(table, key, label, issues) {
+    if (!isPositiveInteger(table[key])) {
+        issues.push(`${label} must be a positive integer`);
+        return undefined;
+    }
+    return table[key];
+}
+function readStringArray(table, key, label, issues) {
+    const value = table[key];
+    if (!Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)) {
+        issues.push(`${label} must be a non-empty string array`);
+        return undefined;
+    }
+    return value;
+}
+function validateExistingTemplatePath(templateRoot, relativePath, label, issues) {
+    if (!isSafeRelativePath(relativePath)) {
+        issues.push(`${label} must be a non-empty relative path`);
+        return undefined;
+    }
+    if (!existsSync(path.join(templateRoot, ...relativePath.split('/')))) {
+        issues.push(`${label} points to a missing file: ${relativePath}`);
+        return undefined;
+    }
+    return relativePath;
+}
+function parseMarkdownFrontmatter(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
+        return undefined;
+    }
+    const frontmatterStart = content.startsWith('---\r\n') ? 5 : 4;
+    const endMatch = /\r?\n---(?:\r?\n|$)/u.exec(content.slice(frontmatterStart));
+    if (!endMatch || endMatch.index === undefined) {
+        return undefined;
+    }
+    const frontmatter = {};
+    const endIndex = frontmatterStart + endMatch.index;
+    const lines = content.slice(frontmatterStart, endIndex).split(/\r?\n/u);
+    for (const line of lines) {
+        const match = /^([A-Za-z0-9_.-]+):\s*(.*?)\s*$/u.exec(line);
+        if (!match) {
+            continue;
+        }
+        frontmatter[match[1]] = match[2].replace(/^"(.*)"$/u, '$1');
+    }
+    return frontmatter;
+}
+function validateFrontmatterField(frontmatter, key, expected, label, issues) {
+    if (frontmatter[key] !== expected) {
+        issues.push(`${label}.frontmatter.${key} must be ${expected}`);
+    }
+}
+function validateMarkdownFrontmatter(templateRoot, relativePath, label, expectedDocumentId, expectedLocale, expectedCanonical, expectedRevision, issues) {
+    if (!relativePath.endsWith('.md')) {
+        return;
+    }
+    const absolutePath = path.join(templateRoot, ...relativePath.split('/'));
+    const frontmatter = parseMarkdownFrontmatter(absolutePath);
+    if (!frontmatter) {
+        issues.push(`${label}.frontmatter is required`);
+        return;
+    }
+    validateFrontmatterField(frontmatter, 'mustflow_doc', expectedDocumentId, label, issues);
+    validateFrontmatterField(frontmatter, 'locale', expectedLocale, label, issues);
+    validateFrontmatterField(frontmatter, 'canonical', String(expectedCanonical), label, issues);
+    if (expectedRevision !== undefined) {
+        validateFrontmatterField(frontmatter, 'revision', String(expectedRevision), label, issues);
+    }
+    else if (!isPositiveInteger(Number(frontmatter.revision))) {
+        issues.push(`${label}.frontmatter.revision must be a positive integer`);
+    }
+}
+function readTomlTable(filePath, label, issues) {
+    try {
+        const parsed = readTomlFile(filePath);
+        if (!isRecord(parsed)) {
+            issues.push(`${label} must contain a TOML table`);
+            return undefined;
+        }
+        return parsed;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(`Invalid TOML in ${label}: ${message}`);
+        return undefined;
+    }
+}
+function isLocalizedSourcePath(template, sourcePath, sourceLocale) {
+    if (!template.manifest.localesRoot) {
+        return false;
+    }
+    return sourcePath.replace(/\\/g, '/').startsWith(`${template.manifest.localesRoot}/${sourceLocale}/`);
+}
+function validateTranslationPathPrefix(template, documentSourcePath, sourceLocale, translationLocale, translationPath, issues) {
+    if (!isLocalizedSourcePath(template, documentSourcePath, sourceLocale) || !template.manifest.localesRoot) {
+        return;
+    }
+    const expectedPrefix = `${template.manifest.localesRoot}/${translationLocale}/`;
+    if (!translationPath.replace(/\\/g, '/').startsWith(expectedPrefix)) {
+        issues.push(`[documents.*.translations.${translationLocale}].path must start with ${expectedPrefix}`);
+    }
+}
+function validateTranslation(template, documentLabel, documentSourcePath, sourceLocale, revision, statusValues, translationLocale, translation, issues) {
+    const label = `${documentLabel}.translations.${translationLocale}`;
+    if (!isRecord(translation)) {
+        issues.push(`[${label}] must be a TOML table`);
+        return;
+    }
+    if (!template.manifest.locales.includes(translationLocale)) {
+        issues.push(`[${label}] locale must be listed in template manifest locales.available`);
+    }
+    if (translationLocale === sourceLocale) {
+        issues.push(`[${label}] locale must not equal the source locale`);
+    }
+    const status = readString(translation, 'status', `[${label}].status`, issues);
+    const sourceRevision = readPositiveInteger(translation, 'source_revision', `[${label}].source_revision`, issues);
+    const pathValue = translation.path;
+    if (status && !statusValues.has(status)) {
+        issues.push(`[${label}].status must be one of ${Array.from(statusValues).join(', ')}`);
+    }
+    if (revision && sourceRevision && sourceRevision > revision) {
+        issues.push(`[${label}].source_revision must not be greater than the source revision`);
+    }
+    if (status === 'current' && revision && sourceRevision && sourceRevision !== revision) {
+        issues.push(`[${label}].source_revision must equal the source revision when status is current`);
+    }
+    if (status === 'stale' && revision && sourceRevision && sourceRevision >= revision) {
+        issues.push(`[${label}].source_revision must be lower than the source revision when status is stale`);
+    }
+    if (status === 'missing') {
+        if (pathValue !== undefined && !isSafeRelativePath(pathValue)) {
+            issues.push(`[${label}].path must be a relative path when present`);
+        }
+        return;
+    }
+    const translationPath = validateExistingTemplatePath(template.templateRoot, pathValue, `[${label}].path`, issues);
+    if (translationPath) {
+        validateTranslationPathPrefix(template, documentSourcePath, sourceLocale, translationLocale, translationPath, issues);
+        validateMarkdownFrontmatter(template.templateRoot, translationPath, `[${label}]`, documentLabel.replace(/^documents\./u, ''), translationLocale, false, undefined, issues);
+    }
+}
+function validateDocument(template, documentId, document, sourceLocale, statusValues, issues) {
+    const label = `documents.${documentId}`;
+    if (!isRecord(document)) {
+        issues.push(`[${label}] must be a TOML table`);
+        return;
+    }
+    const source = validateExistingTemplatePath(template.templateRoot, document.source, `[${label}].source`, issues);
+    const documentSourceLocale = readString(document, 'source_locale', `[${label}].source_locale`, issues);
+    const revision = readPositiveInteger(document, 'revision', `[${label}].revision`, issues);
+    if (documentSourceLocale && documentSourceLocale !== sourceLocale) {
+        issues.push(`[${label}].source_locale must equal template source locale ${sourceLocale}`);
+    }
+    if (source) {
+        validateMarkdownFrontmatter(template.templateRoot, source, `[${label}]`, documentId, sourceLocale, true, revision, issues);
+    }
+    const translations = readOptionalTable(document, 'translations', `[${label}.translations]`, issues);
+    if (!translations || !source) {
+        return;
+    }
+    for (const [translationLocale, translation] of Object.entries(translations)) {
+        validateTranslation(template, label, source, sourceLocale, revision, statusValues, translationLocale, translation, issues);
+    }
+}
+export function validateTemplateI18n(template) {
+    const issues = [];
+    const manifestToml = readTomlTable(template.manifestPath, 'template manifest', issues);
+    if (!manifestToml) {
+        return issues;
+    }
+    const manifestI18n = readTable(manifestToml, 'i18n', '[manifest.i18n]', issues);
+    const manifestLocales = readTable(manifestToml, 'locales', '[manifest.locales]', issues);
+    if (!manifestI18n || !manifestLocales) {
+        return issues;
+    }
+    const metadataPath = validateExistingTemplatePath(template.templateRoot, manifestI18n.metadata, '[manifest.i18n].metadata', issues);
+    const manifestSourceLocale = readString(manifestI18n, 'source_locale', '[manifest.i18n].source_locale', issues);
+    const localesSourceLocale = readString(manifestLocales, 'source', '[manifest.locales].source', issues);
+    if (!metadataPath) {
+        return issues;
+    }
+    const i18nToml = readTomlTable(path.join(template.templateRoot, ...metadataPath.split('/')), metadataPath, issues);
+    if (!i18nToml) {
+        return issues;
+    }
+    readPositiveInteger(i18nToml, 'version', '[i18n].version', issues);
+    const sourceLocale = readString(i18nToml, 'source_locale', '[i18n].source_locale', issues);
+    const statusValues = readStringArray(i18nToml, 'status_values', '[i18n].status_values', issues);
+    const documents = readTable(i18nToml, 'documents', '[i18n.documents]', issues);
+    if (sourceLocale && manifestSourceLocale && sourceLocale !== manifestSourceLocale) {
+        issues.push('[i18n].source_locale must match [manifest.i18n].source_locale');
+    }
+    if (sourceLocale && localesSourceLocale && sourceLocale !== localesSourceLocale) {
+        issues.push('[i18n].source_locale must match [manifest.locales].source');
+    }
+    if (sourceLocale && !template.manifest.locales.includes(sourceLocale)) {
+        issues.push('[i18n].source_locale must be listed in template manifest locales.available');
+    }
+    if (!sourceLocale || !statusValues || !documents) {
+        return issues;
+    }
+    for (const requiredStatus of REQUIRED_STATUS_VALUES) {
+        if (!statusValues.includes(requiredStatus)) {
+            issues.push(`[i18n].status_values must include ${requiredStatus}`);
+        }
+    }
+    const allowedStatuses = new Set(statusValues);
+    for (const [documentId, document] of Object.entries(documents)) {
+        validateDocument(template, documentId, document, sourceLocale, allowedStatuses, issues);
+    }
+    return issues;
+}

package/dist/cli/lib/templates.js

@@ -0,0 +1,188 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'smol-toml';
+function readStringGroup(raw, label) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`Template manifest is missing table: ${label}`);
+    }
+    const group = raw;
+    if (typeof group.default !== 'string') {
+        throw new Error(`Template manifest is missing string field: ${label}.default`);
+    }
+    if (!Array.isArray(group.available) || group.available.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`Template manifest is missing string array field: ${label}.available`);
+    }
+    if (!group.available.includes(group.default)) {
+        throw new Error(`Template manifest ${label}.available must include ${label}.default`);
+    }
+    return {
+        defaultValue: group.default,
+        available: group.available,
+    };
+}
+function readStringArrayTable(raw, label) {
+    if (raw === undefined) {
+        return {};
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`Template manifest ${label} must be a table`);
+    }
+    const table = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+            throw new Error(`Template manifest ${label}.${key} must be a string array`);
+        }
+        table[key] = value;
+    }
+    return table;
+}
+function normalizeTemplateTargetPath(relativePath) {
+    return relativePath.replaceAll('\\', '/');
+}
+function skillNameForTemplatePath(relativePath) {
+    const match = /^\.mustflow\/skills\/([^/]+)\//u.exec(normalizeTemplateTargetPath(relativePath));
+    return match?.[1];
+}
+function templateSkillNames(creates) {
+    return [
+        ...new Set(creates
+            .map((relativePath) => {
+            const normalizedPath = normalizeTemplateTargetPath(relativePath);
+            const match = /^\.mustflow\/skills\/([^/]+)\/SKILL\.md$/u.exec(normalizedPath);
+            return match?.[1];
+        })
+            .filter((value) => Boolean(value))),
+    ].sort();
+}
+function resolveSkillProfileSkills(manifest, profile) {
+    return manifest.skillProfiles[profile] ?? templateSkillNames(manifest.creates);
+}
+function shouldIncludeTemplatePath(manifest, relativePath, profile) {
+    const normalizedPath = normalizeTemplateTargetPath(relativePath);
+    const skillName = skillNameForTemplatePath(normalizedPath);
+    if (!skillName) {
+        return true;
+    }
+    return resolveSkillProfileSkills(manifest, profile).includes(skillName);
+}
+function filterSkillIndexContent(content, selectedSkills) {
+    const selectedSkillSet = new Set(selectedSkills);
+    return content
+        .split(/\r?\n/u)
+        .filter((line) => {
+        const match = /`\.mustflow\/skills\/([^/]+)\/SKILL\.md`/u.exec(line);
+        return !match || selectedSkillSet.has(match[1] ?? '');
+    })
+        .join('\n');
+}
+function isAllowedTemplateCreateTarget(relativePath) {
+    const normalizedPath = normalizeTemplateTargetPath(relativePath);
+    if (normalizedPath.startsWith('/') ||
+        normalizedPath.startsWith('../') ||
+        normalizedPath.includes('/../') ||
+        normalizedPath.endsWith('/..')) {
+        return false;
+    }
+    return normalizedPath === 'AGENTS.md' || normalizedPath.startsWith('.mustflow/');
+}
+/**
+ * mf:anchor cli.templates.install-surface
+ * purpose: Keep template installation and update targets inside the mustflow-managed surface.
+ * search: template manifest, creates, AGENTS.md, .mustflow, install surface
+ * invariant: Template creates targets are limited to AGENTS.md and .mustflow paths.
+ * risk: config, security
+ */
+function validateTemplateCreateTargets(creates) {
+    const invalidTarget = creates.find((relativePath) => !isAllowedTemplateCreateTarget(relativePath));
+    if (!invalidTarget) {
+        return;
+    }
+    throw new Error(`Template manifest creates target "${invalidTarget}" outside the mustflow-managed install surface. ` +
+        'Template installation and updates may write only AGENTS.md and .mustflow/**.');
+}
+function readManifest(manifestPath) {
+    const raw = parse(readFileSync(manifestPath, 'utf8'));
+    if (typeof raw.id !== 'string') {
+        throw new Error(`Template manifest is missing string field: id`);
+    }
+    if (typeof raw.version !== 'string') {
+        throw new Error(`Template manifest is missing string field: version`);
+    }
+    if (!Array.isArray(raw.creates) || raw.creates.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`Template manifest is missing string array field: creates`);
+    }
+    validateTemplateCreateTargets(raw.creates);
+    const profiles = readStringGroup(raw.profiles, 'profiles');
+    const locales = readStringGroup(raw.locales, 'locales');
+    const commonRoot = typeof raw.common_root === 'string' ? raw.common_root : raw.files_root;
+    const skillProfiles = readStringArrayTable(raw.skill_profiles, 'skill_profiles');
+    const availableSkillNames = new Set(templateSkillNames(raw.creates));
+    if (typeof commonRoot !== 'string') {
+        throw new Error(`Template manifest is missing string field: common_root`);
+    }
+    if (raw.locales_root !== undefined && typeof raw.locales_root !== 'string') {
+        throw new Error(`Template manifest locales_root must be a string when present`);
+    }
+    for (const [profile, skills] of Object.entries(skillProfiles)) {
+        if (!profiles.available.includes(profile)) {
+            throw new Error(`Template manifest skill_profiles.${profile} is not listed in profiles.available`);
+        }
+        for (const skill of skills) {
+            if (!availableSkillNames.has(skill)) {
+                throw new Error(`Template manifest skill_profiles.${profile} references unknown skill: ${skill}`);
+            }
+        }
+    }
+    return {
+        id: raw.id,
+        version: raw.version,
+        commonRoot,
+        localesRoot: raw.locales_root,
+        creates: raw.creates,
+        defaultProfile: profiles.defaultValue,
+        profiles: profiles.available,
+        skillProfiles,
+        defaultLocale: locales.defaultValue,
+        locales: locales.available,
+    };
+}
+export function getDefaultTemplate() {
+    const templateRoot = path.resolve(process.env.MUSTFLOW_DEV_TEMPLATE_ROOT ?? fileURLToPath(new URL('../../../templates/default', import.meta.url)));
+    const manifestPath = path.join(templateRoot, 'manifest.toml');
+    const manifest = readManifest(manifestPath);
+    return {
+        manifestPath,
+        templateRoot,
+        manifest,
+    };
+}
+export function getTemplateFiles(template, locale = template.manifest.defaultLocale, profile = template.manifest.defaultProfile) {
+    const commonRoot = path.join(template.templateRoot, template.manifest.commonRoot);
+    const localeRoot = template.manifest.localesRoot ? path.join(template.templateRoot, template.manifest.localesRoot, locale) : undefined;
+    const selectedSkills = resolveSkillProfileSkills(template.manifest, profile);
+    return template.manifest.creates.filter((relativePath) => shouldIncludeTemplatePath(template.manifest, relativePath, profile)).map((relativePath) => {
+        const localePath = localeRoot ? path.join(localeRoot, ...relativePath.split('/')) : undefined;
+        const commonPath = path.join(commonRoot, ...relativePath.split('/'));
+        const content = relativePath === '.mustflow/skills/INDEX.md'
+            ? filterSkillIndexContent(readFileSync(localePath && existsSync(localePath) ? localePath : commonPath, 'utf8'), selectedSkills)
+            : undefined;
+        if (localePath && existsSync(localePath)) {
+            return {
+                relativePath,
+                sourcePath: localePath,
+                sourceKind: 'locale',
+                content,
+            };
+        }
+        if (existsSync(commonPath)) {
+            return {
+                relativePath,
+                sourcePath: commonPath,
+                sourceKind: template.manifest.localesRoot ? 'common' : 'legacy',
+                content,
+            };
+        }
+        throw new Error(`Template source missing for ${relativePath} in locale ${locale}`);
+    });
+}

package/dist/cli/lib/toml.js

@@ -0,0 +1 @@
+export { parseTomlText, readTomlFile, stringifyToml } from '../../core/toml.js';