@really-knows-ai/foundry 2.3.1 → 3.0.0

package/dist/scripts/lib/attestation/payload.js

@@ -0,0 +1,106 @@
+/**
+ * Attestation payload builder.
+ *
+ * Constructs a deterministic, cryptographically verifiable record of work completion.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseFrontmatter } from '../workfile.js';
+import { parseArtefactsTable } from '../artefacts.js';
+import { parseAllHistoryEntries } from '../history.js';
+import { sha256Text, sortPaths } from './hash.js';
+
+function defaultIo() {
+  return {
+    readFile: (filePath) => readFileSync(filePath, 'utf8'),
+    fileExists: (filePath) => existsSync(filePath),
+  };
+}
+
+function readWorkFiles(cwd, io) {
+  const { readFile, fileExists } = io ?? defaultIo();
+
+  return {
+    workText: readFile(path.join(cwd, 'WORK.md')),
+    historyText: fileExists(path.join(cwd, 'WORK.history.yaml')) ? readFile(path.join(cwd, 'WORK.history.yaml')) : '',
+    feedbackText: fileExists(path.join(cwd, 'WORK.feedback.yaml')) ? readFile(path.join(cwd, 'WORK.feedback.yaml')) : '',
+  };
+}
+
+function parseAndSortHistoryEntries(historyText) {
+  const allHistoryEntries = parseAllHistoryEntries(historyText);
+  return allHistoryEntries.slice().sort((a, b) => {
+    const seqA = typeof a.seq === 'number' ? a.seq : 0;
+    const seqB = typeof b.seq === 'number' ? b.seq : 0;
+    return seqA - seqB;
+  });
+}
+
+function buildStageRecord(entry) {
+  const record = {
+    changed_files: entry.changed_files ? sortPaths(entry.changed_files) : [],
+    cycle: entry.cycle,
+    iteration: entry.iteration,
+    open_feedback: entry.open_feedback ?? 0,
+  };
+
+  if (entry.route !== undefined) {
+    record.route = entry.route;
+  }
+
+  record.stage = entry.stage;
+
+  return record;
+}
+
+function buildStagesFromEntries(sortedEntries) {
+  return sortedEntries.map(buildStageRecord);
+}
+
+function def(value, fallback) {
+  return value || fallback;
+}
+
+function buildContract(frontmatter) {
+  return {
+    allowed_write_scope: def(frontmatter['allowed-write-scope'], []),
+    entry_cycle: frontmatter.cycle,
+    expected_output_types: def(frontmatter['expected-output-types'], []),
+    flow_id: frontmatter.flow,
+    required_deterministic_checks: def(frontmatter['required-deterministic-checks'], []),
+    required_human_gates: def(frontmatter['required-human-gates'], null),
+    required_stages: def(frontmatter.stages, []),
+  };
+}
+
+function buildGovernance(frontmatter, workText, historyText, feedbackText) {
+  return {
+    config_commit: def(frontmatter['config-commit'], null),
+    workfile_hashes: {
+      'WORK.md': sha256Text(workText),
+      'WORK.history.yaml': sha256Text(historyText),
+      'WORK.feedback.yaml': sha256Text(feedbackText),
+    },
+  };
+}
+
+export function buildAttestationPayload({ cwd, goalText, archiveBranch, archiveTipSha, io }) {
+  const { workText, historyText, feedbackText } = readWorkFiles(cwd, io);
+
+  const frontmatter = parseFrontmatter(workText);
+  const artefacts = parseArtefactsTable(workText);
+
+  const sortedEntries = parseAndSortHistoryEntries(historyText);
+  const stages = buildStagesFromEntries(sortedEntries);
+
+  return {
+    contract: buildContract(frontmatter),
+    governance: buildGovernance(frontmatter, workText, historyText, feedbackText),
+    outputs: artefacts.map(row => ({ path: row.file, status: row.status })),
+    process: { stages },
+    request: { goal_text: goalText },
+    schema: 'foundry-attestation/v1',
+    work_branch_archive: { name: archiveBranch, tip_sha: archiveTipSha },
+  };
+}

package/dist/scripts/lib/attestation/render.js

@@ -0,0 +1,16 @@
+/**
+ * Attestation commit message renderer.
+ *
+ * Formats commit messages with human-readable summaries and canonical attestation blocks.
+ */
+
+export function renderAttestedCommitMessage({ humanSummary, payloadJson }) {
+  return [
+    humanSummary,
+    '',
+    '-----BEGIN FOUNDRY ATTESTATION-----',
+    payloadJson,
+    '-----END FOUNDRY ATTESTATION-----',
+    '',
+  ].join('\n');
+}

package/dist/scripts/lib/attestation/verify.js

@@ -0,0 +1,15 @@
+import { execFileSync } from 'node:child_process';
+import { extractAttestationBlock } from './parse.js';
+
+export function verifyAttestationRef({ cwd, ref = 'HEAD' }) {
+  execFileSync('git', ['verify-commit', ref], { cwd, encoding: 'utf8', stdio: 'pipe' });
+  const message = execFileSync('git', ['log', '-1', '--pretty=%B', ref], { cwd, encoding: 'utf8', stdio: 'pipe' });
+  const json = extractAttestationBlock(message);
+  let payload;
+  try {
+    payload = JSON.parse(json);
+  } catch {
+    throw new Error(`malformed attestation JSON: ${json}`);
+  }
+  return { status: 'verified', schema: payload.schema, payload };
+}

package/dist/scripts/lib/branch-guard.js

@@ -0,0 +1,72 @@
+export const CONFIG_RE   = /^config\/[^/]+$/;
+const WORK_RE     = /^work\/.+$/;
+export const DRY_RUN_RE  = /^dry-run\/[^/]+\/[^/]+$/;
+
+function tryRevParse(io) {
+  try {
+    const out = io.exec(['git', 'rev-parse', '--abbrev-ref', 'HEAD']).trim();
+    if (out && out !== 'HEAD') return out;
+  } catch { /* fall through to symbolic-ref */ }
+  return null;
+}
+
+function trySymbolicRef(io) {
+  try {
+    const sym = io.exec(['git', 'symbolic-ref', '--short', 'HEAD']).trim();
+    if (sym) return sym;
+  } catch { /* truly detached or not a repo */ }
+  return null;
+}
+
+export function currentBranch(io) {
+  // `git rev-parse --abbrev-ref HEAD` exits non-zero on a fresh repo with
+  // no commits (unborn branch) and on a non-repo directory. Fall back to
+  // `git symbolic-ref --short HEAD` which still resolves the unborn
+  // branch's name; if that also fails (truly detached or non-repo), treat
+  // as "no current branch" so the guard returns a structured refusal
+  // envelope rather than throwing.
+  return tryRevParse(io) || trySymbolicRef(io) || null;
+}
+
+function describe(branch) {
+  return branch === null ? 'detached HEAD' : `'${branch}'`;
+}
+
+export function requireOnConfigBranch(io) {
+  const b = currentBranch(io);
+  if (b && CONFIG_RE.test(b)) return { ok: true };
+  return {
+    ok: false,
+    error:
+      `this tool requires a config/<description> branch (strict; ` +
+      `dry-run/<x>/<y> does not count); currently on ${describe(b)}. ` +
+      `Use foundry_git_branch({ kind: "config", description: "..." }) ` +
+      `from main first.`,
+  };
+}
+
+export function requireOnFlowBranch(io) {
+  const b = currentBranch(io);
+  if (b && (WORK_RE.test(b) || DRY_RUN_RE.test(b))) return { ok: true };
+  return {
+    ok: false,
+    error:
+      `this tool requires a work/<flow>-<desc> or ` +
+      `dry-run/<x>/<y> branch; currently on ${describe(b)}. ` +
+      `Use foundry_git_branch({ kind: "work", flowId, description }) ` +
+      `from main, or { kind: "dry-run", flowId, description } from a config branch.`,
+  };
+}
+
+export function requireOnConfigOrFlowBranch(io) {
+  const b = currentBranch(io);
+  if (b && (CONFIG_RE.test(b) || WORK_RE.test(b) || DRY_RUN_RE.test(b))) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    error:
+      `this tool requires a config/* or work/* or dry-run/*/* ` +
+      `branch; currently on ${describe(b)}.`,
+  };
+}

package/dist/scripts/lib/config-creators/appraiser.js

@@ -0,0 +1,9 @@
+import { join } from 'node:path';
+import { validate } from '../config-validators/appraiser.js';
+import { makeCreator } from './factory.js';
+
+export const create = makeCreator({
+  kind: { human: 'appraiser', underscored: 'appraiser' },
+  pathFor: (args) => join('foundry', 'appraisers', `${args.name}.md`),
+  validator: validate,
+});

package/dist/scripts/lib/config-creators/artefact-type.js

@@ -0,0 +1,9 @@
+import { join } from 'node:path';
+import { validate } from '../config-validators/artefact-type.js';
+import { makeCreator } from './factory.js';
+
+export const create = makeCreator({
+  kind: { human: 'artefact-type', underscored: 'artefact_type' },
+  pathFor: (args) => join('foundry', 'artefacts', args.name, 'definition.md'),
+  validator: validate,
+});

package/dist/scripts/lib/config-creators/cycle.js

@@ -0,0 +1,11 @@
+import { join } from 'node:path';
+import { validate } from '../config-validators/cycle.js';
+import { makeCreator } from './factory.js';
+
+const KIND = 'cycle';
+
+export const create = makeCreator({
+  kind: KIND,
+  pathFor: (args) => join('foundry', 'cycles', `${args.name}.md`),
+  validator: validate,
+});

package/dist/scripts/lib/config-creators/factory.js

@@ -0,0 +1,49 @@
+import { dirname } from 'node:path';
+import { commitWithPolicy } from '../git-bridge.js';
+
+function runCustomValidation(customValidation, args) {
+  if (!customValidation) return null;
+  const result = customValidation(args);
+  return result.ok ? null : result;
+}
+
+async function checkFileExists(io, path) {
+  if (await io.exists(path)) {
+    return {
+      ok: false,
+      errors: [`${path} already exists; this tool only creates new files — to update, edit by hand on this config/* branch`],
+    };
+  }
+  return null;
+}
+
+function normaliseKind(kind) {
+  return typeof kind === 'string' ? { human: kind, underscored: kind } : kind;
+}
+
+export function makeCreator({ kind, pathFor, validator, customValidation }) {
+  return async function create(args) {
+    const customResult = runCustomValidation(customValidation, args);
+    if (customResult) return customResult;
+
+    const v = await validator({ name: args.name, body: args.body, io: args.io });
+    if (!v.ok) return { ok: false, errors: v.errors };
+
+    const path = pathFor(args);
+    const existsError = await checkFileExists(args.io, path);
+    if (existsError) return existsError;
+
+    await args.io.mkdirp(dirname(path));
+    await args.io.writeFile(path, args.body);
+
+    const kindNormalised = normaliseKind(kind);
+
+    const sha = commitWithPolicy({
+      message: `config: add ${kindNormalised.human} ${args.name}\n\nvia foundry_config_create_${kindNormalised.underscored}`,
+      allowedPatterns: ['foundry/**'],
+      execFile: args.execFile,
+    });
+
+    return { ok: true, path, sha };
+  };
+}

package/dist/scripts/lib/config-creators/flow.js

@@ -0,0 +1,11 @@
+import { join } from 'node:path';
+import { validate } from '../config-validators/flow.js';
+import { makeCreator } from './factory.js';
+
+const KIND = 'flow';
+
+export const create = makeCreator({
+  kind: KIND,
+  pathFor: (args) => join('foundry', 'flows', `${args.name}.md`),
+  validator: validate,
+});

package/dist/scripts/lib/config-validators/appraiser.js

@@ -0,0 +1,49 @@
+import {
+  tryParseFrontmatter,
+  requireNonEmptyString,
+  validateIdMatch,
+  bodyAfterFrontmatter,
+} from './helpers.js';
+
+/**
+ * Validate an appraiser definition body.
+ *
+ * Checks the rules the runtime depends on: `getAppraisers()` reads
+ * `frontmatter.id`, optional `frontmatter.model`, and the body prose. The
+ * `add-appraiser` skill additionally requires a human-facing `name`.
+ *
+ * @param {object} opts
+ * @param {string} opts.name  Slugged identifier (matches frontmatter.id).
+ * @param {string} opts.body  Full markdown body.
+ * @returns {Promise<{ok: true} | {ok: false, errors: string[]}>}
+ */
+export async function validate({ name, body }) {
+  const parsed = tryParseFrontmatter(body);
+  if (!parsed.ok) return { ok: false, errors: parsed.errors };
+  const fm = parsed.fm;
+
+  const errors = [
+    requireNonEmptyString(fm.id, 'frontmatter.id'),
+    validateIdMatch(fm, name),
+    requireNonEmptyString(fm.name, 'frontmatter.name'),
+    checkModel(fm),
+    checkBody(body),
+  ].filter(Boolean);
+
+  return errors.length ? { ok: false, errors } : { ok: true };
+}
+
+function checkModel(fm) {
+  if (fm.model !== undefined && (typeof fm.model !== 'string' || !fm.model.trim())) {
+    return 'frontmatter.model, when present, must be a non-empty string';
+  }
+  return null;
+}
+
+function checkBody(body) {
+  const afterFm = bodyAfterFrontmatter(body);
+  if (!afterFm) {
+    return 'body must contain a personality description after the frontmatter';
+  }
+  return null;
+}

package/dist/scripts/lib/config-validators/artefact-type.js

@@ -0,0 +1,38 @@
+import {
+  tryParseFrontmatter,
+  requireNonEmptyString,
+  validateNameMatch,
+  requireHeading,
+  validateStringArrayEntries,
+} from './helpers.js';
+
+/**
+ * Validate an artefact-type definition body.
+ *
+ * @param {object} opts
+ * @param {string} opts.name      Slugged identifier (matches frontmatter.name).
+ * @param {string} opts.body      Full markdown body.
+ * @returns {Promise<{ok: true} | {ok: false, errors: string[]}>}
+ */
+export async function validate({ name, body }) {
+  const parsed = tryParseFrontmatter(body);
+  if (!parsed.ok) return { ok: false, errors: parsed.errors };
+  const fm = parsed.fm;
+
+  const errors = [
+    requireNonEmptyString(fm.name, 'frontmatter.name'),
+    validateNameMatch(fm, name),
+    checkFilePatterns(fm),
+    requireHeading(body, 'Definition'),
+  ].filter(Boolean);
+
+  return errors.length ? { ok: false, errors } : { ok: true };
+}
+
+function checkFilePatterns(fm) {
+  const patterns = fm['file-patterns'];
+  if (!Array.isArray(patterns) || patterns.length === 0) {
+    return 'frontmatter.file-patterns is required and must be a non-empty array of glob strings';
+  }
+  return validateStringArrayEntries(patterns, 'frontmatter.file-patterns');
+}

package/dist/scripts/lib/config-validators/cycle.js

@@ -0,0 +1,131 @@
+import { join } from 'node:path';
+import {
+  tryParseFrontmatter,
+  requireNonEmptyString,
+  validateIdMatch,
+  validateStringArrayEntries,
+} from './helpers.js';
+
+const VALID_INPUT_TYPES = new Set(['any-of', 'all-of']);
+
+/**
+ * Validate a cycle definition body.
+ *
+ * @param {object} opts
+ * @param {string} opts.name      Slugged identifier (matches frontmatter.id).
+ * @param {string} opts.body      Full markdown body.
+ * @param {object} opts.io        IO adapter with `exists(path)`.
+ * @returns {Promise<{ok: true} | {ok: false, errors: string[]}>}
+ */
+export async function validate({ name, body, io }) {
+  const parsed = tryParseFrontmatter(body);
+  if (!parsed.ok) return { ok: false, errors: parsed.errors };
+  const fm = parsed.fm;
+
+  const errors = [
+    requireNonEmptyString(fm.id, 'frontmatter.id'),
+    validateIdMatch(fm, name),
+    requireNonEmptyString(fm.name, 'frontmatter.name'),
+    await checkOutputType(fm, io),
+    ...await checkInputs(fm, io),
+    ...await checkTargets(fm, io),
+  ].filter(Boolean);
+
+  return errors.length ? { ok: false, errors } : { ok: true };
+}
+
+async function checkOutputType(fm, io) {
+  const outputType = fm['output-type'];
+  const strErr = requireNonEmptyString(outputType, 'frontmatter.output-type');
+  if (strErr) return strErr;
+  const filePath = join('foundry', 'artefacts', outputType, 'definition.md');
+  if (!(await io.exists(filePath))) {
+    return `output-type references artefact type "${outputType}" but ${filePath} does not exist`;
+  }
+  return null;
+}
+
+async function checkInputs(fm, io) {
+  const inputs = fm.inputs;
+  if (inputs === undefined) return [];
+
+  const shapeErrors = checkInputsShape(inputs);
+  if (shapeErrors.length) return shapeErrors;
+
+  const typeErrors = checkInputType(inputs);
+  const artefactErrors = await checkInputArtefacts(inputs, io);
+  return [...typeErrors, ...artefactErrors];
+}
+
+function checkInputsShape(inputs) {
+  const errors = [];
+  const isInvalidShape = typeof inputs !== 'object' || inputs === null || Array.isArray(inputs);
+  if (isInvalidShape) {
+    errors.push('frontmatter.inputs, when present, must be an object with type and artefacts');
+  }
+  return errors;
+}
+
+function checkInputType(inputs) {
+  const errors = [];
+  if (!VALID_INPUT_TYPES.has(inputs.type)) {
+    errors.push('frontmatter.inputs.type must be one of: any-of, all-of');
+  }
+  return errors;
+}
+
+async function checkInputArtefacts(inputs, io) {
+  const artefacts = inputs.artefacts;
+  const noArtefacts = !Array.isArray(artefacts) || artefacts.length === 0;
+  if (noArtefacts) {
+    return ['frontmatter.inputs.artefacts must be a non-empty array of artefact-type ids'];
+  }
+
+  const entryErr = validateStringArrayEntries(artefacts, 'frontmatter.inputs.artefacts');
+  const refErrors = await validateArtefactRefs(artefacts, io);
+  return entryErr ? [entryErr, ...refErrors] : refErrors;
+}
+
+async function validateArtefactRefs(artefacts, io) {
+  const errors = [];
+  for (const id of artefacts) {
+    const isValidId = typeof id === 'string' && id.trim();
+    if (!isValidId) continue;
+    const refErr = await validateArtefactRef(id, io, 'inputs.artefacts');
+    if (refErr) errors.push(refErr);
+  }
+  return errors;
+}
+
+async function validateArtefactRef(id, io, label) {
+  const filePath = join('foundry', 'artefacts', id, 'definition.md');
+  if (!(await io.exists(filePath))) {
+    return `${label} references artefact type "${id}" but ${filePath} does not exist`;
+  }
+  return null;
+}
+
+async function checkTargets(fm, io) {
+  const targets = fm.targets;
+  if (targets === undefined) return [];
+
+  if (!Array.isArray(targets)) {
+    return ['frontmatter.targets, when present, must be an array of cycle ids'];
+  }
+
+  const entryErr = validateStringArrayEntries(targets, 'frontmatter.targets');
+  const refErrors = await validateCycleRefs(targets, io);
+  return entryErr ? [entryErr, ...refErrors] : refErrors;
+}
+
+async function validateCycleRefs(targets, io) {
+  const errors = [];
+  for (const id of targets) {
+    if (typeof id !== 'string' || !id.trim()) continue;
+    const filePath = join('foundry', 'cycles', `${id}.md`);
+    if (!(await io.exists(filePath))) {
+      errors.push(`targets references cycle "${id}" but ${filePath} does not exist`);
+    }
+  }
+  return errors;
+}

package/dist/scripts/lib/config-validators/flow.js

@@ -0,0 +1,57 @@
+import { join } from 'node:path';
+import {
+  tryParseFrontmatter,
+  requireNonEmptyString,
+  validateIdMatch,
+  requireHeading,
+  validateStringArrayEntries,
+} from './helpers.js';
+
+/**
+ * Validate a flow definition body.
+ *
+ * @param {object} opts
+ * @param {string} opts.name      Slugged identifier (matches frontmatter.id).
+ * @param {string} opts.body      Full markdown body.
+ * @param {object} opts.io        IO adapter with `exists(path)`.
+ * @returns {Promise<{ok: true} | {ok: false, errors: string[]}>}
+ */
+export async function validate({ name, body, io }) {
+  const parsed = tryParseFrontmatter(body);
+  if (!parsed.ok) return { ok: false, errors: parsed.errors };
+  const fm = parsed.fm;
+
+  const errors = [
+    requireNonEmptyString(fm.id, 'frontmatter.id'),
+    validateIdMatch(fm, name),
+    requireNonEmptyString(fm.name, 'frontmatter.name'),
+    await checkStartingCycles(fm, io),
+    requireHeading(body, 'Cycles'),
+  ].filter(Boolean);
+
+  return errors.length ? { ok: false, errors } : { ok: true };
+}
+
+async function checkStartingCycles(fm, io) {
+  const starting = fm['starting-cycles'];
+  const isEmpty = !Array.isArray(starting) || starting.length === 0;
+  if (isEmpty) {
+    return 'frontmatter.starting-cycles is required and must be a non-empty array of cycle ids';
+  }
+
+  const entryErr = validateStringArrayEntries(starting, 'frontmatter.starting-cycles');
+  if (entryErr) return entryErr;
+
+  return await checkCycleRefsExist(starting, io, 'starting-cycles');
+}
+
+async function checkCycleRefsExist(ids, io, label) {
+  for (const id of ids) {
+    if (typeof id !== 'string' || !id.trim()) continue;
+    const filePath = join('foundry', 'cycles', `${id}.md`);
+    if (!(await io.exists(filePath))) {
+      return `${label} references cycle "${id}" but ${filePath} does not exist`;
+    }
+  }
+  return null;
+}

package/dist/scripts/lib/config-validators/helpers.js

@@ -0,0 +1,96 @@
+import { parseFrontmatter } from '../workfile.js';
+
+/**
+ * Shared helpers for config validators.
+ */
+
+/**
+ * Parse frontmatter from a body string.
+ * @param {string} body
+ * @returns {{ok: true, fm: object} | {ok: false, errors: string[]}}
+ */
+export function tryParseFrontmatter(body) {
+  if (!/^---\n[\s\S]*?\n---/.test(body)) {
+    return { ok: false, errors: ['frontmatter is missing or unparseable'] };
+  }
+  try {
+    return { ok: true, fm: parseFrontmatter(body) };
+  } catch (err) {
+    return { ok: false, errors: [`frontmatter is unparseable: ${err.message}`] };
+  }
+}
+
+/**
+ * Check that a value is a non-empty string.
+ * @param {unknown} value
+ * @param {string} fieldName
+ * @returns {string|null} Error message or null.
+ */
+export function requireNonEmptyString(value, fieldName) {
+  if (typeof value !== 'string' || !value.trim()) {
+    return `${fieldName} is required and must be a non-empty string`;
+  }
+  return null;
+}
+
+/**
+ * Validate that frontmatter.id matches the supplied name.
+ * @param {object} fm
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function validateIdMatch(fm, name) {
+  if (fm.id && fm.id !== name) {
+    return `frontmatter.id (${fm.id}) must match the supplied name (${name})`;
+  }
+  return null;
+}
+
+/**
+ * Validate that frontmatter.name matches the supplied name.
+ * @param {object} fm
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function validateNameMatch(fm, name) {
+  if (fm.name && fm.name !== name) {
+    return `frontmatter.name (${fm.name}) must match the supplied name (${name})`;
+  }
+  return null;
+}
+
+/**
+ * Extract body content after frontmatter.
+ * @param {string} body
+ * @returns {string}
+ */
+export function bodyAfterFrontmatter(body) {
+  return body.replace(/^---\n[\s\S]*?\n---\n?/, '').trim();
+}
+
+/**
+ * Check that the body contains a markdown heading matching the given text.
+ * @param {string} body
+ * @param {string} headingText  e.g. "Definition" or "Cycles"
+ * @returns {string|null}
+ */
+export function requireHeading(body, headingText) {
+  const pattern = new RegExp(`^##\\s+${headingText}\\s*$`, 'm');
+  if (!pattern.test(body)) {
+    return `body must contain a "## ${headingText}" section`;
+  }
+  return null;
+}
+
+/**
+ * Validate that an array contains only non-empty strings.
+ * @param {unknown[]} arr
+ * @param {string} fieldName
+ * @returns {string|null}
+ */
+export function validateStringArrayEntries(arr, fieldName) {
+  if (arr.some((item) => typeof item !== 'string' || !item.trim())) {
+    return `every ${fieldName} entry must be a non-empty string`;
+  }
+  return null;
+}