snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-agent-skills/scripts/__tests__/distribution-validation.spec.js

@@ -0,0 +1,372 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+
+import { CANONICAL_SKILL_NAMES } from '../lib.js';
+import {
+  assertSkillFrontmatter,
+  assertSelfContainedReferences,
+  assertPortability,
+  assertSharedReferenceConsistency,
+  assertOperatingRulesShipped,
+  assertNoDanglingDocMentions,
+  validatePortableSkills,
+} from '../validate-distribution.js';
+import { writeFixtureFile } from './fixtures.js';
+
+const writeValidSkill = (skillsRoot, skillName) => {
+  writeFixtureFile(
+    skillsRoot,
+    `${skillName}/SKILL.md`,
+    `---\nname: ${skillName}\ndescription: Demo skill.\n---\n\n# When To Use\n\nRead \`references/concepts/basics.md\` and \`references/concepts/operating-rules.md\`.\n`,
+  );
+  writeFixtureFile(
+    skillsRoot,
+    `${skillName}/references/concepts/basics.md`,
+    'Basics.\n',
+  );
+  writeFixtureFile(
+    skillsRoot,
+    `${skillName}/references/concepts/operating-rules.md`,
+    'Rules.\n',
+  );
+};
+
+describe('validatePortableSkills', () => {
+  let skillsRoot;
+  let failures;
+  const fail = (message) => failures.push(message);
+
+  beforeEach(() => {
+    skillsRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'agent-skills-validate-'),
+    );
+    failures = [];
+  });
+
+  afterEach(() => {
+    fs.rmSync(skillsRoot, { recursive: true, force: true });
+  });
+
+  it('should pass for a complete, self-contained skill set', () => {
+    for (const skillName of CANONICAL_SKILL_NAMES) {
+      writeValidSkill(skillsRoot, skillName);
+    }
+
+    writeFixtureFile(
+      skillsRoot,
+      'create-app/SKILL.md',
+      '---\nname: create-app\ndescription: Demo skill.\n---\n\n# When To Use\n\nWorks against self-hosted instances. Read `references/concepts/operating-rules.md`.\n',
+    );
+
+    validatePortableSkills(skillsRoot, fail);
+
+    assert.deepEqual(failures, []);
+  });
+
+  it('should fail when a portable skill is missing or unexpected', () => {
+    writeValidSkill(skillsRoot, 'create-app');
+    writeValidSkill(skillsRoot, 'not-a-twenty-skill');
+
+    validatePortableSkills(skillsRoot, fail);
+
+    assert.ok(failures.includes('portable skill is missing: develop-app'));
+    assert.ok(
+      failures.includes('unexpected skill directory: not-a-twenty-skill'),
+    );
+  });
+
+  it('should fail when frontmatter name does not match the directory', () => {
+    writeFixtureFile(
+      skillsRoot,
+      'create-app/SKILL.md',
+      '---\nname: other-name\ndescription: Demo.\n---\n\n# When To Use\n\nText.\n',
+    );
+
+    assertSkillFrontmatter({ skillsRoot, skillName: 'create-app', fail });
+
+    assert.ok(
+      failures.includes(
+        'create-app/SKILL.md frontmatter name must match its directory',
+      ),
+    );
+  });
+
+  it('should fail when frontmatter includes extra fields or misses the trigger section', () => {
+    writeFixtureFile(
+      skillsRoot,
+      'create-app/SKILL.md',
+      '---\nname: create-app\ndescription: Demo.\nlicense: MIT\n---\n\nNo trigger section.\n',
+    );
+
+    assertSkillFrontmatter({ skillsRoot, skillName: 'create-app', fail });
+
+    assert.ok(
+      failures.includes(
+        'create-app/SKILL.md frontmatter should only include name and description',
+      ),
+    );
+    assert.ok(
+      failures.includes(
+        'create-app/SKILL.md must include a "When To Use" section',
+      ),
+    );
+  });
+
+  it('should fail when a reference escapes the skill directory', () => {
+    writeFixtureFile(
+      skillsRoot,
+      'create-app/SKILL.md',
+      '---\nname: create-app\ndescription: Demo.\n---\n\n# When To Use\n\nRead `../../references/concepts/basics.md`.\n',
+    );
+
+    assertSelfContainedReferences({
+      skillsRoot,
+      skillName: 'create-app',
+      fail,
+    });
+
+    assert.ok(
+      failures.some((failure) =>
+        failure.includes('references a path outside its skill directory'),
+      ),
+    );
+  });
+
+  it('should fail when a referenced file is missing after installation', () => {
+    writeFixtureFile(
+      skillsRoot,
+      'create-app/SKILL.md',
+      '---\nname: create-app\ndescription: Demo.\n---\n\n# When To Use\n\nRead `references/concepts/missing.md`.\n',
+    );
+
+    assertSelfContainedReferences({
+      skillsRoot,
+      skillName: 'create-app',
+      fail,
+    });
+
+    assert.ok(
+      failures.includes(
+        'create-app/SKILL.md references a missing file: references/concepts/missing.md',
+      ),
+    );
+  });
+
+  it('should fail when a skill ships an unexpected executable file', () => {
+    writeValidSkill(skillsRoot, 'create-app');
+    writeFixtureFile(skillsRoot, 'create-app/script.js', 'console.log(1);\n');
+
+    assertSelfContainedReferences({
+      skillsRoot,
+      skillName: 'create-app',
+      fail,
+    });
+
+    assert.ok(
+      failures.includes(
+        'portable skills may only contain markdown and agents/openai.yaml: create-app/script.js',
+      ),
+    );
+  });
+
+  it('should fail when content depends on the codex plugin wrapper', () => {
+    writeFixtureFile(
+      skillsRoot,
+      'create-app/SKILL.md',
+      '---\nname: create-app\ndescription: Demo.\n---\n\n# When To Use\n\nRun `bash packages/twenty-codex-plugin/scripts/setup-mcp.sh`.\n',
+    );
+
+    assertPortability({ skillsRoot, skillName: 'create-app', fail });
+
+    assert.ok(
+      failures.includes(
+        'create-app/SKILL.md must not depend on non-portable content: packages/twenty-codex-plugin',
+      ),
+    );
+  });
+
+  it('should fail on non-placeholder URLs', () => {
+    writeFixtureFile(
+      skillsRoot,
+      'create-app/SKILL.md',
+      '---\nname: create-app\ndescription: Demo.\n---\n\n# When To Use\n\nVisit https://some-random-host.dev/docs.\n',
+    );
+
+    assertPortability({ skillsRoot, skillName: 'create-app', fail });
+
+    assert.ok(
+      failures.includes(
+        'non-placeholder URL found in create-app/SKILL.md: https://some-random-host.dev',
+      ),
+    );
+  });
+
+  it('should fail when a shared reference diverges between skills', () => {
+    writeValidSkill(skillsRoot, 'create-app');
+    writeValidSkill(skillsRoot, 'develop-app');
+    writeFixtureFile(
+      skillsRoot,
+      'develop-app/references/concepts/basics.md',
+      'Diverged basics.\n',
+    );
+
+    assertSharedReferenceConsistency(
+      skillsRoot,
+      ['create-app', 'develop-app'],
+      fail,
+    );
+
+    assert.deepEqual(failures, [
+      'shared reference diverges between create-app and develop-app: references/concepts/basics.md',
+    ]);
+  });
+});
+
+describe('assertOperatingRulesShipped', () => {
+  let skillsRoot;
+  let failures;
+  const fail = (message) => failures.push(message);
+
+  beforeEach(() => {
+    skillsRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-rules-'));
+    failures = [];
+  });
+
+  afterEach(() => {
+    fs.rmSync(skillsRoot, { recursive: true, force: true });
+  });
+
+  it('should fail when an app skill does not ship the operating rules', () => {
+    for (const skillName of CANONICAL_SKILL_NAMES) {
+      writeValidSkill(skillsRoot, skillName);
+    }
+
+    fs.rmSync(
+      path.join(
+        skillsRoot,
+        'manage-app/references/concepts/operating-rules.md',
+      ),
+    );
+
+    assertOperatingRulesShipped(skillsRoot, fail);
+
+    assert.ok(
+      failures.some((failure) =>
+        failure.startsWith('manage-app does not ship'),
+      ),
+      `expected a missing operating-rules failure, got: ${failures.join('; ')}`,
+    );
+  });
+
+  it('should fail when an app skill does not link to the operating rules', () => {
+    for (const skillName of CANONICAL_SKILL_NAMES) {
+      writeValidSkill(skillsRoot, skillName);
+    }
+
+    writeFixtureFile(
+      skillsRoot,
+      'publish-app/SKILL.md',
+      '---\nname: publish-app\ndescription: Demo skill.\n---\n\n# When To Use\n\nNo rules link here.\n',
+    );
+
+    assertOperatingRulesShipped(skillsRoot, fail);
+
+    assert.ok(
+      failures.some((failure) =>
+        failure.includes('publish-app/SKILL.md must link'),
+      ),
+      `expected a missing link failure, got: ${failures.join('; ')}`,
+    );
+  });
+});
+
+describe('assertNoDanglingDocMentions', () => {
+  let skillsRoot;
+  let failures;
+  const fail = (message) => failures.push(message);
+
+  beforeEach(() => {
+    skillsRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'agent-skills-mentions-'),
+    );
+    failures = [];
+  });
+
+  afterEach(() => {
+    fs.rmSync(skillsRoot, { recursive: true, force: true });
+  });
+
+  it('should fail when a skill mentions a doc another skill ships but it does not', () => {
+    writeValidSkill(skillsRoot, 'create-app');
+    writeValidSkill(skillsRoot, 'develop-app');
+    writeFixtureFile(
+      skillsRoot,
+      'develop-app/references/develop-app/front-components.md',
+      'Front components.\n',
+    );
+    writeFixtureFile(
+      skillsRoot,
+      'create-app/references/design/front-component-ui.md',
+      'Use `front-components.md` for exact imports.\n',
+    );
+
+    assertNoDanglingDocMentions(
+      skillsRoot,
+      ['create-app', 'develop-app'],
+      fail,
+    );
+
+    assert.ok(
+      failures.some(
+        (failure) =>
+          failure.includes('front-components.md') &&
+          failure.includes('create-app does not ship'),
+      ),
+      `expected a dangling mention failure, got: ${failures.join('; ')}`,
+    );
+  });
+
+  it('should ignore filenames that belong to the user rather than the collection', () => {
+    writeValidSkill(skillsRoot, 'publish-app');
+    writeFixtureFile(
+      skillsRoot,
+      'publish-app/references/concepts/basics.md',
+      'Inspect `README.md` and `package.json` in the app.\n',
+    );
+
+    assertNoDanglingDocMentions(skillsRoot, ['publish-app'], fail);
+
+    assert.deepEqual(failures, []);
+  });
+});
+
+describe('verify-install argument handling', () => {
+  let installRoot;
+
+  beforeEach(() => {
+    installRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'agent-skills-install-'),
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(installRoot, { recursive: true, force: true });
+  });
+
+  it('should not report escaping references when given a relative install root', () => {
+    const failures = [];
+    const fail = (message) => failures.push(message);
+
+    writeValidSkill(installRoot, 'create-app');
+    assertSelfContainedReferences({
+      skillsRoot: path.resolve(installRoot),
+      skillName: 'create-app',
+      fail,
+    });
+
+    assert.deepEqual(failures, []);
+  });
+});

packages/twenty-agent-skills/scripts/__tests__/fixtures.js

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const writeFixtureFile = (root, relativePath, contents) => {
+  const absolutePath = path.join(root, relativePath);
+
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, contents);
+};
+
+export { writeFixtureFile };

packages/twenty-agent-skills/scripts/__tests__/lib.spec.js

@@ -0,0 +1,355 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+
+import {
+  rewriteSkillReferenceLinks,
+  collectSkillSeedReferences,
+  resolveReferenceClosure,
+  buildPortableSkills,
+  buildDistribution,
+  CANONICAL_SKILL_NAMES,
+  listFiles,
+} from '../lib.js';
+import { writeFixtureFile } from './fixtures.js';
+
+describe('rewriteSkillReferenceLinks', () => {
+  it('should rewrite plugin-relative reference links to skill-relative links', () => {
+    const rewritten = rewriteSkillReferenceLinks(
+      'Read `../../references/concepts/how-apps-work.md` and `../../references/develop-app/tests.md`.',
+    );
+
+    assert.equal(
+      rewritten,
+      'Read `references/concepts/how-apps-work.md` and `references/develop-app/tests.md`.',
+    );
+  });
+
+  it('should leave skill-relative links untouched', () => {
+    const contents = 'Read `references/concepts/how-apps-work.md`.';
+
+    assert.equal(rewriteSkillReferenceLinks(contents), contents);
+  });
+});
+
+describe('collectSkillSeedReferences', () => {
+  it('should collect plugin-relative and skill-relative reference mentions', () => {
+    const seeds = collectSkillSeedReferences(
+      'Read `../../references/concepts/how-apps-work.md` then `references/design/front-component-ui.md`.',
+    );
+
+    assert.deepEqual([...seeds].sort(), [
+      'concepts/how-apps-work.md',
+      'design/front-component-ui.md',
+    ]);
+  });
+});
+
+describe('resolveReferenceClosure', () => {
+  let fixtureRoot;
+
+  beforeEach(() => {
+    fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-lib-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(fixtureRoot, { recursive: true, force: true });
+  });
+
+  it('should follow sibling-scope and same-directory reference mentions transitively', () => {
+    writeFixtureFile(fixtureRoot, 'references/a/one.md', 'See `../b/two.md`.');
+    writeFixtureFile(fixtureRoot, 'references/b/two.md', 'See `three.md`.');
+    writeFixtureFile(fixtureRoot, 'references/b/three.md', 'Terminal doc.');
+
+    const closure = resolveReferenceClosure(
+      path.join(fixtureRoot, 'references'),
+      new Set(['a/one.md']),
+    );
+
+    assert.deepEqual([...closure].sort(), [
+      'a/one.md',
+      'b/three.md',
+      'b/two.md',
+    ]);
+  });
+
+  it('should ignore backtick tokens that only look like markdown files', () => {
+    writeFixtureFile(
+      fixtureRoot,
+      'references/design/ui.md',
+      'Use `themeCssVariables.font.size.md` for medium font size.',
+    );
+
+    const closure = resolveReferenceClosure(
+      path.join(fixtureRoot, 'references'),
+      new Set(['design/ui.md']),
+    );
+
+    assert.deepEqual([...closure], ['design/ui.md']);
+  });
+
+  it('should throw when a referenced doc does not exist', () => {
+    writeFixtureFile(
+      fixtureRoot,
+      'references/a/one.md',
+      'See `../b/missing.md`.',
+    );
+
+    assert.throws(
+      () =>
+        resolveReferenceClosure(
+          path.join(fixtureRoot, 'references'),
+          new Set(['a/one.md']),
+        ),
+      /referenced doc does not exist: references\/b\/missing\.md/,
+    );
+  });
+});
+
+describe('buildPortableSkills', () => {
+  let sourceRoot;
+  let outputRoot;
+
+  beforeEach(() => {
+    sourceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-source-'));
+    outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-output-'));
+    writeFixtureFile(
+      sourceRoot,
+      'skills/demo-skill/SKILL.md',
+      '---\nname: demo-skill\ndescription: Demo.\n---\n\nRead `../../references/concepts/basics.md`.\n',
+    );
+    writeFixtureFile(
+      sourceRoot,
+      'skills/demo-skill/agents/openai.yaml',
+      'interface: {}\n',
+    );
+    writeFixtureFile(
+      sourceRoot,
+      'references/concepts/basics.md',
+      'See `../deep/detail.md`.',
+    );
+    writeFixtureFile(sourceRoot, 'references/deep/detail.md', 'Terminal doc.');
+  });
+
+  afterEach(() => {
+    fs.rmSync(sourceRoot, { recursive: true, force: true });
+    fs.rmSync(outputRoot, { recursive: true, force: true });
+  });
+
+  it('should emit a self-contained skill including optional Codex display metadata', () => {
+    buildPortableSkills({ sourceRoot, outputRoot, skillNames: ['demo-skill'] });
+
+    const skillMarkdown = fs.readFileSync(
+      path.join(outputRoot, 'demo-skill', 'SKILL.md'),
+      'utf8',
+    );
+
+    assert.match(skillMarkdown, /`references\/concepts\/basics\.md`/);
+    assert.ok(
+      fs.existsSync(
+        path.join(outputRoot, 'demo-skill', 'references/concepts/basics.md'),
+      ),
+    );
+    assert.ok(
+      fs.existsSync(
+        path.join(outputRoot, 'demo-skill', 'references/deep/detail.md'),
+      ),
+    );
+    assert.equal(
+      fs.readFileSync(
+        path.join(outputRoot, 'demo-skill', 'agents/openai.yaml'),
+        'utf8',
+      ),
+      'interface: {}\n',
+    );
+  });
+
+  it('should remove stale files from a previous build', () => {
+    writeFixtureFile(outputRoot, 'stale-skill/SKILL.md', 'stale');
+
+    buildPortableSkills({ sourceRoot, outputRoot, skillNames: ['demo-skill'] });
+
+    assert.ok(!fs.existsSync(path.join(outputRoot, 'stale-skill')));
+  });
+
+  it('should throw when a canonical skill is missing', () => {
+    assert.throws(
+      () =>
+        buildPortableSkills({
+          sourceRoot,
+          outputRoot,
+          skillNames: ['absent-skill'],
+        }),
+      /canonical skill is missing: skills\/absent-skill\/SKILL\.md/,
+    );
+  });
+});
+
+describe('resolveReferenceClosure cross-scope mentions', () => {
+  let referencesRoot;
+
+  beforeEach(() => {
+    referencesRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'agent-skills-closure-'),
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(referencesRoot, { recursive: true, force: true });
+  });
+
+  it('should throw when a bare mention names a doc that lives in another scope', () => {
+    writeFixtureFile(
+      referencesRoot,
+      'design/front-component-ui.md',
+      'Use `front-components.md` for exact imports.\n',
+    );
+    writeFixtureFile(
+      referencesRoot,
+      'develop-app/front-components.md',
+      'Front components.\n',
+    );
+
+    assert.throws(
+      () =>
+        resolveReferenceClosure(referencesRoot, [
+          'design/front-component-ui.md',
+        ]),
+      /lives at references\/develop-app\/front-components\.md/,
+    );
+  });
+
+  it('should still ignore bare mentions that name no reference doc', () => {
+    writeFixtureFile(
+      referencesRoot,
+      'publish-app/prepare-for-app-store.md',
+      'Write the app `README.md` and set `themeCssVariables.font.size.md`.\n',
+    );
+
+    const closure = resolveReferenceClosure(referencesRoot, [
+      'publish-app/prepare-for-app-store.md',
+    ]);
+
+    assert.deepEqual([...closure], ['publish-app/prepare-for-app-store.md']);
+  });
+});
+
+describe('buildDistribution', () => {
+  let fixtureRoot;
+
+  beforeEach(() => {
+    fixtureRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'twenty-distribution-'),
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(fixtureRoot, { recursive: true, force: true });
+  });
+
+  it('builds one standalone plugin and skill collection without modifying source', () => {
+    const sourceRoot = path.join(fixtureRoot, 'source');
+    const outputRoot = path.join(fixtureRoot, 'dist');
+    const files = [
+      '.codex-plugin',
+      '.mcp.json',
+      'assets',
+      'skills',
+      'scripts/setup-mcp.sh',
+    ];
+
+    writeFixtureFile(
+      sourceRoot,
+      'package.json',
+      JSON.stringify({
+        name: 'twenty-agent-skills',
+        version: '0.1.0',
+        license: 'AGPL-3.0',
+        files,
+        scripts: { build: 'node scripts/build.js' },
+      }),
+    );
+    writeFixtureFile(
+      sourceRoot,
+      '.codex-plugin/plugin.json',
+      '{"name":"twenty","skills":"./skills/"}',
+    );
+    writeFixtureFile(sourceRoot, '.mcp.json', '{"mcpServers":{}}');
+    writeFixtureFile(sourceRoot, 'assets/logo.png', 'binary-asset');
+    writeFixtureFile(sourceRoot, 'scripts/setup-mcp.sh', '#!/bin/sh\nexit 0\n');
+    fs.chmodSync(path.join(sourceRoot, 'scripts/setup-mcp.sh'), 0o755);
+    writeFixtureFile(sourceRoot, 'scripts/build.js', 'build-only');
+    writeFixtureFile(
+      sourceRoot,
+      'references/concepts/basics.md',
+      'Shared concept.',
+    );
+
+    for (const skillName of CANONICAL_SKILL_NAMES) {
+      writeFixtureFile(
+        sourceRoot,
+        `skills/${skillName}/SKILL.md`,
+        'Read `../../references/concepts/basics.md`.',
+      );
+      writeFixtureFile(
+        sourceRoot,
+        `skills/${skillName}/agents/openai.yaml`,
+        'interface: {}\n',
+      );
+    }
+
+    const snapshot = (root) =>
+      listFiles(root).map((file) => [
+        path.relative(root, file),
+        fs.readFileSync(file),
+      ]);
+    const sourceBefore = snapshot(sourceRoot);
+    buildDistribution({ sourceRoot, outputRoot });
+    const distributionBefore = snapshot(outputRoot);
+    writeFixtureFile(outputRoot, 'removed-skill/SKILL.md', 'stale');
+    buildDistribution({ sourceRoot, outputRoot });
+
+    assert.deepEqual(snapshot(sourceRoot), sourceBefore);
+    assert.deepEqual(snapshot(outputRoot), distributionBefore);
+    assert.ok(
+      fs.existsSync(path.join(outputRoot, '.codex-plugin/plugin.json')),
+    );
+    assert.ok(fs.existsSync(path.join(outputRoot, '.mcp.json')));
+    assert.ok(fs.existsSync(path.join(outputRoot, 'assets/logo.png')));
+    assert.ok(!fs.existsSync(path.join(outputRoot, 'scripts/build.js')));
+    assert.equal(
+      fs.statSync(path.join(outputRoot, 'scripts/setup-mcp.sh')).mode & 0o777,
+      0o755,
+    );
+    assert.equal(
+      JSON.parse(fs.readFileSync(path.join(outputRoot, 'package.json'), 'utf8'))
+        .scripts,
+      undefined,
+    );
+
+    fs.rmSync(sourceRoot, { recursive: true });
+    for (const skillName of CANONICAL_SKILL_NAMES) {
+      const skillRoot = path.join(outputRoot, 'skills', skillName);
+      assert.equal(
+        fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8'),
+        'Read `references/concepts/basics.md`.',
+      );
+      assert.equal(
+        fs.readFileSync(
+          path.join(skillRoot, 'references/concepts/basics.md'),
+          'utf8',
+        ),
+        'Shared concept.',
+      );
+      assert.equal(
+        fs.readFileSync(path.join(skillRoot, 'agents/openai.yaml'), 'utf8'),
+        'interface: {}\n',
+      );
+      assert.ok(
+        listFiles(skillRoot).every((file) => fs.lstatSync(file).isFile()),
+      );
+    }
+  });
+});

packages/twenty-agent-skills/scripts/__tests__/source-validation.spec.js

@@ -0,0 +1,449 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import * as metadata from '../validators/metadata.js';
+import * as assets from '../validators/assets.js';
+import * as skills from '../validators/skills.js';
+import * as references from '../validators/references.js';
+import * as crossDocContracts from '../validators/cross-doc-contracts.js';
+import * as setupHelper from '../validators/setup-helper.js';
+
+const PLUGIN_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+const PLUGIN_JSON_PATH = path.join(PLUGIN_ROOT, '.codex-plugin', 'plugin.json');
+const PACKAGE_JSON_PATH = path.join(PLUGIN_ROOT, 'package.json');
+const MCP_JSON_PATH = path.join(PLUGIN_ROOT, '.mcp.json');
+const MARKETPLACE_TEMPLATE_PATH = path.join(PLUGIN_ROOT, 'templates', 'marketplace.example.json');
+
+const collectFailures = (assertion) => {
+  const failures = [];
+  assertion((message) => failures.push(message));
+  return failures;
+};
+
+const withFileMutation = (filePath, mutator, body) => {
+  const original = fs.readFileSync(filePath, 'utf8');
+
+  try {
+    fs.writeFileSync(filePath, mutator(original));
+    body();
+  } finally {
+    fs.writeFileSync(filePath, original);
+  }
+};
+
+const withJsonMutation = (filePath, mutator, body) =>
+  withFileMutation(
+    filePath,
+    (original) => {
+      const data = JSON.parse(original);
+      mutator(data);
+      return `${JSON.stringify(data, null, 2)}\n`;
+    },
+    body,
+  );
+
+const withExtraFile = (filePath, contents, body) => {
+  try {
+    fs.writeFileSync(filePath, contents);
+    body();
+  } finally {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Smoke tests — every assertion should pass on the current plugin state.
+// ---------------------------------------------------------------------------
+
+test('assertJsonMetadata passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(metadata.assertJsonMetadata), []);
+});
+
+test('assertNoBundledMcpConfig passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(metadata.assertNoBundledMcpConfig), []);
+});
+
+test('assertInterfaceFields passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(metadata.assertInterfaceFields), []);
+});
+
+test('assertMarketplaceTemplate passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(metadata.assertMarketplaceTemplate), []);
+});
+
+test('assertAssets passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(assets.assertAssets), []);
+});
+
+test('assertSkills passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(skills.assertSkills), []);
+});
+
+test('assertSkillTriggerPhrases passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(skills.assertSkillTriggerPhrases), []);
+});
+
+test('assertNoLegacySkillReferences passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(skills.assertNoLegacySkillReferences), []);
+});
+
+test('assertReferences passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(references.assertReferences), []);
+});
+
+test('assertHowAppsWork passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(references.assertHowAppsWork), []);
+});
+
+test('assertTwentyMcpFormattingContract passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(crossDocContracts.assertTwentyMcpFormattingContract), []);
+});
+
+test('assertFrontComponentGuidance passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(crossDocContracts.assertFrontComponentGuidance), []);
+});
+
+test('assertFrontComponentGuidance catches independent UI version guidance', () => {
+  const frontComponentsPath = path.join(
+    PLUGIN_ROOT,
+    'references/develop-app/front-components.md',
+  );
+
+  withFileMutation(
+    frontComponentsPath,
+    (contents) => contents.replace(
+      'at the same version as `twenty-sdk` and `twenty-client-sdk`',
+      'at an independent version',
+    ),
+    () => {
+      const failures = collectFailures(crossDocContracts.assertFrontComponentGuidance);
+      assert.ok(failures.some((failure) => failure.includes('same version as')));
+    },
+  );
+});
+
+test('assertCliGuidanceSplit passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(crossDocContracts.assertCliGuidanceSplit), []);
+});
+
+test('assertCliGuidanceSplit catches deprecated dev --once guidance', () => {
+  const cliAndSyncPath = path.join(
+    PLUGIN_ROOT,
+    'references',
+    'manage-app',
+    'cli-and-sync.md',
+  );
+
+  withFileMutation(
+    cliAndSyncPath,
+    (contents) => contents.replace('yarn twenty apply', 'yarn twenty dev --once'),
+    () => {
+      const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);
+
+      assert.ok(
+        failures.some((failure) => failure.includes('yarn twenty dev --once')),
+      );
+    },
+  );
+});
+
+test('assertCliGuidanceSplit catches deprecated guidance outside the CLI reference', () => {
+  const manageSkillPath = path.join(
+    PLUGIN_ROOT,
+    'skills',
+    'manage-app',
+    'SKILL.md',
+  );
+
+  withFileMutation(
+    manageSkillPath,
+    (contents) => `${contents}\nRun yarn twenty dev --once after editing.\n`,
+    () => {
+      const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);
+
+      assert.ok(
+        failures.some(
+          (failure) =>
+            failure.includes('skills/manage-app/SKILL.md') &&
+            failure.includes('yarn twenty dev --once'),
+        ),
+      );
+    },
+  );
+});
+
+test('assertCliGuidanceSplit catches stale one-shot sync terminology', () => {
+  const standalonePagesPath = path.join(
+    PLUGIN_ROOT,
+    'references',
+    'develop-app',
+    'standalone-pages.md',
+  );
+
+  withFileMutation(
+    standalonePagesPath,
+    (contents) => `${contents}\nUse one-shot sync for verification.\n`,
+    () => {
+      const failures = collectFailures(crossDocContracts.assertCliGuidanceSplit);
+
+      assert.ok(
+        failures.some(
+          (failure) =>
+            failure.includes('references/develop-app/standalone-pages.md') &&
+            failure.includes('one-shot sync'),
+        ),
+      );
+    },
+  );
+});
+
+test('assertTestingGuidance passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(crossDocContracts.assertTestingGuidance), []);
+});
+
+test('assertSetupHelper passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(setupHelper.assertSetupHelper), []);
+});
+
+// ---------------------------------------------------------------------------
+// Negative cases — each assertion catches its targeted failure.
+// ---------------------------------------------------------------------------
+
+test('assertJsonMetadata catches version mismatch between package.json and plugin.json', () => {
+  withJsonMutation(PACKAGE_JSON_PATH, (pkg) => { pkg.version = '99.99.99'; }, () => {
+    const failures = collectFailures(metadata.assertJsonMetadata);
+    assert.ok(
+      failures.some((f) => f.includes('version must match')),
+      `expected version-mismatch failure, got: ${failures.join('; ')}`,
+    );
+  });
+});
+
+test('assertJsonMetadata catches missing .mcp.json from package.json files', () => {
+  withJsonMutation(PACKAGE_JSON_PATH, (pkg) => {
+    pkg.files = pkg.files.filter((f) => f !== '.mcp.json');
+  }, () => {
+    const failures = collectFailures(metadata.assertJsonMetadata);
+    assert.ok(failures.some((f) => f.includes('.mcp.json')));
+  });
+});
+
+test('assertJsonMetadata catches non-canonical MCP server', () => {
+  withJsonMutation(MCP_JSON_PATH, (mcp) => {
+    mcp.mcpServers['rogue-server'] = { url: 'https://example.com/mcp' };
+  }, () => {
+    const failures = collectFailures(metadata.assertJsonMetadata);
+    assert.ok(failures.some((f) => f.includes('twenty-docs')));
+  });
+});
+
+test('assertNoBundledMcpConfig catches a bundled .app.json', () => {
+  const stub = path.join(PLUGIN_ROOT, '.app.json');
+  withExtraFile(stub, '{}', () => {
+    const failures = collectFailures(metadata.assertNoBundledMcpConfig);
+    assert.ok(failures.some((f) => f.includes('app declarations must not be shipped')));
+  });
+});
+
+test('assertNoBundledMcpConfig catches a non-placeholder URL', () => {
+  const stub = path.join(PLUGIN_ROOT, 'scratch-url-check.md');
+  withExtraFile(stub, 'see https://internal.private-domain.test/secret for details', () => {
+    const failures = collectFailures(metadata.assertNoBundledMcpConfig);
+    assert.ok(failures.some((f) => f.includes('non-placeholder URL')));
+  });
+});
+
+test('assertNoBundledMcpConfig catches a bearer token', () => {
+  const stub = path.join(PLUGIN_ROOT, 'scratch-bearer.md');
+  withExtraFile(stub, 'Authorization: Bearer abc123def456ghi789jkl012mno', () => {
+    const failures = collectFailures(metadata.assertNoBundledMcpConfig);
+    assert.ok(failures.some((f) => f.includes('bearer token')));
+  });
+});
+
+test('source scans ignore generated distribution files', () => {
+  const distributionRoot = path.join(PLUGIN_ROOT, 'dist');
+  fs.mkdirSync(distributionRoot, { recursive: true });
+  const fixtureRoot = fs.mkdtempSync(path.join(distributionRoot, 'source-validation-'));
+
+  try {
+    fs.writeFileSync(path.join(fixtureRoot, '.mcp.json'), '{}');
+    fs.writeFileSync(path.join(fixtureRoot, 'SKILL.md'), 'name: create-an-app\n');
+
+    assert.deepStrictEqual(collectFailures(metadata.assertNoBundledMcpConfig), []);
+    assert.deepStrictEqual(collectFailures(skills.assertNoLegacySkillReferences), []);
+  } finally {
+    fs.rmSync(fixtureRoot, { recursive: true, force: true });
+  }
+});
+
+test('assertInterfaceFields catches invalid brandColor', () => {
+  withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.brandColor = 'red'; }, () => {
+    const failures = collectFailures(metadata.assertInterfaceFields);
+    assert.ok(failures.some((f) => f.includes('brandColor must match')));
+  });
+});
+
+test('assertInterfaceFields catches too-long shortDescription', () => {
+  withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.shortDescription = 'x'.repeat(100); }, () => {
+    const failures = collectFailures(metadata.assertInterfaceFields);
+    assert.ok(failures.some((f) => f.includes('shortDescription must be 64')));
+  });
+});
+
+test('assertInterfaceFields catches unknown category', () => {
+  withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.category = 'Photography'; }, () => {
+    const failures = collectFailures(metadata.assertInterfaceFields);
+    assert.ok(failures.some((f) => f.includes('category must be one of')));
+  });
+});
+
+test('assertInterfaceFields catches invalid capability', () => {
+  withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.capabilities = ['Magic']; }, () => {
+    const failures = collectFailures(metadata.assertInterfaceFields);
+    assert.ok(failures.some((f) => f.includes('capabilities contains invalid value')));
+  });
+});
+
+test('assertInterfaceFields catches empty defaultPrompt', () => {
+  withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.defaultPrompt = []; }, () => {
+    const failures = collectFailures(metadata.assertInterfaceFields);
+    assert.ok(failures.some((f) => f.includes('defaultPrompt')));
+  });
+});
+
+test('assertAssets catches a missing screenshot reference', () => {
+  withJsonMutation(PLUGIN_JSON_PATH, (j) => {
+    j.interface.screenshots = ['./assets/screenshots/nonexistent.png'];
+  }, () => {
+    const failures = collectFailures(assets.assertAssets);
+    assert.ok(failures.some((f) => f.includes('screenshots entry is missing')));
+  });
+});
+
+test('assertAssets catches a non-PNG logo', () => {
+  withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.logo = './assets/twenty-logo.svg'; }, () => {
+    const failures = collectFailures(assets.assertAssets);
+    assert.ok(failures.some((f) => f.includes('logo must be a PNG')));
+  });
+});
+
+test('assertMarketplaceTemplate requires marketplace identity', () => {
+  withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {
+    delete template.name;
+    delete template.interface;
+  }, () => {
+    const failures = collectFailures(metadata.assertMarketplaceTemplate);
+    assert.ok(failures.some((failure) => failure.includes('name must be a non-empty string')));
+    assert.ok(failures.some((failure) => failure.includes('interface.displayName must be a non-empty string')));
+  });
+});
+
+test('assertMarketplaceTemplate catches the legacy source descriptor', () => {
+  withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {
+    template.plugins[0].source = {
+      type: 'local',
+      path: './packages/twenty-agent-skills/dist',
+    };
+  }, () => {
+    const failures = collectFailures(metadata.assertMarketplaceTemplate);
+    assert.ok(failures.some((failure) => failure.includes('source.source must be local')));
+  });
+});
+
+for (const [field, value] of [['installation', 'manual'], ['authentication', 'user-local']]) {
+  test(`assertMarketplaceTemplate catches legacy ${field} policy`, () => {
+    withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {
+      template.plugins[0].policy[field] = value;
+    }, () => {
+      const failures = collectFailures(metadata.assertMarketplaceTemplate);
+      assert.ok(failures.some((failure) => failure.includes(`policy.${field} must be`)));
+    });
+  });
+}
+
+test('assertMarketplaceTemplate requires the installable distribution path', () => {
+  withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {
+    template.plugins[0].source.path = './packages/twenty-agent-skills';
+  }, () => {
+    const failures = collectFailures(metadata.assertMarketplaceTemplate);
+    assert.ok(failures.some((failure) => failure.includes('source.path must be ./packages/twenty-agent-skills/dist')));
+  });
+});
+
+test('assertSkillTriggerPhrases catches a SKILL.md missing the When To Use section', () => {
+  const skillPath = path.join(PLUGIN_ROOT, 'skills', 'create-app', 'SKILL.md');
+  withFileMutation(skillPath, (original) => original.replace(/^#+\s+When To Use[\s\S]*?(?=\n#\s)/m, ''), () => {
+    const failures = collectFailures(skills.assertSkillTriggerPhrases);
+    assert.ok(failures.some((f) => f.includes('create-app') && f.includes('When To Use')));
+  });
+});
+
+test('assertTestingGuidance catches missing manage-app test target instructions', () => {
+  const skillPath = path.join(PLUGIN_ROOT, 'skills', 'manage-app', 'SKILL.md');
+  withFileMutation(skillPath, (original) => original.replace('TWENTY_API_URL=http://localhost:2021 yarn test', 'yarn test'), () => {
+    const failures = collectFailures(crossDocContracts.assertTestingGuidance);
+    assert.ok(
+      failures.some((f) => f.includes('manage-app/SKILL.md') && f.includes('TWENTY_API_URL')),
+      `expected manage-app test target failure, got: ${failures.join('; ')}`,
+    );
+  });
+});
+
+test('assertOperatingRulesSingleSource passes on current state', () => {
+  assert.deepStrictEqual(collectFailures(crossDocContracts.assertOperatingRulesSingleSource), []);
+});
+
+test('assertOperatingRulesSingleSource catches AGENTS.md restating a rule', () => {
+  const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');
+  withFileMutation(agentsPath, (original) => `${original}\n1. **Confirm destructive operations.** Restated.\n`, () => {
+    const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);
+    assert.ok(
+      failures.some((f) => f.includes('AGENTS.md') && f.includes('restates an operating rule')),
+      `expected a restated-rule failure, got: ${failures.join('; ')}`,
+    );
+  });
+});
+
+test('assertOperatingRulesSingleSource catches AGENTS.md losing the pointer', () => {
+  const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');
+  withFileMutation(agentsPath, (original) => original.replaceAll('references/concepts/operating-rules.md', 'nowhere.md'), () => {
+    const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);
+    assert.ok(
+      failures.some((f) => f.includes('AGENTS.md must point at')),
+      `expected a missing-pointer failure, got: ${failures.join('; ')}`,
+    );
+  });
+});
+
+test('assertHowAppsWork catches a skill that does not reference operating-rules.md', () => {
+  const skillPath = path.join(PLUGIN_ROOT, 'skills', 'develop-app', 'SKILL.md');
+  withFileMutation(skillPath, (original) => original.replace('../../references/concepts/operating-rules.md', 'nowhere.md'), () => {
+    const failures = collectFailures(references.assertHowAppsWork);
+    assert.ok(
+      failures.some((f) => f.includes('develop-app/SKILL.md') && f.includes('operating-rules.md')),
+      `expected an operating-rules reference failure, got: ${failures.join('; ')}`,
+    );
+  });
+});
+
+test('assertOperatingRulesSingleSource catches prose copied from the rules file', () => {
+  const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');
+  const copiedSentence = 'Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.';
+  withFileMutation(agentsPath, (original) => `${original}\n${copiedSentence}\n`, () => {
+    const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);
+    assert.ok(
+      failures.some((f) => f.includes('AGENTS.md') && f.includes('copies a sentence')),
+      `expected a copied-prose failure, got: ${failures.join('; ')}`,
+    );
+  });
+});