@kontourai/flow-agents 0.1.1

package/build/src/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { basename } from "node:path";
+import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
+import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
+import { main as flowKit } from "./cli/flow-kit.js";
+import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
+import { main as init } from "./cli/init.js";
+import { main as promoteWorkflowArtifact } from "./cli/promote-workflow-artifact.js";
+import { main as publishChange } from "./cli/publish-change-helper.js";
+import { main as pullWorkProvider } from "./cli/pull-work-provider.js";
+import { main as telemetryDoctor } from "./cli/telemetry-doctor.js";
+import { main as usageFeedback } from "./cli/usage-feedback.js";
+import { main as veritasGovernance } from "./cli/veritas-governance.js";
+import { main as workflowArtifactCleanupAudit } from "./cli/workflow-artifact-cleanup-audit.js";
+import { main as buildBundles } from "./tools/build-universal-bundles.js";
+import { main as contextMap } from "./tools/generate-context-map.js";
+import { main as filterInstalledPacks } from "./tools/filter-installed-packs.js";
+import { main as validateSource } from "./tools/validate-source-tree.js";
+import { main as validatePackage } from "./tools/validate-package.js";
+import { main as validateHookInfluence } from "./cli/validate-hook-influence.js";
+import { main as runtimeAdapter } from "./cli/runtime-adapter.js";
+const availableCommands = new Map([
+    ["build-bundles", () => buildBundles()],
+    ["console-learning-projection", consoleLearningProjection],
+    ["context-map", contextMap],
+    ["effective-backlog-settings", effectiveBacklogSettings],
+    ["filter-installed-packs", filterInstalledPacks],
+    ["fixture-retirement-audit", fixtureRetirementAudit],
+    ["flow-kit", flowKit],
+    ["init", init],
+    ["promote-workflow-artifact", promoteWorkflowArtifact],
+    ["publish-change", publishChange],
+    ["pull-work-provider", pullWorkProvider],
+    ["runtime-adapter", runtimeAdapter],
+    ["telemetry-doctor", telemetryDoctor],
+    ["usage-feedback", usageFeedback],
+    ["veritas-governance", veritasGovernance],
+    ["validate-package", validatePackage],
+    ["validate-hook-influence", validateHookInfluence],
+    ["validate-source", validateSource],
+    ["workflow-artifact-cleanup-audit", workflowArtifactCleanupAudit],
+]);
+const aliases = new Map([
+    ["flow-agents-build-bundles", "build-bundles"],
+    ["flow-agents-console-learning-projection", "console-learning-projection"],
+    ["flow-agents-context-map", "context-map"],
+    ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
+    ["flow-agents-filter-installed-packs", "filter-installed-packs"],
+    ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
+    ["flow-agents-flow-kit", "flow-kit"],
+    ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],
+    ["flow-agents-publish-change", "publish-change"],
+    ["flow-agents-pull-work-provider", "pull-work-provider"],
+    ["flow-agents-runtime-adapter", "runtime-adapter"],
+    ["flow-agents-telemetry-doctor", "telemetry-doctor"],
+    ["flow-agents-usage-feedback", "usage-feedback"],
+    ["flow-agents-veritas-governance", "veritas-governance"],
+    ["flow-agents-validate-hook-influence", "validate-hook-influence"],
+    ["flow-agents-validate-source", "validate-source"],
+    ["flow-agents-workflow-artifact-cleanup-audit", "workflow-artifact-cleanup-audit"],
+]);
+function printHelp() {
+    console.log("Usage: flow-agents <command> [args]");
+    console.log("");
+    console.log("Available commands:");
+    for (const name of availableCommands.keys())
+        console.log(`  ${name}`);
+}
+const invokedAs = basename(process.argv[1] ?? "flow-agents");
+const commandName = aliases.get(invokedAs) ?? process.argv[2];
+const forwardedArgs = aliases.has(invokedAs) ? process.argv.slice(2) : process.argv.slice(3);
+async function run() {
+    if (!commandName || commandName === "--help" || commandName === "-h" || commandName === "help") {
+        printHelp();
+        return 0;
+    }
+    if (commandName === "commands" || commandName === "list") {
+        for (const name of availableCommands.keys())
+            console.log(name);
+        return 0;
+    }
+    const availableCommand = availableCommands.get(commandName);
+    if (availableCommand)
+        return await availableCommand(forwardedArgs);
+    console.error(`Unknown flow-agents command: ${commandName}`);
+    console.error("Run `flow-agents --help` for registered commands.");
+    return 64;
+}
+process.exit(await run());

package/build/src/flow-kit/validate.js

@@ -0,0 +1,75 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readJson } from "../lib/fs.js";
+const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
+export function validateKitRepository(kitDir) {
+    const errors = [];
+    const manifestPath = path.join(kitDir, "kit.json");
+    let manifest;
+    try {
+        manifest = readJson(manifestPath);
+    }
+    catch (error) {
+        errors.push(`${manifestPath}: invalid JSON: ${error.message}`);
+        return errors;
+    }
+    if (manifest.schema_version !== "1.0")
+        errors.push(`${manifestPath}: .schema_version must be "1.0"`);
+    if (typeof manifest.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.id)) {
+        errors.push(`${manifestPath}: .id must be a stable kebab-case string`);
+    }
+    if (typeof manifest.name !== "string" || !manifest.name.trim())
+        errors.push(`${manifestPath}: .name must be a non-empty string`);
+    for (const section of ASSET_CLASSES) {
+        const entries = manifest[section];
+        if (entries === undefined)
+            continue;
+        if (!Array.isArray(entries)) {
+            errors.push(`${manifestPath}: .${section} must be a list`);
+            continue;
+        }
+        const seen = new Set();
+        entries.forEach((entry, index) => {
+            if (typeof entry !== "object" || entry === null) {
+                errors.push(`${manifestPath}: ${section}[${index}] must be an object`);
+                return;
+            }
+            const record = entry;
+            const id = record.id;
+            const rel = record.path;
+            if (typeof id === "string") {
+                if (seen.has(id))
+                    errors.push(`${manifestPath}: ${section}[${index}].id duplicates`);
+                seen.add(id);
+            }
+            if (typeof rel !== "string" || !rel) {
+                errors.push(`${manifestPath}: ${section}[${index}].path must be a string`);
+                return;
+            }
+            if (path.isAbsolute(rel)) {
+                errors.push(`${manifestPath}: ${section}[${index}].path must be relative`);
+                return;
+            }
+            const resolved = path.resolve(kitDir, rel);
+            const root = path.resolve(kitDir);
+            if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+                errors.push(`${manifestPath}: ${section}[${index}].path must stay inside the kit directory`);
+                return;
+            }
+            if (!fs.existsSync(resolved)) {
+                const noun = section === "flows" ? "Flow Definition" : "asset";
+                errors.push(`${manifestPath}: ${section}[${index}].path points at missing ${noun}: ${rel}`);
+            }
+        });
+    }
+    return errors;
+}
+export function assertKitRepository(kitDir) {
+    const errors = validateKitRepository(kitDir);
+    if (errors.length) {
+        const error = new Error("Flow Kit repository validation failed");
+        error.diagnostics = errors;
+        throw error;
+    }
+    return readJson(path.join(kitDir, "kit.json"));
+}

package/build/src/lib/args.js

@@ -0,0 +1,45 @@
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const eq = arg.indexOf("=");
+        const key = arg.slice(2, eq === -1 ? undefined : eq);
+        const next = eq === -1 ? argv[index + 1] : arg.slice(eq + 1);
+        let value = true;
+        if (eq !== -1)
+            value = String(next);
+        else if (next !== undefined && !String(next).startsWith("--")) {
+            value = String(next);
+            index += 1;
+        }
+        if (flags[key] === undefined)
+            flags[key] = value;
+        else if (Array.isArray(flags[key]))
+            flags[key].push(String(value));
+        else
+            flags[key] = [String(flags[key]), String(value)];
+    }
+    return { positionals, flags };
+}
+export function flagString(flags, key, fallback) {
+    const value = flags[key];
+    if (Array.isArray(value))
+        return value[value.length - 1];
+    if (typeof value === "string")
+        return value;
+    return fallback;
+}
+export function flagBool(flags, key) {
+    return flags[key] === true || flags[key] === "true";
+}
+export function flagList(flags, key) {
+    const value = flags[key];
+    if (value === undefined || value === true)
+        return [];
+    return Array.isArray(value) ? value.map(String) : [String(value)];
+}

package/build/src/lib/fs.js

@@ -0,0 +1,62 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+export function writeJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export function copyDir(src, dest) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest))
+        fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(src, dest, {
+        recursive: true,
+        filter: (source) => !source.split(path.sep).some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part)),
+    });
+}
+export function assertPathContained(root, target) {
+    const rootReal = fs.realpathSync(root);
+    let existingParent = path.dirname(target);
+    const missingParts = [path.basename(target)];
+    while (!fs.existsSync(existingParent)) {
+        missingParts.unshift(path.basename(existingParent));
+        const next = path.dirname(existingParent);
+        if (next === existingParent)
+            break;
+        existingParent = next;
+    }
+    const parentReal = fs.realpathSync(existingParent);
+    const resolved = path.resolve(parentReal, ...missingParts);
+    const relative = path.relative(rootReal, resolved);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error(`path escapes root: ${target}`);
+    if (fs.existsSync(target)) {
+        const targetReal = fs.realpathSync(target);
+        const targetRelative = path.relative(rootReal, targetReal);
+        if (!targetRelative || targetRelative.startsWith("..") || path.isAbsolute(targetRelative))
+            throw new Error(`path escapes root: ${target}`);
+    }
+}
+export function walkFiles(root) {
+    const out = [];
+    if (!fs.existsSync(root))
+        return out;
+    for (const name of fs.readdirSync(root).sort()) {
+        const file = path.join(root, name);
+        const stat = fs.statSync(file);
+        if (stat.isDirectory())
+            out.push(...walkFiles(file));
+        else if (stat.isFile())
+            out.push(file);
+    }
+    return out;
+}
+export function relPath(root, file) {
+    const rel = path.relative(root, file);
+    return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel.split(path.sep).join("/") : file.split(path.sep).join("/");
+}
+export function isoNow() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}

package/build/src/lib/workflow-learning-projection.js

@@ -0,0 +1,334 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+const KNOWN_LEARNING_STATUSES = new Set(["pending", "learned", "followup_required", "blocked"]);
+const KNOWN_LEARNING_OUTCOMES = new Set(["success", "failure", "mixed", "unknown"]);
+const KNOWN_LEARNING_ROUTE_TARGETS = new Set([
+    "rule",
+    "skill",
+    "power",
+    "agent",
+    "eval",
+    "doc",
+    "backlog",
+    "knowledge",
+    "none",
+]);
+const KNOWN_LEARNING_ROUTE_STATUSES = new Set(["open", "completed", "accepted", "deferred", "rejected"]);
+const KNOWN_CORRECTION_TYPES = new Set([
+    "workflow",
+    "skill",
+    "agent",
+    "tooling",
+    "test",
+    "doc",
+    "process",
+    "product",
+    "provider",
+    "none",
+]);
+const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history"]);
+const MAX_SIDECAR_BYTES = 1024 * 1024;
+export function readWorkflowLearningSources(artifactRoot) {
+    const root = path.resolve(artifactRoot);
+    const stat = fs.statSync(root);
+    if (!stat.isDirectory())
+        throw new Error(`artifact root is not a directory: ${root}`);
+    const sources = [];
+    for (const slug of childWorkflowDirs(root)) {
+        const file = path.join(root, slug, "learning.json");
+        if (!fs.existsSync(file))
+            continue;
+        const value = readSourceJson(file, `${slug}/learning.json`);
+        const learning = validateWorkflowLearningProjectionSourceShape(value, `${slug}/learning.json`);
+        sources.push({
+            path: file,
+            relativePath: toPosix(path.relative(root, file)),
+            slug,
+            learning,
+        });
+    }
+    return sources;
+}
+export function buildWorkflowLearningProjection(sources, options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const producer = {
+        id: options.producer?.id ?? "flow-agents-learning",
+        product: options.producer?.product ?? "flow-agents",
+    };
+    const scope = normalizeScope(options.scope);
+    const learnings = sources.flatMap((source) => source.learning.records.map((record) => mapLearningRecord(source, record)));
+    learnings.sort((left, right) => left.id.localeCompare(right.id));
+    return {
+        schema: "kontour.console.projection",
+        version: "0.1",
+        generatedAt,
+        scope,
+        producer,
+        derivedFrom: {
+            mode: "direct_snapshot",
+            eventHistory: "unavailable",
+            directSnapshot: {
+                id: `flow-agents-learning:${scope.kind}:${scope.id}`,
+                emittedAt: generatedAt,
+                producer,
+                reason: "workflow-learning projection is derived from local learning sidecars; Console event history is unavailable",
+                sourceRef: {
+                    product: "flow-agents",
+                    kind: "workflow-learning",
+                    id: ".flow-agents/*/learning.json",
+                    label: "Local workflow learning sidecars",
+                },
+            },
+        },
+        learnings,
+    };
+}
+export function validateWorkflowLearningProjectionSourceShape(value, label = "learning.json") {
+    const sidecar = objectValue(value, `${label} projection source must be an object`);
+    const schemaVersion = requiredString(sidecar, "schema_version", label);
+    if (schemaVersion !== "1.0")
+        throw new Error(`${label}.schema_version must be 1.0`);
+    const taskSlug = requiredString(sidecar, "task_slug", label);
+    const status = enumString(sidecar, "status", KNOWN_LEARNING_STATUSES, label);
+    const updatedAt = requiredString(sidecar, "updated_at", label);
+    const recordsValue = sidecar.records;
+    if (!Array.isArray(recordsValue) || recordsValue.length === 0) {
+        throw new Error(`${label}.records must be a non-empty array for projection source validation`);
+    }
+    const records = recordsValue.map((record, index) => validateLearningRecord(record, `${label}.records[${index}]`));
+    return {
+        schema_version: "1.0",
+        task_slug: taskSlug,
+        status,
+        updated_at: updatedAt,
+        records,
+    };
+}
+function mapLearningRecord(source, record) {
+    const correction = record.correction;
+    const routing = routeSummary(record.routing);
+    const correctionSummary = correction?.needed
+        ? ` Correction needed${correction.type ? ` for ${correction.type}` : ""}${correction.recurrence_key ? ` (${correction.recurrence_key})` : ""}.`
+        : correction
+            ? " Correction not needed."
+            : "";
+    const openRoutes = routing.open > 0 ? ` ${routing.open} open route${routing.open === 1 ? "" : "s"}.` : "";
+    return {
+        id: deterministicLearningId(source.relativePath, source.learning.task_slug, record.id),
+        family: "workflow",
+        nonAuthority: true,
+        subjectRef: {
+            product: "flow-agents",
+            kind: "workflow",
+            id: source.learning.task_slug,
+            label: source.learning.task_slug,
+        },
+        sourceRef: {
+            product: "flow-agents",
+            kind: "workflow-learning",
+            id: sourceRecordRefId(source.learning.task_slug, record.id),
+            label: `${source.learning.task_slug}/${record.id}`,
+        },
+        summary: `${record.interpretation}${correctionSummary}${openRoutes}`,
+        extensions: {
+            "flow-agents": {
+                task_slug: source.learning.task_slug,
+                record_id: record.id,
+                source_refs: [...record.source_refs],
+                routing,
+                correction: {
+                    needed: correction?.needed ?? false,
+                    ...(correction?.type ? { type: correction.type } : {}),
+                    ...(correction?.recurrence_key ? { recurrence_key: correction.recurrence_key } : {}),
+                    ...(correction?.prevention
+                        ? {
+                            prevention: {
+                                target: correction.prevention.target,
+                                status: correction.prevention.status,
+                                ...(correction.prevention.ref ? { ref: correction.prevention.ref } : {}),
+                            },
+                        }
+                        : {}),
+                },
+                outcome: record.outcome,
+                learning_status: source.learning.status,
+                recorded_at: record.recorded_at,
+                updated_at: source.learning.updated_at,
+                source_path: source.relativePath,
+            },
+        },
+    };
+}
+// Minimal projection source-shape validation for mapper safety. Full workflow
+// artifact JSON Schema validation remains owned by workflow:validate-artifacts.
+export const validateWorkflowLearningSidecar = validateWorkflowLearningProjectionSourceShape;
+function validateLearningRecord(value, label) {
+    const record = objectValue(value, `${label} must be an object`);
+    const id = requiredString(record, "id", label);
+    const recordedAt = requiredString(record, "recorded_at", label);
+    const sourceRefs = stringArray(record.source_refs, `${label}.source_refs`);
+    const outcome = enumString(record, "outcome", KNOWN_LEARNING_OUTCOMES, label);
+    const facts = stringArray(record.facts, `${label}.facts`);
+    const interpretation = requiredString(record, "interpretation", label);
+    if (!Array.isArray(record.routing) || record.routing.length === 0)
+        throw new Error(`${label}.routing must be a non-empty array`);
+    const routing = record.routing.map((route, index) => validateRoute(route, `${label}.routing[${index}]`));
+    const correction = record.correction === undefined ? undefined : validateCorrection(record.correction, `${label}.correction`);
+    return { id, recorded_at: recordedAt, source_refs: sourceRefs, outcome, facts, interpretation, routing, ...(correction ? { correction } : {}) };
+}
+function validateRoute(value, label) {
+    const route = objectValue(value, `${label} must be an object`);
+    const target = enumString(route, "target", KNOWN_LEARNING_ROUTE_TARGETS, label);
+    requiredString(route, "action", label);
+    const status = enumString(route, "status", KNOWN_LEARNING_ROUTE_STATUSES, label);
+    const ref = optionalString(route, "ref", label);
+    return { target, status, ...(ref ? { ref } : {}) };
+}
+function validateCorrection(value, label) {
+    const correction = objectValue(value, `${label} must be an object`);
+    const needed = correction.needed;
+    if (typeof needed !== "boolean")
+        throw new Error(`${label}.needed must be a boolean`);
+    const type = optionalEnumString(correction, "type", KNOWN_CORRECTION_TYPES, label);
+    const recurrenceKey = optionalString(correction, "recurrence_key", label);
+    const intendedBehavior = optionalString(correction, "intended_behavior", label);
+    const observedBehavior = optionalString(correction, "observed_behavior", label);
+    const gap = optionalString(correction, "gap", label);
+    const evidence = optionalString(correction, "evidence", label);
+    const noChangeRationale = optionalString(correction, "no_change_rationale", label);
+    const prevention = correction.prevention === undefined ? undefined : validateRoute(correction.prevention, `${label}.prevention`);
+    if (needed && (!type || !recurrenceKey || !intendedBehavior || !observedBehavior || !gap || (!prevention && !noChangeRationale))) {
+        throw new Error(`${label} is correction-needed but lacks required correction details`);
+    }
+    if (!needed && !evidence)
+        throw new Error(`${label}.evidence is required when correction is not needed`);
+    return {
+        needed,
+        ...(type ? { type } : {}),
+        ...(recurrenceKey ? { recurrence_key: recurrenceKey } : {}),
+        ...(intendedBehavior ? { intended_behavior: intendedBehavior } : {}),
+        ...(observedBehavior ? { observed_behavior: observedBehavior } : {}),
+        ...(gap ? { gap } : {}),
+        ...(evidence ? { evidence } : {}),
+        ...(noChangeRationale ? { no_change_rationale: noChangeRationale } : {}),
+        ...(prevention ? { prevention } : {}),
+    };
+}
+function readSourceJson(file, label) {
+    let fd = null;
+    try {
+        const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+        fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error(`${label} must be a regular file`);
+        if (stat.size > MAX_SIDECAR_BYTES)
+            throw new Error(`${label} exceeds max size of ${MAX_SIDECAR_BYTES} bytes`);
+        const buffer = Buffer.alloc(stat.size);
+        const bytesRead = fs.readSync(fd, buffer, 0, stat.size, 0);
+        if (bytesRead !== stat.size)
+            throw new Error(`${label} changed while being read`);
+        return JSON.parse(buffer.toString("utf8"));
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ELOOP") {
+            throw new Error(`${label} must not be a symlink`);
+        }
+        throw error;
+    }
+    finally {
+        if (fd !== null)
+            fs.closeSync(fd);
+    }
+}
+function childWorkflowDirs(root) {
+    return fs.readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) => !name.startsWith(".") && !SKIPPED_ROOT_ENTRIES.has(name))
+        .sort();
+}
+function routeSummary(routes) {
+    const statuses = routes.map((route) => route.status);
+    return {
+        count: routes.length,
+        open: statuses.filter((status) => status === "open").length,
+        completed: statuses.filter((status) => status === "completed").length,
+        accepted: statuses.filter((status) => status === "accepted").length,
+        deferred: statuses.filter((status) => status === "deferred").length,
+        rejected: statuses.filter((status) => status === "rejected").length,
+        targets: uniqueStrings(routes.map((route) => route.target)),
+        statuses: uniqueStrings(statuses),
+        refs: uniqueStrings(routes.map((route) => route.ref)),
+    };
+}
+function normalizeScope(scope) {
+    return typeof scope === "string" ? { kind: "local", id: scope } : scope;
+}
+function deterministicLearningId(sourcePath, taskSlug, recordId) {
+    const raw = `${sourcePath}\n${taskSlug}\n${recordId}`;
+    return `learning.workflow.${slugPart(taskSlug)}.${slugPart(recordId)}.${fnv1a32(raw)}`;
+}
+function sourceRecordRefId(taskSlug, recordId) {
+    return `${taskSlug}/${recordId}`;
+}
+function fnv1a32(value) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function objectValue(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(message);
+    return value;
+}
+function requiredString(record, key, label) {
+    const value = record[key];
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`${label}.${key} must be a non-empty string`);
+    return value;
+}
+function optionalString(record, key, label) {
+    const value = record[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`${label}.${key} must be a string`);
+    return value.length > 0 ? value : undefined;
+}
+function enumString(record, key, allowed, label) {
+    const value = requiredString(record, key, label);
+    if (!allowed.has(value))
+        throw new Error(`${label}.${key} has unknown value: ${value}`);
+    return value;
+}
+function optionalEnumString(record, key, allowed, label) {
+    const value = optionalString(record, key, label);
+    if (value === undefined)
+        return undefined;
+    if (!allowed.has(value))
+        throw new Error(`${label}.${key} has unknown value: ${value}`);
+    return value;
+}
+function stringArray(value, label) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error(`${label} must be a non-empty string array`);
+    return value.map((item, index) => {
+        if (typeof item !== "string" || item.length === 0)
+            throw new Error(`${label}[${index}] must be a non-empty string`);
+        return item;
+    });
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter((value) => typeof value === "string" && value.length > 0))].sort();
+}
+function slugPart(value) {
+    const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug.slice(0, 64) : "item";
+}
+function toPosix(value) {
+    return value.split(path.sep).join("/");
+}