cabloy 5.1.191 → 5.1.192

package/repo-agent-governance/tests/governance.test.mjs

@@ -0,0 +1,295 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { test } from 'node:test';
+
+import { check, GOVERNANCE_DIR, ROOT_DIR } from '../scripts/governance.mjs';
+import {
+  analyze,
+  buildMessages,
+  isCodeFile,
+  resolveEdition,
+} from '../tools/contract-loop/core.mjs';
+
+function createFixture() {
+  const root = mkdtempSync(resolve(tmpdir(), 'cabloy-agent-governance-'));
+  cpSync(GOVERNANCE_DIR, resolve(root, 'repo-agent-governance'), { recursive: true });
+  writeFileSync(resolve(root, '__CABLOY_BASIC__'), '');
+  return root;
+}
+
+function runNode(root, executable, ...args) {
+  const result = spawnSync(process.execPath, [executable, ...args], {
+    cwd: root,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      CABLOY_GOVERNANCE_ROOT: root,
+    },
+  });
+  return {
+    status: result.status,
+    output: `${result.stdout}${result.stderr}`,
+  };
+}
+
+function runGovernance(root, ...args) {
+  return runNode(root, resolve(root, 'repo-agent-governance/scripts/governance.mjs'), ...args);
+}
+
+function readState(root) {
+  return JSON.parse(readFileSync(resolve(root, '.cabloy-agent-governance-state.json'), 'utf8'));
+}
+
+function modifyPolicy(root, addition) {
+  const policyPath = resolve(root, 'repo-agent-governance/policies/repository.md');
+  writeFileSync(policyPath, `${readFileSync(policyPath, 'utf8').trimEnd()}\n\n${addition}\n`);
+}
+
+function removePolicyTarget(root, target) {
+  const manifestPath = resolve(root, 'repo-agent-governance/manifest.json');
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  manifest.policy.targets = manifest.policy.targets.filter(item => item.target !== target);
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+function withFixture(callback) {
+  const root = createFixture();
+  try {
+    callback(root);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test('committed governance adapters match their canonical sources', () => {
+  const result = check();
+  assert.deepEqual(result.problems, []);
+  assert.ok(result.assets.length > 0);
+  assert.ok(existsSync(resolve(GOVERNANCE_DIR, 'managed-assets.json')));
+});
+
+test('all generated skill bundles retain their source identity', () => {
+  for (const asset of check().assets.filter(
+    asset => asset.category === 'skill' && asset.target.endsWith('/SKILL.md'),
+  )) {
+    const source = `${readFileSync(resolve(GOVERNANCE_DIR, asset.source), 'utf8')
+      .replace(/\r\n?/g, '\n')
+      .replace(/\n*$/, '')}\n`;
+    const target = readFileSync(resolve(ROOT_DIR, asset.target), 'utf8');
+    assert.equal(target, source, asset.target);
+    assert.match(target, /^---\nname: [^\n]+\ndescription: [^\n]+\n---\n/);
+  }
+});
+
+test('governance adoption creates state and is idempotent', () => {
+  withFixture(root => {
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    const state = readState(root);
+    assert.ok(state.assets.length > 0);
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    assert.match(runGovernance(root, 'adopt', '--apply').output, /No governance adoption changes/);
+  });
+});
+
+test('initializer adopts canonical adapters for a fresh transition package', () => {
+  withFixture(root => {
+    const scriptsDirectory = resolve(root, 'scripts');
+    mkdirSync(scriptsDirectory);
+    const bootstrap = resolve(ROOT_DIR, 'scripts/bootstrapAgentGovernance.mjs');
+    const fixtureBootstrap = resolve(scriptsDirectory, 'bootstrapAgentGovernance.mjs');
+    const content = readFileSync(bootstrap, 'utf8').replace(
+      "const ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');",
+      'const ROOT_DIR = process.env.CABLOY_GOVERNANCE_ROOT;',
+    );
+    writeFileSync(fixtureBootstrap, content);
+    const result = runNode(root, fixtureBootstrap);
+    assert.equal(result.status, 0, result.output);
+    assert.ok(existsSync(resolve(root, 'CLAUDE.md')));
+    assert.equal(readState(root).assets.length, check().assets.length);
+  });
+});
+
+test('initializer preserves a legacy-customized adapter during a staged upgrade', () => {
+  withFixture(root => {
+    const scriptsDirectory = resolve(root, 'scripts');
+    mkdirSync(scriptsDirectory);
+    const bootstrap = resolve(ROOT_DIR, 'scripts/bootstrapAgentGovernance.mjs');
+    const fixtureBootstrap = resolve(scriptsDirectory, 'bootstrapAgentGovernance.mjs');
+    const content = readFileSync(bootstrap, 'utf8').replace(
+      "const ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');",
+      'const ROOT_DIR = process.env.CABLOY_GOVERNANCE_ROOT;',
+    );
+    writeFileSync(fixtureBootstrap, content);
+    writeFileSync(resolve(root, 'CLAUDE.md'), 'legacy project customization\n');
+    writeFileSync(resolve(root, 'package.json'), readFileSync(resolve(ROOT_DIR, 'package.json')));
+
+    const upgradeRoot = resolve(root, 'node_modules/.cabloy-upgrade');
+    cpSync(GOVERNANCE_DIR, resolve(upgradeRoot, 'repo-agent-governance'), { recursive: true });
+    writeFileSync(
+      resolve(upgradeRoot, 'package.json'),
+      readFileSync(resolve(ROOT_DIR, 'package.json')),
+    );
+    modifyPolicy(upgradeRoot, 'Staged governance source.');
+
+    const result = runNode(root, fixtureBootstrap);
+    assert.equal(result.status, 0, result.output);
+    assert.match(result.output, /locally modified or legacy adapter outputs/);
+    assert.equal(
+      readFileSync(resolve(root, 'CLAUDE.md'), 'utf8'),
+      'legacy project customization\n',
+    );
+    assert.match(
+      readFileSync(resolve(root, 'repo-agent-governance/policies/repository.md'), 'utf8'),
+      /Staged governance source/,
+    );
+    assert.match(readFileSync(resolve(root, 'AGENTS.md'), 'utf8'), /Staged governance source/);
+  });
+});
+
+test('governance adoption adopts byte-identical legacy outputs', () => {
+  withFixture(root => {
+    assert.equal(runGovernance(root, 'render').status, 0);
+    assert.equal(existsSync(resolve(root, '.cabloy-agent-governance-state.json')), false);
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    assert.equal(readState(root).assets.length, check().assets.length);
+  });
+});
+
+test('governance adoption preserves modified legacy outputs and records other ownership', () => {
+  withFixture(root => {
+    const policyPath = resolve(root, 'CLAUDE.md');
+    writeFileSync(policyPath, 'project-owned policy\n');
+    const result = runGovernance(root, 'adopt', '--apply');
+    assert.equal(result.status, 2);
+    assert.match(result.output, /conflicts: CLAUDE\.md/);
+    assert.equal(readFileSync(policyPath, 'utf8'), 'project-owned policy\n');
+    const state = readState(root);
+    assert.equal(
+      state.assets.some(asset => asset.target === 'CLAUDE.md'),
+      false,
+    );
+    assert.equal(
+      state.assets.some(asset => asset.target === 'AGENTS.md'),
+      true,
+    );
+  });
+});
+
+test('governance adoption updates unchanged owned outputs and preserves later user edits', () => {
+  withFixture(root => {
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    modifyPolicy(root, 'Fixture-owned change.');
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    assert.match(readFileSync(resolve(root, 'CLAUDE.md'), 'utf8'), /Fixture-owned change/);
+
+    writeFileSync(resolve(root, 'CLAUDE.md'), 'locally customized adapter\n');
+    modifyPolicy(root, 'A newer canonical change.');
+    const result = runGovernance(root, 'adopt', '--apply');
+    assert.equal(result.status, 2);
+    assert.match(result.output, /conflicts: CLAUDE\.md/);
+    assert.equal(readFileSync(resolve(root, 'CLAUDE.md'), 'utf8'), 'locally customized adapter\n');
+  });
+});
+
+test('governance adoption deletes only unchanged retired outputs', () => {
+  withFixture(root => {
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    removePolicyTarget(root, 'AGENTS.md');
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    assert.equal(existsSync(resolve(root, 'AGENTS.md')), false);
+    assert.equal(
+      readState(root).assets.some(asset => asset.target === 'AGENTS.md'),
+      false,
+    );
+  });
+});
+
+test('governance adoption preserves modified retired outputs', () => {
+  withFixture(root => {
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    writeFileSync(resolve(root, 'AGENTS.md'), 'locally customized retired adapter\n');
+    removePolicyTarget(root, 'AGENTS.md');
+    const result = runGovernance(root, 'adopt', '--apply');
+    assert.equal(result.status, 2);
+    assert.match(result.output, /conflicts: AGENTS\.md/);
+    assert.equal(
+      readFileSync(resolve(root, 'AGENTS.md'), 'utf8'),
+      'locally customized retired adapter\n',
+    );
+  });
+});
+
+test('governance adoption preserves unmanaged siblings and rejects malformed state', () => {
+  withFixture(root => {
+    const siblingPath = resolve(root, '.claude/skills/project-local/SKILL.md');
+    mkdirSync(dirname(siblingPath), { recursive: true });
+    writeFileSync(siblingPath, 'project-local skill\n');
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 0);
+    assert.equal(readFileSync(siblingPath, 'utf8'), 'project-local skill\n');
+
+    writeFileSync(
+      resolve(root, '.cabloy-agent-governance-state.json'),
+      '{"schemaVersion":1,"assets":[{"target":"../../outside","sha256":"bad"}]}\n',
+    );
+    const result = runGovernance(root, 'adopt', '--apply');
+    assert.equal(result.status, 1);
+    assert.match(result.output, /Unable to parse governance installer state/);
+  });
+});
+
+test('governance adoption force-updates one explicitly named target', () => {
+  withFixture(root => {
+    writeFileSync(resolve(root, 'CLAUDE.md'), 'locally customized adapter\n');
+    assert.equal(runGovernance(root, 'adopt', '--apply').status, 2);
+    assert.equal(runGovernance(root, 'adopt', '--apply', '--force', 'CLAUDE.md').status, 0);
+    assert.notEqual(
+      readFileSync(resolve(root, 'CLAUDE.md'), 'utf8'),
+      'locally customized adapter\n',
+    );
+  });
+});
+
+test('contract-loop analysis preserves forward and reverse guidance', () => {
+  const resolution = resolveEdition(ROOT_DIR);
+  assert.equal(resolution.kind, 'resolved');
+  const forward = analyze(
+    '/repo/vona/src/module/demo/src/controller/demo.ts',
+    '@Api.field()',
+    resolution.edition,
+  );
+  assert.equal(forward.forwardReason, 'Backend contract source may have changed.');
+  assert.equal(forward.reverseReason, null);
+  const reverse = analyze(
+    '/repo/zova/src/suite/demo/modules/demo/src/.metadata/index.ts',
+    '',
+    resolution.edition,
+  );
+  assert.equal(reverse.forwardReason, null);
+  assert.equal(
+    reverse.reverseReason,
+    'Frontend-owned resources or metadata may affect backend consumers.',
+  );
+  assert.match(buildMessages(reverse, resolution), /npm run build:zova:admin/);
+  assert.match(buildMessages(reverse, resolution), /npm run deps:vona/);
+});
+
+test('contract-loop recognizes supported vendor and suite source paths', () => {
+  assert.equal(isCodeFile('/repo/zova/src/module-vendor/demo/src/bean/demo.ts'), true);
+  assert.equal(
+    isCodeFile('/repo/zova/src/suite-vendor/demo/modules/demo/src/component/demo.tsx'),
+    true,
+  );
+  assert.equal(isCodeFile('/repo/vona/src/module/demo/src/service/demo.ts'), true);
+  assert.equal(isCodeFile('/repo/repo-docs/ai/agent-governance.md'), false);
+});

package/repo-agent-governance/tools/contract-loop/check.mjs

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  analyze,
+  buildMessages,
+  hasSignal,
+  isCodeFile,
+  normalizePath,
+  resolveEdition,
+} from './core.mjs';
+
+const SCRIPT_FILE = fileURLToPath(import.meta.url);
+const ROOT_DIR = resolve(dirname(SCRIPT_FILE), '..', '..', '..');
+
+function parseArgs(args) {
+  let file;
+  let format = 'text';
+  for (let index = 0; index < args.length; index++) {
+    if (args[index] === '--file') {
+      file = args[++index];
+    } else if (args[index] === '--format') {
+      format = args[++index];
+    } else {
+      throw new Error(`Unknown argument: ${args[index]}`);
+    }
+  }
+  if (!file) throw new Error('Usage: contract-loop/check.mjs --file <path> [--format text|json]');
+  if (!['text', 'json'].includes(format)) throw new Error(`Unsupported format: ${format}`);
+  return { file, format };
+}
+
+function main() {
+  const { file, format } = parseArgs(process.argv.slice(2));
+  const filePath = normalizePath(ROOT_DIR, file);
+  if (!filePath || !isCodeFile(filePath)) {
+    throw new Error(`File is not a supported Vona/Zova source path: ${file}`);
+  }
+  const content = readFileSync(filePath, 'utf8');
+  const resolution = resolveEdition(ROOT_DIR);
+  const result = analyze(
+    filePath,
+    content,
+    resolution.kind === 'resolved' ? resolution.edition : null,
+  );
+  const output = {
+    edition: resolution.kind === 'resolved' ? resolution.edition.id : resolution.kind,
+    file: filePath,
+    signal: hasSignal(result),
+    ...result,
+    message: hasSignal(result) ? buildMessages(result, resolution) : null,
+  };
+  if (format === 'json') {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(output, null, 2));
+  } else if (output.message) {
+    // eslint-disable-next-line no-console
+    console.log(output.message);
+  } else {
+    // eslint-disable-next-line no-console
+    console.log(`Contract-loop check: no signal for ${file}.`);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Contract-loop check failed: ${error.message}`);
+  process.exitCode = 1;
+}

package/repo-agent-governance/tools/contract-loop/core.mjs

@@ -0,0 +1,189 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+export const TARGET_PATTERNS = [
+  ['zova/src/module/', '.ts'],
+  ['zova/src/module/', '.tsx'],
+  ['zova/src/module/', '.jsx'],
+  ['zova/src/module-vendor/', '.ts'],
+  ['zova/src/module-vendor/', '.tsx'],
+  ['zova/src/module-vendor/', '.jsx'],
+  ['zova/src/suite/', '.ts'],
+  ['zova/src/suite/', '.tsx'],
+  ['zova/src/suite/', '.jsx'],
+  ['zova/src/suite-vendor/', '.ts'],
+  ['zova/src/suite-vendor/', '.tsx'],
+  ['zova/src/suite-vendor/', '.jsx'],
+  ['vona/src/', '.ts'],
+  ['vona/src/', '.tsx'],
+  ['vona/src/', '.jsx'],
+];
+
+const FORWARD_PATH_MARKERS = ['/controller/', '/dto/', '/entity/'];
+const FORWARD_CONTENT_MARKERS = ['@Web.', '@Api.field', '@Api.body', 'v.openapi(', '@Dto<'];
+const SHARED_REVERSE_VONA_CONTENT_MARKERS = ['ZovaRender.', 'tableActionRow(', 'tableActionBulk('];
+const REVERSE_ZOVA_PATH_MARKERS = ['/src/bean/', '/src/component/', '/src/.metadata/'];
+const REVERSE_ZOVA_CONTENT_MARKERS = [
+  "declare module 'zova-module-a-openapi'",
+  'IResourceTableActionRowRecord',
+  '@TableCell<',
+  '@Component(',
+  '@Component<',
+];
+
+export const REVERSE_AUTO_SYNC_COMMANDS = [
+  { args: ['run', 'build:zova:admin'], display: 'npm run build:zova:admin' },
+  { args: ['run', 'deps:vona'], display: 'npm run deps:vona' },
+];
+
+export const EDITION_CONFIGS = {
+  basic: {
+    id: 'basic',
+    label: 'Cabloy Basic',
+    reverseVonaContentMarkers: ['zova-rest-cabloy-basic-admin'],
+    reverseAutoSyncCommands: REVERSE_AUTO_SYNC_COMMANDS,
+    reverseWebBuildCommand: 'npm run build:zova:web',
+  },
+  start: {
+    id: 'start',
+    label: 'Cabloy Start',
+    reverseVonaContentMarkers: ['zova-rest-cabloy-start-admin'],
+    reverseAutoSyncCommands: REVERSE_AUTO_SYNC_COMMANDS,
+    reverseWebBuildCommand: 'npm run build:zova:web',
+  },
+};
+
+const FALLBACK_REVERSE_VONA_CONTENT_MARKERS = [
+  ...SHARED_REVERSE_VONA_CONTENT_MARKERS,
+  ...EDITION_CONFIGS.basic.reverseVonaContentMarkers,
+  ...EDITION_CONFIGS.start.reverseVonaContentMarkers,
+];
+
+export function toPosixPath(value) {
+  return value.split(path.sep).join('/');
+}
+
+export function normalizePath(root, value) {
+  if (!value) return null;
+  try {
+    const candidate = path.isAbsolute(value) ? value : path.join(root, value);
+    return toPosixPath(path.resolve(candidate));
+  } catch {
+    return null;
+  }
+}
+
+export function resolveEdition(root) {
+  const hasBasic = existsSync(path.resolve(root, '__CABLOY_BASIC__'));
+  const hasStart = existsSync(path.resolve(root, '__CABLOY_START__'));
+  if (hasBasic && hasStart) return { kind: 'ambiguous' };
+  if (!hasBasic && !hasStart) return { kind: 'missing' };
+  return { kind: 'resolved', edition: hasBasic ? EDITION_CONFIGS.basic : EDITION_CONFIGS.start };
+}
+
+function containsAny(text, needles) {
+  return needles.some(needle => text.includes(needle));
+}
+
+function pathContainsAny(filePath, needles) {
+  return needles.some(needle => filePath.includes(needle));
+}
+
+function getReverseVonaContentMarkers(edition) {
+  if (!edition) return FALLBACK_REVERSE_VONA_CONTENT_MARKERS;
+  return [...SHARED_REVERSE_VONA_CONTENT_MARKERS, ...edition.reverseVonaContentMarkers];
+}
+
+export function isCodeFile(filePath) {
+  return TARGET_PATTERNS.some(
+    ([prefix, suffix]) => filePath.includes(prefix) && filePath.endsWith(suffix),
+  );
+}
+
+function detectForward(filePath, content) {
+  if (!filePath.includes('/vona/src/')) return null;
+  if (
+    pathContainsAny(filePath, FORWARD_PATH_MARKERS) ||
+    containsAny(content, FORWARD_CONTENT_MARKERS)
+  ) {
+    return 'Backend contract source may have changed.';
+  }
+  return null;
+}
+
+function detectReverse(filePath, content, reverseVonaContentMarkers) {
+  if (filePath.includes('/vona/src/') && containsAny(content, reverseVonaContentMarkers)) {
+    return 'Vona code is consuming frontend metadata or render resources.';
+  }
+  if (
+    filePath.includes('/zova/src/') &&
+    (pathContainsAny(filePath, REVERSE_ZOVA_PATH_MARKERS) ||
+      containsAny(content, REVERSE_ZOVA_CONTENT_MARKERS))
+  ) {
+    return 'Frontend-owned resources or metadata may affect backend consumers.';
+  }
+  return null;
+}
+
+export function analyze(filePath, content, edition) {
+  return {
+    forwardReason: detectForward(filePath, content),
+    reverseReason: detectReverse(filePath, content, getReverseVonaContentMarkers(edition)),
+  };
+}
+
+export function hasSignal(result) {
+  return Boolean(result.forwardReason || result.reverseReason);
+}
+
+export function isHighConfidenceReverseSource(filePath) {
+  return filePath.includes('/zova/src/') && pathContainsAny(filePath, REVERSE_ZOVA_PATH_MARKERS);
+}
+
+export function buildReverseGuidance(resolution) {
+  if (resolution.kind !== 'resolved') {
+    const resolutionMessage =
+      resolution.kind === 'ambiguous'
+        ? 'Both Cabloy edition markers are present, so stop before choosing an edition-specific build or generated-output path.'
+        : 'No Cabloy edition marker is present, so inspect the active package scripts and repository shape before choosing an edition-specific build or generated-output path.';
+    return `If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable. ${resolutionMessage} Then run \`npm run deps:vona\` once the active edition is resolved.`;
+  }
+  const edition = resolution.edition;
+  const autoSyncCommands = edition.reverseAutoSyncCommands
+    .map(command => `\`${command.display}\``)
+    .join(', then ');
+  return `If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable, run ${autoSyncCommands}, and also run \`${edition.reverseWebBuildCommand}\` when the Web flavor is affected in this ${edition.label} repo.`;
+}
+
+export function buildMessages(
+  result,
+  resolution,
+  reverseSyncOutcome = { kind: 'not-applicable', message: '' },
+) {
+  const messages = [
+    "Contract-loop gate: this change may affect Cabloy's bidirectional contract loop.",
+  ];
+  if (resolution.kind === 'ambiguous') {
+    messages.push(
+      'Both Cabloy edition markers are present, so stop before choosing an edition-specific build, generated-output path, or auto-sync action.',
+    );
+  }
+  if (result.forwardReason) {
+    messages.push(
+      `Forward chain: ${result.forwardReason} If backend contract truth changed, verify the emitted OpenAPI/contract output and regenerate the frontend consumer path before considering the task done.`,
+    );
+    messages.push(
+      'After forward regeneration, keep frontend follow-up thin: prefer semantic model facades and reuse the existing resource-owner when the custom API still belongs to the same resource.',
+    );
+  }
+  if (result.reverseReason) {
+    messages.push(`Reverse chain: ${result.reverseReason} ${buildReverseGuidance(resolution)}`);
+    if (reverseSyncOutcome.message) messages.push(reverseSyncOutcome.message);
+    if (reverseSyncOutcome.kind === 'failure') {
+      messages.push(
+        'Please review the failure before continuing. If generated artifacts already contain the expected changes but consumers still behave stale, suspect local dependency drift before making more source edits.',
+      );
+    }
+  }
+  return messages.join(' ');
+}