Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

63.5 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import {
  GHOST_MANUAL_DESCRIPTION_MAX_CHARS,
  GHOST_MANUAL_ENTRY_FILE,
  GHOST_MANUAL_MAX_ITEMS,
  GHOST_MANUAL_MD_MAX_BYTES,
  GHOST_MANIFEST_SUMMARY_MAX_CHARS,
  GHOST_MANIFEST_SCHEMA_VERSION,
  GHOST_MAIN_VIEW_ICONS,
  GHOST_OAUTH_SCOPES_MAX,
  LEGACY_GHOST_SLOTS,
  compareCindyVersions,
  ghostManifestUsesOidcToken,
  isSafeGhostRelativePath,
  isValidCindyVersion,
  isValidGhostId,
  isVersionlessCindyVersion,
  supportsCindyVersion,
  validateGhostManifest,
} from '../manifest.js';

const validManifest = {
  schemaVersion: 2,
  id: 'acme-helper',
  name: 'Acme Helper',
  version: '1.0.0',
  kind: 'chip',
  entry: 'index.js',
  slots: ['tool'],
  tools: [{ name: 'help', description: 'Help with Acme tasks' }],
} as const;

describe('Ghost manifest contract', () => {
  it.each([2, 3])('preserves the optional Host task card visibility flag in schema v%s', (schemaVersion) => {
    const base = {
      ...validManifest,
      schemaVersion,
      ...(schemaVersion === 3 ? { minCindyVersion: '0.1.0' } : {}),
      slots: schemaVersion === 2 ? ['agent'] : undefined,
      tools: undefined,
      agent: { tasks: true },
    };
    for (const showTaskPreferences of [undefined, true, false]) {
      const result = validateGhostManifest({ ...base, showTaskPreferences });
      expect(result.ok).toBe(true);
      if (!result.ok) continue;
      expect(result.manifest.showTaskPreferences).toBe(showTaskPreferences);
      expect(Object.hasOwn(result.manifest, 'showTaskPreferences')).toBe(showTaskPreferences !== undefined);
      expect(result.manifest.agent?.tasks).toBe(true);
      expect(validateGhostManifest(result.manifest)).toEqual(result);
    }
    for (const showTaskPreferences of [null, 0, 1, 'false', {}, []]) {
      expect(validateGhostManifest({ ...base, showTaskPreferences })).toMatchObject({
        ok: false,
        reason: 'showTaskPreferences 必须是布尔值',
      });
    }
  });

  it('keeps main-view in the v2 compatibility contract', () => {
    expect(LEGACY_GHOST_SLOTS).toContain('main-view');
    expect(GHOST_MAIN_VIEW_ICONS).toEqual([
      'puzzle',
      'globe',
      'code',
      'folder',
      'database',
      'chart-column',
      'image',
      'message-circle',
      'calendar-days',
    ]);
  });

  it('uses Manifest v3 for new plugins and keeps v2 as input compatibility', () => {
    expect(GHOST_MANIFEST_SCHEMA_VERSION).toBe(3);
    const result = validateGhostManifest({
      schemaVersion: GHOST_MANIFEST_SCHEMA_VERSION,
      minCindyVersion: '0.1.61',
      id: 'direct-helper',
      name: 'Direct Helper',
      version: '1.0.0',
      entry: 'index.js',
      tools: [{ name: 'help', description: 'Help with direct capabilities' }],
      card: {},
      agent: {},
      notify: true,
      futureCapability: { mode: 'example' },
    });
    expect(result.ok).toBe(true);
    if (!result.ok) return;
    expect(result.manifest).not.toHaveProperty('slots');
    expect(result.manifest.card).toEqual({});
    expect(result.manifest.agent).toEqual({});
    expect(result.manifest.notify).toBe(true);
    expect(result.manifest.futureCapability).toEqual({ mode: 'example' });

    expect(validateGhostManifest({ ...validManifest, schemaVersion: 3 }).ok).toBe(false);
    expect(
      validateGhostManifest({
        ...validManifest,
        schemaVersion: 3,
        minCindyVersion: '0.1.61',
      }).ok,
    ).toBe(false);
    expect(
      validateGhostManifest({
        ...validManifest,
        schemaVersion: 3,
        minCindyVersion: '0.1.61',
        slots: undefined,
        notify: false,
      }).ok,
    ).toBe(false);
    expect(
      validateGhostManifest({
        schemaVersion: 3,
        minCindyVersion: '0.1.60',
        id: 'older-compatible-v3',
        name: 'Older Compatible v3',
        version: '1.0.0',
        entry: 'index.js',
      }).ok,
    ).toBe(true);
  });

  it('validates and normalizes setup at the shared protocol boundary', () => {
    const manifest = {
      schemaVersion: 3,
      minCindyVersion: '0.1.61',
      id: 'setup-helper',
      name: 'Setup Helper',
      version: '1.0.0',
      entry: 'index.js',
      settingsHtml: 'settings.html',
      network: {
        hosts: ['api.example.com'],
        secrets: [
          {
            key: 'api_key',
            label: 'API key',
            inject: { header: 'Authorization', format: 'Bearer {value}' },
          },
        ],
      },
      setup: {
        requires: [
          {
            anyOf: ['secret:api_key', { kv: 'repository', label: 'Repository' }],
          },
        ],
      },
    } as const;

    const result = validateGhostManifest(manifest);
    expect(result.ok).toBe(true);
    if (!result.ok) return;
    expect(result.manifest.setup).toEqual({
      requires: [
        {
          anyOf: [
            { kind: 'secret', key: 'api_key' },
            { kind: 'kv', key: 'repository', label: 'Repository' },
          ],
        },
      ],
    });
    expect(validateGhostManifest({ ...manifest, setup: { requires: 'bad' } }).ok).toBe(false);
    expect(
      validateGhostManifest({
        ...manifest,
        setup: { requires: [{ anyOf: ['secret:missing'] }] },
      }).ok,
    ).toBe(false);
  });

  it('accepts empty and zero-power v2 slots and drops the latter', () => {
    expect(validateGhostManifest({ ...validManifest, slots: [], tools: undefined })).toMatchObject({
      ok: true,
      manifest: { slots: [] },
    });
    expect(
      validateGhostManifest({ ...validManifest, slots: ['tool', 'network'], tools: undefined }),
    ).toMatchObject({ ok: true, manifest: { slots: [] } });
  });

  it('exports the manual authoring limits', () => {
    expect(GHOST_MANUAL_MAX_ITEMS).toBe(8);
    expect(GHOST_MANUAL_ENTRY_FILE).toBe('MANUAL.md');
    expect(GHOST_MANUAL_MD_MAX_BYTES).toBe(64 * 1024);
    expect(GHOST_MANUAL_DESCRIPTION_MAX_CHARS).toBe(300);
  });

  it('accepts and normalizes a valid schema v2 manifest', () => {
    const result = validateGhostManifest(validManifest);
    expect(result).toEqual({ ok: true, manifest: validManifest });
  });

  it('keeps minCindyVersion optional for old plugins and validates declared versions', () => {
    expect(validateGhostManifest(validManifest)).toEqual({
      ok: true,
      manifest: validManifest,
    });
    expect(validateGhostManifest({ ...validManifest, minCindyVersion: '1.2.3' })).toEqual({
      ok: true,
      manifest: { ...validManifest, minCindyVersion: '1.2.3' },
    });
    for (const invalid of ['v1.2.3', '1.2', '01.2.3', '1.2.3-01', '']) {
      expect(validateGhostManifest({ ...validManifest, minCindyVersion: invalid }).ok).toBe(false);
    }
  });

  it('compares Cindy versions with SemVer precedence', () => {
    expect(compareCindyVersions('1.2.3', '1.2.3')).toBe(0);
    expect(compareCindyVersions('1.3.0', '1.2.9')).toBe(1);
    expect(compareCindyVersions('1.2.3-beta.2', '1.2.3-beta.10')).toBe(-1);
    expect(compareCindyVersions('1.2.3-999999999999999999', '1.2.3-1000000000000000000')).toBe(-1);
    expect(compareCindyVersions('1.2.3', '1.2.3-rc.1')).toBe(1);
    expect(compareCindyVersions('not-a-version', '1.2.3')).toBeNull();
    expect(isValidCindyVersion('1.2.3')).toBe(true);
    expect(isValidCindyVersion('v1.2.3')).toBe(false);
    expect(isVersionlessCindyVersion('0.0.0-dev.1')).toBe(true);
    expect(supportsCindyVersion('0.1.0', undefined)).toBe(true);
    expect(supportsCindyVersion('0.0.0-dev.1', '99.0.0')).toBe(true);
    expect(supportsCindyVersion('0.0.0-not valid', '1.0.0')).toBe(false);
    expect(supportsCindyVersion('0.0.0-dev.1', 'not-a-version')).toBe(false);
    expect(supportsCindyVersion('1.2.3', '1.2.3')).toBe(true);
    expect(supportsCindyVersion('1.2.2', '1.2.3')).toBe(false);
    expect(supportsCindyVersion('not-a-version', '1.2.3')).toBe(false);
  });

  it('rejects invalid ids and schema versions', () => {
    expect(isValidGhostId('../escape')).toBe(false);
    expect(validateGhostManifest({ ...validManifest, schemaVersion: 1 }).ok).toBe(false);
  });

  it('shares the 300-character limit across description and whenToUse', () => {
    expect(GHOST_MANIFEST_SUMMARY_MAX_CHARS).toBe(300);
    for (const field of ['description', 'whenToUse'] as const) {
      expect(
        validateGhostManifest({
          ...validManifest,
          [field]: 'x'.repeat(GHOST_MANIFEST_SUMMARY_MAX_CHARS),
        }).ok,
      ).toBe(true);
      expect(
        validateGhostManifest({
          ...validManifest,
          [field]: 'x'.repeat(GHOST_MANIFEST_SUMMARY_MAX_CHARS + 1),
        }),
      ).toEqual({
        ok: false,
        reason: `${field} 必须是 1–${GHOST_MANIFEST_SUMMARY_MAX_CHARS} 字符的非空字符串`,
      });
    }
  });

  it('accepts an oidc-token secret without a settings page and normalizes its exact host', () => {
    const result = validateGhostManifest({
      ...validManifest,
      tools: undefined,
      slots: ['network'],
      network: {
        hosts: ['api.example.com'],
        secrets: [
          {
            key: 'cindy_identity',
            label: 'Cindy organization identity',
            source: 'oidc-token',
            inject: {
              header: 'Authorization',
              format: 'Bearer {value}',
              hosts: ['API.EXAMPLE.COM'],
            },
          },
        ],
      },
    });

    expect(result).toEqual({
      ok: true,
      manifest: expect.objectContaining({
        network: {
          hosts: ['api.example.com'],
          secrets: [
            {
              key: 'cindy_identity',
              label: 'Cindy organization identity',
              source: 'oidc-token',
              inject: {
                header: 'Authorization',
                format: 'Bearer {value}',
                hosts: ['api.example.com'],
              },
            },
          ],
        },
      }),
    });
    expect(result.ok && ghostManifestUsesOidcToken(result.manifest)).toBe(true);
    const baseline = validateGhostManifest(validManifest);
    expect(baseline.ok && ghostManifestUsesOidcToken(baseline.manifest)).toBe(false);
  });

  it('rejects unsafe oidc-token declarations', () => {
    const base = {
      ...validManifest,
      tools: undefined,
      slots: ['network'],
      network: {
        hosts: ['api.example.com'],
        secrets: [
          {
            key: 'cindy_identity',
            label: 'Cindy organization identity',
            source: 'oidc-token',
            inject: {
              header: 'Authorization',
              format: 'Bearer {value}',
              hosts: ['api.example.com'],
            },
          },
        ],
      },
    };
    const secret = (patch: Record<string, unknown> = {}, hosts: string[] = base.network.hosts) => ({
      ...base,
      network: {
        ...base.network,
        hosts,
        secrets: [{ ...base.network.secrets[0], ...patch }],
      },
    });

    expect(
      validateGhostManifest(
        secret({
          inject: {
            header: 'X-Identity',
            format: 'Bearer {value}',
            hosts: ['api.example.com'],
          },
        }),
      ),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('Authorization: Bearer'),
    });
    expect(
      validateGhostManifest(
        secret({
          inject: { header: 'Authorization', format: 'Basic {value}' },
        }),
      ),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('Authorization: Bearer'),
    });
    expect(
      validateGhostManifest(
        secret(
          {
            inject: {
              header: 'Authorization',
              format: 'Bearer {value}',
              hosts: ['*.example.com'],
            },
          },
          ['*.example.com'],
        ),
      ),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不允许通配'),
    });
    expect(
      validateGhostManifest(
        secret({
          inject: { header: 'Authorization', format: 'Bearer {value}' },
        }),
      ),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('显式声明非空 inject.hosts'),
    });
    expect(validateGhostManifest(secret({ url: 'https://api.example.com/keys' }))).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不允许声明 url'),
    });
    expect(validateGhostManifest(secret({ exchange: {} }))).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不允许声明 exchange'),
    });
    expect(validateGhostManifest(secret({ oauth: {} }))).toMatchObject({
      ok: false,
      reason: expect.stringContaining('oauth 仅允许在 source: oauth'),
    });
    expect(
      validateGhostManifest(
        secret({
          input: 'ghost',
        }),
      ),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不允许标注 input'),
    });
  });

  it('accepts a gh-cli secret with a settings-managed fallback token', () => {
    const result = validateGhostManifest({
      ...validManifest,
      tools: undefined,
      slots: ['network'],
      settingsHtml: 'settings.html',
      network: {
        hosts: ['api.github.com', 'objects.githubusercontent.com'],
        secrets: [
          {
            key: 'github_pat',
            label: 'GitHub login',
            source: 'gh-cli',
            hint: 'The host prefers GitHub CLI and falls back to this token',
            url: 'https://github.com/settings/tokens',
            inject: {
              header: 'Authorization',
              format: 'Bearer {value}',
              hosts: ['API.GITHUB.COM'],
            },
          },
        ],
      },
    });

    expect(result).toEqual({
      ok: true,
      manifest: expect.objectContaining({
        network: {
          hosts: ['api.github.com', 'objects.githubusercontent.com'],
          secrets: [
            {
              key: 'github_pat',
              label: 'GitHub login',
              source: 'gh-cli',
              hint: 'The host prefers GitHub CLI and falls back to this token',
              url: 'https://github.com/settings/tokens',
              inject: {
                header: 'Authorization',
                format: 'Bearer {value}',
                hosts: ['api.github.com'],
              },
            },
          ],
        },
      }),
    });
  });

  it('rejects unsafe gh-cli declarations', () => {
    const base = {
      ...validManifest,
      tools: undefined,
      slots: ['network'],
      settingsHtml: 'settings.html',
      network: {
        hosts: ['api.github.com', 'uploads.github.com'],
        secrets: [
          {
            key: 'github_pat',
            label: 'GitHub login',
            source: 'gh-cli',
            inject: {
              header: 'Authorization',
              format: 'Bearer {value}',
              hosts: ['api.github.com'],
            },
          },
        ],
      },
    };
    const secret = (patch: Record<string, unknown> = {}) => ({
      ...base,
      network: {
        ...base.network,
        secrets: [{ ...base.network.secrets[0], ...patch }],
      },
    });

    expect(validateGhostManifest({ ...base, settingsHtml: undefined })).toMatchObject({
      ok: false,
      reason: expect.stringContaining('settingsHtml'),
    });
    expect(
      validateGhostManifest(
        secret({
          inject: {
            header: 'X-GitHub-Token',
            format: 'Bearer {value}',
            hosts: ['api.github.com'],
          },
        }),
      ),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('Authorization: Bearer'),
    });
    expect(
      validateGhostManifest(
        secret({
          inject: {
            header: 'Authorization',
            format: 'Bearer {value}',
            hosts: ['api.github.com', 'uploads.github.com'],
          },
        }),
      ),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('只能是 api.github.com'),
    });
    expect(
      validateGhostManifest(
        secret({
          inject: { header: 'Authorization', format: 'Bearer {value}' },
        }),
      ),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('只能是 api.github.com'),
    });
    expect(validateGhostManifest(secret({ exchange: {} }))).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不允许声明 exchange'),
    });
    expect(validateGhostManifest(secret({ oauth: {} }))).toMatchObject({
      ok: false,
      reason: expect.stringContaining('oauth 仅允许在 source: oauth'),
    });
    expect(validateGhostManifest(secret({ input: 'ghost' }))).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不允许标注 input'),
    });
  });

  it('accepts up to 256 OAuth scopes and rejects more', () => {
    const withScopes = (count: number) =>
      validateGhostManifest({
        ...validManifest,
        tools: undefined,
        slots: ['network'],
        settingsHtml: 'settings.html',
        network: {
          hosts: ['accounts.example.com'],
          secrets: [
            {
              key: 'account',
              label: 'Example account',
              source: 'oauth',
              inject: { header: 'Authorization', format: 'Bearer {value}' },
              oauth: {
                authorizeUrl: 'https://accounts.example.com/authorize',
                tokenUrl: 'https://accounts.example.com/token',
                scopes: Array.from({ length: count }, (_, index) => `scope:${index}`),
              },
            },
          ],
        },
      });

    expect(GHOST_OAUTH_SCOPES_MAX).toBe(256);
    const accepted = withScopes(GHOST_OAUTH_SCOPES_MAX);
    expect(accepted.ok).toBe(true);
    expect(accepted.ok && accepted.manifest.network?.secrets?.[0]?.oauth?.scopes).toEqual(
      Array.from({ length: GHOST_OAUTH_SCOPES_MAX }, (_, index) => `scope:${index}`),
    );
    expect(withScopes(GHOST_OAUTH_SCOPES_MAX + 1)).toEqual({
      ok: false,
      reason: 'network.secrets[].oauth.scopes 必须是 ≤256 条的数组',
    });
  });

  it('preserves Desktop-supported OAuth client alternatives and identity avatar path', () => {
    const result = validateGhostManifest({
      ...validManifest,
      tools: undefined,
      slots: ['network'],
      settingsHtml: 'settings.html',
      network: {
        hosts: ['accounts.example.com', 'api.example.com'],
        secrets: [
          {
            key: 'account',
            label: 'Example account',
            source: 'oauth',
            inject: { header: 'Authorization', format: 'Bearer {value}' },
            oauth: {
              authorizeUrl: 'https://accounts.example.com/authorize',
              tokenUrl: 'https://accounts.example.com/token',
              clientId: 'cn-client',
              clientIdAlternatives: ['global-client'],
              tokenBroker: 'example',
              identity: {
                url: 'https://api.example.com/me',
                labelPath: 'data.user_id',
                avatarPath: 'data.avatar_thumb',
              },
            },
          },
        ],
      },
    });

    expect(result.ok).toBe(true);
    expect(result.ok && result.manifest.network?.secrets?.[0]?.oauth).toMatchObject({
      clientIdAlternatives: ['global-client'],
      identity: { avatarPath: 'data.avatar_thumb' },
    });
  });

  it('accepts and normalizes Plugin locale resource declarations', () => {
    const locales = {
      en: 'locales/en.json',
      'zh-CN': 'locales/zh-CN.json',
      ja: 'locales/ja.json',
      ko: 'locales/ko.json',
    };
    const result = validateGhostManifest({ ...validManifest, locales });

    expect(result).toEqual({
      ok: true,
      manifest: { ...validManifest, locales },
    });
  });

  it('rejects locale declarations without English fallback or with unsafe conflicts', () => {
    expect(
      validateGhostManifest({
        ...validManifest,
        locales: { ja: 'locales/ja.json' },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('必须提供 en'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        locales: { en: 'index.js' },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('以 .json 结尾'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        locales: { en: 'ghost.json' },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与插件其他声明文件'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        locales: {
          en: 'locales/en.json',
          ja: 'locales/EN.json',
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('重复路径'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        locales: {
          en: 'a.json',
          ja: 'a.json/child.json',
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('祖先路径冲突'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        locales: {
          en: 'locales/en.json',
          fr: 'locales/fr.json',
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不支持的语言'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        slots: ['tool', 'skill'],
        locales: { en: 'skills/helper.json' },
        skill: {
          items: [
            {
              dir: 'skills/helper.json',
              name: 'helper',
              description: 'Help with example tasks.',
            },
          ],
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与插件其他声明文件'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        slots: ['tool', 'skill'],
        locales: { en: 'skills/helper.json' },
        skill: {
          items: [
            {
              dir: 'skills/helper.json/subskill',
              name: 'helper',
              description: 'Help with example tasks.',
            },
          ],
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与插件其他声明文件'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        slots: ['tool', 'skill'],
        locales: { en: 'skills/helper/locales/en.json' },
        skill: {
          items: [
            {
              dir: 'skills/helper',
              name: 'helper',
              description: 'Help with example tasks.',
            },
          ],
        },
      }),
    ).toMatchObject({
      ok: true,
      manifest: expect.objectContaining({
        locales: { en: 'skills/helper/locales/en.json' },
      }),
    });
  });

  it('rejects locale and manual paths with either nesting direction', () => {
    const validatePaths = (localePath: string, manualDir: string) =>
      validateGhostManifest({
        ...validManifest,
        locales: { en: localePath },
        manual: {
          items: [{ dir: manualDir, name: 'guide', description: 'Manual guide.' }],
        },
      });

    expect(validatePaths('content/en.json', 'content/en.json/manual')).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与插件其他声明文件'),
    });
    expect(validatePaths('manual/docs/en.json', 'manual/docs')).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与插件其他声明文件'),
    });
    expect(validatePaths('manual/en.json', 'manual/en.json')).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与插件其他声明文件'),
    });
    expect(validatePaths('locales/en.json', 'manual/docs')).toMatchObject({
      ok: true,
      manifest: expect.objectContaining({
        locales: { en: 'locales/en.json' },
        manual: {
          items: [{ dir: 'manual/docs', name: 'guide', description: 'Manual guide.' }],
        },
      }),
    });
  });

  it('rejects Windows reserved device names in ids and relative paths', () => {
    expect(isValidGhostId('con')).toBe(false);
    expect(isValidGhostId('com1')).toBe(false);
    expect(isSafeGhostRelativePath('CON.js')).toBe(false);
    expect(isSafeGhostRelativePath('assets/AUX.html')).toBe(false);
    expect(isSafeGhostRelativePath('assets/console.html')).toBe(true);
    expect(validateGhostManifest({ ...validManifest, entry: 'assets/LPT9.js' }).ok).toBe(false);
  });

  it('rejects credential exchange URLs on non-default HTTPS ports', () => {
    const result = validateGhostManifest({
      ...validManifest,
      settingsHtml: 'settings.html',
      slots: ['network'],
      tools: undefined,
      network: {
        hosts: ['api.example.com'],
        secrets: [
          {
            key: 'api_key',
            label: 'API key',
            inject: { header: 'Authorization', format: 'Bearer {value}' },
            exchange: {
              url: 'https://api.example.com:8443/token',
              bodyFormat: '{"key":"{value}"}',
              tokenPath: 'token',
            },
          },
        ],
      },
    });

    expect(result).toMatchObject({ ok: false });
    if (!result.ok) expect(result.reason).toContain('仅支持 https 默认端口');
  });

  it('normalizes a representative full capability manifest', () => {
    const result = validateGhostManifest({
      schemaVersion: GHOST_MANIFEST_SCHEMA_VERSION,
      minCindyVersion: '0.1.61',
      id: 'full-helper',
      name: 'Full Helper',
      version: '2.0.0',
      author: 'Cindy',
      description: 'Exercises the shared manifest contract.',
      whenToUse: 'Use for representative protocol validation.',
      icon: 'assets/icon.png',
      entry: 'src/main.js',
      launch: 'resident',
      settingsHtml: 'settings.html',
      settingsHeight: 320,
      card: {},
      notify: true,
      fs: true,
      library: true,
      tools: [
        {
          name: 'run_helper',
          description: 'Run the helper.',
          parameters: {
            type: 'object',
            properties: {
              input: { type: 'string' },
              mediaUrl: { type: 'string' },
              references: { type: 'array', items: { type: 'string' } },
            },
            required: ['input'],
          },
        },
      ],
      cindy: { image: ['generate'], video: ['edit'] },
      subscribe: { topics: ['turn'], hooks: ['will-user-message'] },
      network: {
        hosts: ['api.example.com'],
        secrets: [
          {
            key: 'api_key',
            label: 'API key',
            inject: { header: 'Authorization', format: 'Bearer {value}' },
          },
        ],
      },
      command: 'full-helper',
      keywords: ['full helper'],
      panel: {
        title: 'Full Helper',
        html: 'panel.html',
        position: 'right',
        minWidth: 320,
        defaultFraction: 0.2,
      },
      unknownField: 'ignored',
    });

    expect(result.ok).toBe(true);
    if (!result.ok) return;
    expect(result.manifest.kind).toBe('chip');
    expect(result.manifest).not.toHaveProperty('slots');
    expect(result.manifest.card).toEqual({});
    expect(result.manifest.notify).toBe(true);
    expect(result.manifest.fs).toBe(true);
    expect(result.manifest.library).toBe(true);
    expect(result.manifest.unknownField).toBe('ignored');
  });

  it('accepts Desktop-supported badge and confirm slots while requiring a badge panel', () => {
    const manifest = {
      ...validManifest,
      slots: ['tool', 'panel', 'badge', 'confirm'],
      panel: { html: 'panel.html' },
    } as const;

    expect(validateGhostManifest(manifest)).toEqual({ ok: true, manifest });
    expect(
      validateGhostManifest({
        ...validManifest,
        slots: ['tool', 'badge'],
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('panel'),
    });
  });

  it('accepts the taptap-maker style manifest with node/session-context/pick/preview slots', () => {
    const result = validateGhostManifest({
      schemaVersion: GHOST_MANIFEST_SCHEMA_VERSION,
      minCindyVersion: '0.1.61',
      id: 'taptap-maker',
      name: 'TapTap Maker',
      version: '2.0.0',
      author: 'Cindy',
      icon: 'assets/icon.png',
      entry: 'main.js',
      settingsHtml: 'settings.html',
      settingsHeight: 760,
      card: { externalLinks: true },
      sessionContext: true,
      pick: true,
      workspace: true,
      node: {
        entry: 'node/maker-mcp.cjs',
        entries: ['node/account.cjs', 'node/maker-child.cjs'],
        protocol: 'mcp-stdio',
        lifecycle: 'on-demand',
        idleTimeoutSeconds: 600,
        childSpawn: true,
      },
      preview: { hosts: ['maker.taptap.cn'] },
      command: 'taptap-maker',
      tools: [{ name: 'maker_status', description: 'Check Maker status' }],
    });

    expect(result.ok).toBe(true);
    if (!result.ok) return;
    expect(result.manifest).not.toHaveProperty('slots');
    expect(result.manifest.sessionContext).toBe(true);
    expect(result.manifest.pick).toBe(true);
    expect(result.manifest.workspace).toBe(true);
    expect(result.manifest.node).toEqual({
      entry: 'node/maker-mcp.cjs',
      protocol: 'mcp-stdio',
      lifecycle: 'on-demand',
      idleTimeoutSeconds: 600,
      entries: ['node/account.cjs', 'node/maker-child.cjs'],
      childSpawn: true,
    });
    expect(result.manifest.preview).toEqual({ hosts: ['maker.taptap.cn'] });
    expect(result.manifest.card).toEqual({ externalLinks: true });
  });

  it('keeps minCindyVersion optional for Host-owned slots', () => {
    const manifest = {
      ...validManifest,
      id: 'simulator-workflow',
      name: 'Simulator Workflow',
      slots: ['ios-simulator'],
      tools: undefined,
    } as const;

    const result = validateGhostManifest(JSON.parse(JSON.stringify(manifest)));

    expect(result).toEqual({ ok: true, manifest });
  });

  it('preserves well-formed unknown slots and rejects unsafe slot names', () => {
    const manifest = {
      ...validManifest,
      slots: ['future-host-capability'],
      tools: undefined,
    };

    expect(validateGhostManifest(manifest)).toEqual({ ok: true, manifest });
    for (const slot of ['FutureCapability', 'future capability', 'future/capability', '']) {
      expect(validateGhostManifest({ ...manifest, slots: [slot] })).toMatchObject({
        ok: false,
        reason: expect.stringContaining('格式非法'),
      });
    }
  });

  // 跟对话的任务页:v3 直接声明保留;v2 必须与 task-view 槽成对;入口路径与 mainView 同一套安全约束。
  it('accepts direct v3 taskView, pairs v2 task-view, and rejects unsafe or missing entries', () => {
    const direct = {
      schemaVersion: 3,
      minCindyVersion: '1.2.3',
      id: 'direct-task-view',
      name: 'Direct Task View',
      version: '1.0.0',
      entry: 'index.js',
      taskView: { title: 'Simulator', html: 'ui/task.html' },
    } as const;
    expect(validateGhostManifest(direct)).toMatchObject({ ok: true, manifest: { taskView: direct.taskView } });
    expect(validateGhostManifest({ ...direct, taskView: { html: '../task.html' } }).ok).toBe(false);
    expect(validateGhostManifest({ ...direct, taskView: { title: 'Simulator' } }).ok).toBe(false);
    const v2 = { ...validManifest, minCindyVersion: '1.2.3', slots: ['task-view'], tools: undefined, taskView: { html: 'task.html' } };
    expect(validateGhostManifest(JSON.parse(JSON.stringify(v2)))).toMatchObject({ ok: true });
    expect(validateGhostManifest({ ...v2, slots: [] }).ok).toBe(false);
    expect(validateGhostManifest({ ...v2, taskView: undefined }).ok).toBe(false);
  });

  it('accepts direct v3 mainView and round-trips v2 main-view compatibility', () => {
    const direct = {
      schemaVersion: 3,
      minCindyVersion: '0.1.61',
      id: 'direct-main-view',
      name: 'Direct Main View',
      version: '1.0.0',
      entry: 'index.js',
      mainView: {
        title: 'Workspace',
        icon: 'globe',
        html: 'ui/main-view.html',
      },
    } as const;
    const directResult = validateGhostManifest(direct);
    expect(directResult).toMatchObject({ ok: true, manifest: { mainView: direct.mainView } });
    if (directResult.ok) expect(directResult.manifest).not.toHaveProperty('slots');

    const manifest = {
      ...validManifest,
      minCindyVersion: '1.2.3',
      slots: ['main-view'],
      tools: undefined,
      mainView: {
        title: 'Workspace',
        icon: 'globe',
        html: 'ui/main-view.html',
      },
    } as const;

    expect(validateGhostManifest(JSON.parse(JSON.stringify(manifest)))).toEqual({
      ok: true,
      manifest,
    });

    const withoutMin = { ...manifest } as Record<string, unknown>;
    delete withoutMin.minCindyVersion;
    expect(validateGhostManifest(withoutMin)).toEqual({ ok: true, manifest: withoutMin });
  });

  it('keeps v2 main-view paired, rejects unsafe paths and preserves extension fields', () => {
    const legacyBase = {
      ...validManifest,
      minCindyVersion: '1.2.3',
      slots: ['main-view'],
      tools: undefined,
    };
    expect(validateGhostManifest(legacyBase)).toMatchObject({
      ok: false,
      reason: expect.stringContaining('mainView'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        minCindyVersion: '1.2.3',
        mainView: { html: 'main-view.html' },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('main-view'),
    });
    const base = {
      schemaVersion: 3,
      minCindyVersion: '0.1.61',
      id: 'invalid-main-view',
      name: 'Invalid Main View',
      version: '1.0.0',
      entry: 'index.js',
    } as const;
    expect(validateGhostManifest({ ...base, mainView: { html: '../escape.html' } }).ok).toBe(false);
    expect(
      validateGhostManifest({
        ...base,
        mainView: { html: 'main-view.html', icon: 'plugin' },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('mainView.icon'),
    });
    expect(
      validateGhostManifest({
        ...base,
        mainView: { html: 'main-view.html', icon: 'globe-2' },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('puzzle / globe / code'),
    });
    expect(
      validateGhostManifest({
        ...base,
        mainView: { html: 'main-view.html', position: 'left' },
      }),
    ).toMatchObject({
      ok: true,
      manifest: { mainView: { position: 'left' } },
    });
  });

  it('drops an empty legacy node slot and enforces entry discipline', () => {
    const base = {
      ...validManifest,
      slots: ['tool', 'node'],
    };
    expect(validateGhostManifest(base)).toMatchObject({
      ok: true,
      manifest: { slots: ['tool'] },
    });
    const withNode = (node: Record<string, unknown>) => validateGhostManifest({ ...base, node });
    expect(withNode({ entry: 'node/a.cjs', protocol: 'mcp-stdio', command: 'sh' })).toMatchObject({
      ok: true,
      manifest: { node: { command: 'sh', entry: 'node/a.cjs', protocol: 'mcp-stdio' } },
    });
    expect(withNode({ entry: '../a.cjs', protocol: 'mcp-stdio' }).ok).toBe(false);
    expect(withNode({ entry: 'index.js', protocol: 'mcp-stdio' })).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不能与浏览器沙箱 entry'),
    });
    expect(withNode({ entry: 'node/a.cjs', protocol: 'bash' }).ok).toBe(false);
    expect(
      withNode({
        entry: 'node/a.cjs',
        protocol: 'mcp-stdio',
        entries: ['node/a.cjs'],
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不能重复主入口'),
    });
    // 大小写不敏感文件系统上的同名变体必须按同一个文件拒绝。
    expect(withNode({ entry: 'Index.js', protocol: 'mcp-stdio' })).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不能与浏览器沙箱 entry'),
    });
    expect(
      withNode({
        entry: 'node/a.cjs',
        protocol: 'mcp-stdio',
        entries: ['node/A.cjs'],
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('不能重复主入口'),
    });
    expect(
      withNode({
        entry: 'node/a.cjs',
        protocol: 'mcp-stdio',
        entries: ['node/b.cjs', 'node/B.cjs'],
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('重复入口') });
    expect(
      withNode({
        entry: 'node/a.cjs',
        protocol: 'mcp-stdio',
        entries: ['node/b.cjs', 'node/b.cjs'],
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('重复入口') });
    expect(
      withNode({
        entry: 'node/a.cjs',
        protocol: 'mcp-stdio',
        childSpawn: 'yes',
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('childSpawn 必须是布尔值'),
    });
    expect(
      withNode({
        entry: 'node/a.cjs',
        protocol: 'mcp-stdio',
        lifecycle: 'resident',
        idleTimeoutSeconds: 60,
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('resident 时不能再声明'),
    });
  });

  it('accepts and normalizes method-scoped Node secret bindings', () => {
    const result = validateGhostManifest({
      ...validManifest,
      settingsHtml: 'settings.html',
      slots: ['tool', 'node'],
      node: {
        entry: 'node/worker.cjs',
        entries: ['node/secondary.cjs'],
        protocol: 'json-rpc-stdio',
        secretBindings: [
          {
            key: 'mail_code',
            label: 'Mail authorization code',
            methods: ['account/connect', 'mail/action'],
            entry: 'node/secondary.cjs',
            hint: 'Use the provider-generated authorization code',
            url: 'https://mail.example.com/settings',
          },
        ],
      },
    });

    expect(result.ok).toBe(true);
    if (!result.ok) return;
    expect(result.manifest.node?.secretBindings).toEqual([
      {
        key: 'mail_code',
        label: 'Mail authorization code',
        methods: ['account/connect', 'mail/action'],
        entry: 'node/secondary.cjs',
        hint: 'Use the provider-generated authorization code',
        url: 'https://mail.example.com/settings',
      },
    ]);
  });

  it('preserves OAuth references for plugin-local runtime resolution', () => {
    const manifest = {
      ...validManifest, settingsHtml: 'settings.html', slots: ['tool', 'network', 'node'],
      network: { hosts: ['example.test'], secrets: [{
        key: 'mail_account', label: 'Mail', source: 'oauth',
        inject: { header: 'Authorization', format: 'Bearer {value}' },
        oauth: { authorizeUrl: 'https://example.test/auth', tokenUrl: 'https://example.test/token', scopes: ['mail'] },
      }] },
      node: { entry: 'node/worker.cjs', protocol: 'json-rpc-stdio', secretBindings: [{
        key: 'access_token', label: 'Mail', methods: ['run'], oauthSecret: 'mail_account',
      }] },
    };
    const result = validateGhostManifest(manifest);
    expect(result.ok).toBe(true);
    if (result.ok) expect(result.manifest.node?.secretBindings?.[0]?.oauthSecret).toBe('mail_account');
    const missing = structuredClone(manifest);
    missing.node.secretBindings[0].oauthSecret = 'other_plugin';
    expect(validateGhostManifest(missing).ok).toBe(true);
    const staticSource = structuredClone(manifest);
    staticSource.network.secrets[0].source = 'user';
    expect(validateGhostManifest(staticSource).ok).toBe(false);
  });

  it('rejects unsafe Node secret bindings and shared credential-key collisions', () => {
    const base = {
      ...validManifest,
      settingsHtml: 'settings.html',
      slots: ['tool', 'node'],
      node: {
        entry: 'node/worker.cjs',
        entries: ['node/secondary.cjs'],
        protocol: 'json-rpc-stdio',
      },
    };
    const binding = {
      key: 'mail_code',
      label: 'Mail authorization code',
      methods: ['mail/action'],
    };

    expect(
      validateGhostManifest({
        ...base,
        settingsHtml: undefined,
        node: { ...base.node, secretBindings: [binding] },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('需要 settingsHtml'),
    });
    expect(
      validateGhostManifest({
        ...base,
        node: {
          ...base.node,
          secretBindings: [{ ...binding, methods: ['bad method'] }],
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('安全方法名'),
    });
    expect(
      validateGhostManifest({
        ...base,
        node: {
          ...base.node,
          protocol: 'mcp-stdio',
          secretBindings: [{ ...binding, methods: ['initialize'] }],
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('宿主保留的 MCP 方法'),
    });
    expect(
      validateGhostManifest({
        ...base,
        node: {
          ...base.node,
          protocol: 'json-rpc-stdio',
          secretBindings: [{ ...binding, methods: ['initialize'] }],
        },
      }).ok,
    ).toBe(true);
    expect(
      validateGhostManifest({
        ...base,
        node: {
          ...base.node,
          secretBindings: [{ ...binding, entry: 'node/other.cjs' }],
        },
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('逐字命中') });
    expect(
      validateGhostManifest({
        ...base,
        node: { ...base.node, secretBindings: [binding, binding] },
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('重复 key') });
    expect(
      validateGhostManifest({
        ...base,
        slots: ['tool', 'node', 'network'],
        node: { ...base.node, secretBindings: [binding] },
        network: {
          hosts: ['api.example.com'],
          secrets: [
            {
              key: 'mail_code',
              label: 'Duplicate key',
              inject: { header: 'Authorization', format: 'Bearer {value}' },
            },
          ],
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与 node.secretBindings 撞名'),
    });
    expect(
      validateGhostManifest({
        ...base,
        slots: ['tool', 'node', 'network'],
        node: { ...base.node, secretBindings: [binding] },
        network: {
          hosts: [],
          connections: [
            {
              key: 'mail_code',
              label: 'Duplicate connection',
              inject: { header: 'Authorization', format: 'Bearer {value}' },
            },
          ],
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与 node.secretBindings'),
    });

    for (const invalidBinding of [
      { ...binding, key: 'Bad-Key' },
      { ...binding, label: '' },
      { ...binding, methods: [] },
      { ...binding, methods: ['mail/action', 'mail/action'] },
      { ...binding, hint: '' },
      { ...binding, url: 'http://mail.example.com/settings' },
    ]) {
      expect(
        validateGhostManifest({
          ...base,
          node: { ...base.node, secretBindings: [invalidBinding] },
        }).ok,
        JSON.stringify(invalidBinding),
      ).toBe(false);
    }
    expect(
      validateGhostManifest({
        ...base,
        node: { ...base.node, secretBindings: [] },
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('1–4 条') });
    expect(
      validateGhostManifest({
        ...base,
        node: {
          ...base.node,
          secretBindings: Array.from({ length: 5 }, (_, index) => ({
            ...binding,
            key: `mail_code_${index}`,
          })),
        },
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('1–4 条') });
  });

  it('drops an empty legacy preview slot and enforces hosts and pattern rules', () => {
    const base = { ...validManifest, slots: ['tool', 'preview'] };
    expect(validateGhostManifest(base)).toMatchObject({
      ok: true,
      manifest: { slots: ['tool'] },
    });
    expect(validateGhostManifest({ ...base, preview: { hosts: [] } }).ok).toBe(false);
    expect(
      validateGhostManifest({
        ...base,
        preview: { hosts: ['https://x.example.com'] },
      }).ok,
    ).toBe(false);
    expect(
      validateGhostManifest({
        ...base,
        preview: { hosts: ['maker.taptap.cn', 'maker.taptap.cn'] },
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('重复域名') });
    expect(
      validateGhostManifest({
        ...validManifest,
        preview: { hosts: ['maker.taptap.cn'] },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('未包含 "preview"'),
    });
    const loopback = validateGhostManifest({
      ...base,
      preview: { hosts: ['localhost', '*.taptap.cn'] },
    });
    expect(loopback.ok).toBe(true);
  });

  it('drops an empty legacy skill slot and enforces item shape rules', () => {
    const base = { ...validManifest, slots: ['tool', 'skill'] };
    const goodItems = [{ dir: 'skills/foo', name: 'foo', description: '教 Agent 用 foo' }];
    expect(validateGhostManifest(base)).toMatchObject({
      ok: true,
      manifest: { slots: ['tool'] },
    });
    expect(validateGhostManifest({ ...validManifest, skill: { items: goodItems } })).toMatchObject({
      ok: false,
      reason: expect.stringContaining('未包含 "skill"'),
    });
    // 合法声明原样收录
    const good = validateGhostManifest({
      ...base,
      skill: { items: goodItems },
    });
    expect(good).toMatchObject({
      ok: true,
      manifest: { skill: { items: goodItems } },
    });
    // 已知字段校验形状;扩展字段保留但不改变技能安装范围。
    expect(validateGhostManifest({ ...base, skill: { items: [] } }).ok).toBe(false);
    expect(validateGhostManifest({ ...base, skill: {} }).ok).toBe(false);
    expect(validateGhostManifest({ ...base, skill: { items: goodItems, extra: 1 } }).ok).toBe(
      true,
    );
    expect(
      validateGhostManifest({
        ...base,
        skill: { items: [{ ...goodItems[0], scope: 'global' }] },
      }).ok,
    ).toBe(true);
    const five = Array.from({ length: 5 }, (_, i) => ({
      dir: `skills/s${i}`,
      name: `s${i}`,
      description: 'x',
    }));
    expect(validateGhostManifest({ ...base, skill: { items: five } })).toMatchObject({
      ok: false,
      reason: expect.stringContaining('最多 4 条'),
    });
    expect(validateGhostManifest({ ...base, skill: { items: five.slice(0, 4) } }).ok).toBe(true);
  });

  it('enforces skill item dir / name / description constraints and case-folded dedupe', () => {
    const base = { ...validManifest, slots: ['tool', 'skill'] };
    const item = (patch: Record<string, unknown>) =>
      validateGhostManifest({
        ...base,
        skill: {
          items: [{ dir: 'skills/foo', name: 'foo', description: 'x', ...patch }],
        },
      });
    // dir:必须是包内安全相对路径
    expect(item({ dir: '../evil' }).ok).toBe(false);
    expect(item({ dir: '/abs/path' }).ok).toBe(false);
    expect(item({ dir: 'skills\\foo' }).ok).toBe(false);
    expect(item({ dir: 'skills/./foo' }).ok).toBe(false);
    expect(item({ dir: '' }).ok).toBe(false);
    // name:小写字母数字单连字符分段(链接名 <id>--<name> 的无歧义前提)
    expect(item({ name: 'foo-bar' }).ok).toBe(true);
    expect(item({ name: 'Foo' }).ok).toBe(false);
    expect(item({ name: '-foo' }).ok).toBe(false);
    expect(item({ name: 'foo-' }).ok).toBe(false);
    expect(item({ name: 'foo--bar' }).ok).toBe(false);
    expect(item({ name: '' }).ok).toBe(false);
    expect(item({ name: 'a'.repeat(65) }).ok).toBe(false);
    expect(item({ name: 'a'.repeat(64) }).ok).toBe(true);
    // description:1–1024 非空
    expect(item({ description: '' }).ok).toBe(false);
    expect(item({ description: '   ' }).ok).toBe(false);
    expect(item({ description: 'x'.repeat(1025) }).ok).toBe(false);
    expect(item({ description: 'x'.repeat(1024) }).ok).toBe(true);
    expect(item({ description: 42 }).ok).toBe(false);
    // name/dir 大小写折叠去重(win32 文件系统折叠大小写)
    expect(
      validateGhostManifest({
        ...base,
        skill: {
          items: [
            { dir: 'skills/a', name: 'foo', description: 'x' },
            { dir: 'skills/b', name: 'foo', description: 'y' },
          ],
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('重复 name'),
    });
    expect(
      validateGhostManifest({
        ...base,
        skill: {
          items: [
            { dir: 'skills/A', name: 'foo', description: 'x' },
            { dir: 'skills/a', name: 'bar', description: 'y' },
          ],
        },
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('重复 dir') });
  });

  it('accepts a top-level manual index without requiring a slot', () => {
    const items = [
      {
        dir: 'manual/getting-started',
        name: 'getting-started',
        description: '按需读取的入门工作流',
      },
    ];
    const result = validateGhostManifest({
      ...validManifest,
      manual: { items },
    });
    expect(result).toMatchObject({
      ok: true,
      manifest: {
        slots: ['tool'],
        manual: { items },
      },
    });
  });

  it('enforces manual items shape, limits, and case-folded dedupe', () => {
    const item = (patch: Record<string, unknown>) =>
      validateGhostManifest({
        ...validManifest,
        manual: {
          items: [
            {
              dir: 'manual/getting-started',
              name: 'getting-started',
              description: 'x',
              ...patch,
            },
          ],
        },
      });

    expect(validateGhostManifest({ ...validManifest, manual: { items: [] } }).ok).toBe(false);
    expect(validateGhostManifest({ ...validManifest, manual: {} }).ok).toBe(false);
    expect(
      validateGhostManifest({
        ...validManifest,
        manual: { items: [], extra: true },
      }).ok,
    ).toBe(false);
    expect(item({ extra: true }).ok).toBe(true);
    const nine = Array.from({ length: 9 }, (_, index) => ({
      dir: `manual/unit-${index}`,
      name: `unit-${index}`,
      description: 'x',
    }));
    expect(validateGhostManifest({ ...validManifest, manual: { items: nine } })).toMatchObject({
      ok: false,
      reason: expect.stringContaining('最多 8 条'),
    });

    expect(item({ dir: '../manual' }).ok).toBe(false);
    expect(item({ dir: 'manual\\guide' }).ok).toBe(false);
    expect(item({ name: 'GettingStarted' }).ok).toBe(false);
    expect(item({ name: 'getting--started' }).ok).toBe(false);
    expect(item({ name: 'a'.repeat(65) }).ok).toBe(false);
    expect(item({ name: 'a'.repeat(64) }).ok).toBe(true);
    expect(item({ description: '' }).ok).toBe(false);
    expect(item({ description: ' '.repeat(3) }).ok).toBe(false);
    expect(item({ description: 'x'.repeat(301) }).ok).toBe(false);
    expect(item({ description: 'x'.repeat(300) }).ok).toBe(true);

    expect(
      validateGhostManifest({
        ...validManifest,
        manual: {
          items: [
            { dir: 'manual/a', name: 'guide', description: 'x' },
            { dir: 'manual/b', name: 'guide', description: 'y' },
          ],
        },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('重复 name'),
    });
    expect(
      validateGhostManifest({
        ...validManifest,
        manual: {
          items: [
            { dir: 'manual/A', name: 'guide-a', description: 'x' },
            { dir: 'manual/a', name: 'guide-b', description: 'y' },
          ],
        },
      }),
    ).toMatchObject({ ok: false, reason: expect.stringContaining('重复 dir') });
  });

  it('intentionally allows nested manual item directories with distinct logical names', () => {
    const items = [
      { dir: 'manual', name: 'overview', description: 'Overview.' },
      {
        dir: 'manual/advanced',
        name: 'advanced',
        description: 'Advanced topics.',
      },
    ];

    expect(validateGhostManifest({ ...validManifest, manual: { items } })).toMatchObject({
      ok: true,
      manifest: expect.objectContaining({ manual: { items } }),
    });
  });

  it('rejects manual directories that contain or descend from declared file paths', () => {
    const withManual = (manifest: Record<string, unknown>, dir: string) =>
      validateGhostManifest({
        ...manifest,
        manual: {
          items: [{ dir, name: 'guide', description: 'Manual guide.' }],
        },
      });
    const declaredFileCases: Array<{
      label: string;
      manifest: Record<string, unknown>;
      dir: string;
    }> = [
      {
        label: 'ghost.json',
        manifest: { ...validManifest },
        dir: 'ghost.json',
      },
      {
        label: 'entry',
        manifest: { ...validManifest, entry: 'manual/entry/main.js' },
        dir: 'manual/entry',
      },
      {
        label: 'icon',
        manifest: { ...validManifest, icon: 'manual/icon/icon.png' },
        dir: 'manual/icon',
      },
      {
        label: 'settingsHtml',
        manifest: {
          ...validManifest,
          settingsHtml: 'manual/settings/settings.html',
        },
        dir: 'manual/settings',
      },
      {
        label: 'panel.html',
        manifest: {
          ...validManifest,
          slots: ['tool', 'panel'],
          panel: { html: 'manual/panel/panel.html', position: 'tab' },
        },
        dir: 'manual/panel',
      },
      {
        label: 'node.entry',
        manifest: {
          ...validManifest,
          slots: ['tool', 'node'],
          node: { entry: 'manual/node/main.cjs', protocol: 'mcp-stdio' },
        },
        dir: 'manual/node',
      },
      {
        label: 'node.entries',
        manifest: {
          ...validManifest,
          slots: ['tool', 'node'],
          node: {
            entry: 'node/main.cjs',
            entries: ['manual/node-extra/child.cjs'],
            protocol: 'mcp-stdio',
          },
        },
        dir: 'manual/node-extra',
      },
    ];

    for (const { label, manifest, dir } of declaredFileCases) {
      expect(withManual(manifest, dir), label).toMatchObject({
        ok: false,
        reason: expect.stringContaining('与插件声明文件路径'),
      });
    }

    expect(
      withManual({ ...validManifest, entry: 'assets/main.js' }, 'assets/main.js/manual'),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与插件声明文件路径'),
    });
    expect(
      withManual({ ...validManifest, entry: 'Manual/Case/main.js' }, 'manual/case'),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('与插件声明文件路径'),
    });
    expect(withManual({ ...validManifest, entry: 'src/main.js' }, 'manual/guide')).toMatchObject({
      ok: true,
      manifest: expect.objectContaining({
        manual: {
          items: [
            {
              dir: 'manual/guide',
              name: 'guide',
              description: 'Manual guide.',
            },
          ],
        },
      }),
    });
  });

  it('validates card and agent capability details', () => {
    expect(
      validateGhostManifest({
        ...validManifest,
        slots: ['tool', 'card'],
        card: { externalLinks: 'yes' },
      }).ok,
    ).toBe(false);
    expect(
      validateGhostManifest({
        ...validManifest,
        card: { externalLinks: true },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('未包含 "card"'),
    });
    const normalizedCard = validateGhostManifest({
      ...validManifest,
      slots: ['tool', 'card'],
      card: { externalLinks: false },
    });
    expect(normalizedCard.ok).toBe(true);
    if (normalizedCard.ok) expect(normalizedCard.manifest).not.toHaveProperty('card');

    expect(
      validateGhostManifest({
        ...validManifest,
        slots: ['tool', 'agent'],
        agent: { background: false },
      }),
    ).toMatchObject({
      ok: false,
      reason: expect.stringContaining('background: true'),
    });
    const backgroundAgent = validateGhostManifest({
      ...validManifest,
      slots: ['tool', 'agent'],
      agent: { background: true },
    });
    expect(backgroundAgent.ok).toBe(true);
    if (backgroundAgent.ok) expect(backgroundAgent.manifest.agent).toEqual({ background: true });

    for (const [capability, expected] of [
      ['errand', { errand: true }],
      ['schedule', { schedule: true }],
    ] as const) {
      const result = validateGhostManifest({
        ...validManifest,
        slots: ['tool', 'agent'],
        agent: { [capability]: true },
      });
      expect(result.ok, capability).toBe(true);
      if (result.ok) expect(result.manifest.agent).toEqual(expected);
    }
  });

  it("panel.position 'tab' 合法;tab 时停靠专属字段(minWidth/defaultFraction)明确拒绝", () => {
    const withPanel = (panel: Record<string, unknown>) => ({
      ...validManifest,
      slots: ['tool', 'panel'],
      panel: { html: 'panel.html', ...panel },
    });

    const tab = validateGhostManifest(withPanel({ position: 'tab' }));
    expect(tab.ok).toBe(true);
    if (tab.ok) expect(tab.manifest.panel?.position).toBe('tab');

    for (const extra of [{ minWidth: 240 }, { defaultFraction: 0.2 }]) {
      const rejected = validateGhostManifest(withPanel({ position: 'tab', ...extra }));
      expect(rejected.ok, JSON.stringify(extra)).toBe(false);
      if (!rejected.ok) expect(rejected.reason).toContain('仅停靠形态');
    }

    // 四条边都是真实的页签组位置(与 Desktop 校验一致),野值仍拒。
    for (const side of ['left', 'right', 'top', 'bottom'] as const) {
      const ok = validateGhostManifest(withPanel({ position: side }));
      expect(ok.ok, side).toBe(true);
      if (ok.ok) expect(ok.manifest.panel?.position).toBe(side);
    }
    expect(validateGhostManifest(withPanel({ position: 'center' })).ok).toBe(false);
  });

  it('mainView.open / side / multiple 与 Desktop 校验一致:合法保留,野值与错配拒', () => {
    const withView = (mainView: Record<string, unknown>) =>
      validateGhostManifest({
        schemaVersion: 3,
        minCindyVersion: '0.1.61',
        id: 'view-helper',
        name: 'View Helper',
        version: '1.0.0',
        entry: 'main.js',
        mainView: { html: 'main-view.html', ...mainView },
      });
    const ok = withView({ open: 'sidebar', side: 'bottom', multiple: true });
    expect(ok.ok).toBe(true);
    if (ok.ok) {
      expect(ok.manifest.mainView).toMatchObject({ open: 'sidebar', side: 'bottom', multiple: true });
    }
    expect(withView({ open: 'popup' }).ok).toBe(false);
    expect(withView({ open: 'page', side: 'left' }).ok).toBe(false);
    expect(withView({ open: 'sidebar', side: 'middle' }).ok).toBe(false);
    expect(withView({ multiple: false }).ok).toBe(false);
  });
});

describe('cindy 详单:media/text/embed/search 类目与 oneshotModel 校验', () => {
  const base = {
    schemaVersion: 2,
    id: 'cindy-full',
    name: 'Cindy Full',
    version: '1.0.0',
    entry: 'main.js',
    slots: ['cindy'],
  };

  it('接受 media/text/embed 类目并保留', () => {
    const r = validateGhostManifest({
      ...base,
      cindy: { media: ['deposit'], text: ['oneshot'], embed: ['text'] },
    });
    expect(r.ok, r.ok ? '' : String(r.reason)).toBe(true);
    if (!r.ok) return;
    expect(r.manifest.cindy).toEqual({
      media: ['deposit'],
      text: ['oneshot'],
      embed: ['text'],
    });
  });

  it('保留当前类目尚未实现的动作,不替换或映射到其它类目', () => {
    expect(validateGhostManifest({ ...base, cindy: { text: ['text'] } })).toMatchObject({ ok: true, manifest: { cindy: { text: ['text'] } } });
    expect(validateGhostManifest({ ...base, cindy: { embed: ['oneshot'] } })).toMatchObject({ ok: true, manifest: { cindy: { embed: ['oneshot'] } } });
  });

  it('接受 search.web 并要求真实工具声明', () => {
    const manifest = {
      ...base,
      slots: ['cindy', 'tool'],
      tools: [{ name: 'search_web', description: 'Search the public web' }],
      cindy: { search: ['web'] },
    };
    const accepted = validateGhostManifest(manifest);
    expect(accepted.ok, accepted.ok ? '' : String(accepted.reason)).toBe(true);
    if (accepted.ok) expect(accepted.manifest.cindy).toEqual({ search: ['web'] });

    expect(validateGhostManifest({ ...base, cindy: { search: ['web'] } }).ok).toBe(false);
    expect(validateGhostManifest({ ...manifest, cindy: { search: ['deep'] } }).ok).toBe(true);
    expect(validateGhostManifest({ ...manifest, cindy: { search: [] } }).ok).toBe(false);
    expect(validateGhostManifest({ ...manifest, cindy: { search: ['web', 'web'] } }).ok).toBe(
      false,
    );
  });

  it('oneshotModel:合法声明落字段;形态非法 / 缺 text.oneshot 单挂 → 拒', () => {
    const ok = validateGhostManifest({
      ...base,
      cindy: { text: ['oneshot'], oneshotModel: 'codex/gpt-5.5' },
    });
    expect(ok.ok, ok.ok ? '' : String(ok.reason)).toBe(true);
    if (ok.ok)
      expect(ok.manifest.cindy).toEqual({
        text: ['oneshot'],
        oneshotModel: 'codex/gpt-5.5',
      });

    for (const bad of [
      { text: ['oneshot'], oneshotModel: '' },
      { text: ['oneshot'], oneshotModel: '   ' },
      { text: ['oneshot'], oneshotModel: 42 },
      { text: ['oneshot'], oneshotModel: 'x'.repeat(129) },
      { oneshotModel: 'codex/gpt-5.5' },
      { image: ['generate'], oneshotModel: 'gpt-5.5' },
    ]) {
      const rejected = validateGhostManifest({ ...base, cindy: bad });
      expect(rejected.ok, JSON.stringify(bad)).toBe(false);
    }
  });
});

describe('agent.hiddenTasks declaration', () => {
  const v3 = { schemaVersion: 3, minCindyVersion: '0.1.0', id: 'bg-tasks', name: 'Background', version: '1.0.0', entry: 'main.js' };
  it('accepts it only together with agent.tasks', () => {
    const ok = validateGhostManifest({ ...v3, agent: { tasks: true, hiddenTasks: true } });
    expect(ok.ok && ok.manifest.agent).toEqual({ tasks: true, hiddenTasks: true });
    expect(validateGhostManifest({ ...v3, agent: { hiddenTasks: true } }).ok).toBe(false);
    expect(validateGhostManifest({ ...v3, agent: { tasks: true, hiddenTasks: 'yes' } }).ok).toBe(false);
    const visible = validateGhostManifest({ ...v3, agent: { tasks: true, hiddenTasks: false } });
    expect(visible.ok && visible.manifest.agent).toEqual({ tasks: true });
  });
});

// New target access is not implied by the old plugin-owned tasks declaration.
it('validates independent target access without dropping the tasks dependency', () => {
  const base = { schemaVersion: 3, minCindyVersion: '0.1.0', id: 'target-test', name: 'Targets', version: '1.0.0', entry: 'main.js' };
  const approved = validateGhostManifest({ ...base, agent: { tasks: true, targets: true } });
  expect(approved.ok && approved.manifest.agent).toEqual({ tasks: true, targets: true });
  expect(validateGhostManifest({ ...base, agent: { targets: true } }).ok).toBe(false);
  expect(validateGhostManifest({ ...base, agent: { tasks: true, targets: 'yes' } }).ok).toBe(false);
  const disabled = validateGhostManifest({ ...base, agent: { tasks: true, targets: false } });
  expect(disabled.ok && disabled.manifest.agent).toEqual({ tasks: true });
});

describe('package release notes', () => {
  const base = { schemaVersion: 3, minCindyVersion: '0.1.0', id: 'notes-test', name: 'Notes test', version: '1.0.0', entry: 'main.js' };
  it('keeps old packages without notes installable', () => {
    const result = validateGhostManifest(base);
    expect(result.ok).toBe(true);
    if (result.ok) expect(result.manifest).not.toHaveProperty('releaseNotes');
  });
  it('retains the complete package text without turning it into manifest summary', () => {
    const releaseNotes = 'First change\nSecond change\n' + 'More changes '.repeat(500);
    const result = validateGhostManifest({ ...base, releaseNotes });
    expect(result.ok).toBe(true);
    if (result.ok) expect(result.manifest.releaseNotes).toBe(releaseNotes);
  });
  it('rejects a non-text package releaseNotes', () => {
    expect(validateGhostManifest({ ...base, releaseNotes: { version: '1' } }).ok).toBe(false);
  });
});