strapi-plugin-mcp-chat 0.1.0

package/server/src/provision/link.ts

@@ -0,0 +1,203 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Manifest } from './manifest';
+import { adapterForManifest, type LinkContext } from './adapters';
+import { generateTypes } from './types-gen';
+import { apiUid } from './generate';
+
+/**
+ * Link: conecta o frontend já instalado à Strapi.
+ *  1. Escreve o .env do framework (aditivo: nunca sobrescreve valor existente).
+ *  2. Gera os tipos TS a partir do manifest.
+ *  3. Gera a config de Preview da Strapi (handler que mapeia uid -> rota do front).
+ *
+ * Tudo aditivo e idempotente. Caminhos validados para ficarem dentro dos dirs
+ * informados.
+ */
+
+export interface LinkOptions {
+  /** pasta do frontend já instalado. */
+  frontendDir: string;
+  /** pasta raiz da app Strapi (onde fica config/). */
+  strapiAppDir: string;
+  context: LinkContext;
+  dryRun?: boolean;
+}
+
+export interface LinkResult {
+  ok: boolean;
+  envFile: string;
+  envAdded: string[];
+  envPreserved: string[];
+  typesFile: string;
+  previewFile: string;
+  previewAction: 'created' | 'sidecar' | 'skipped';
+  errors: string[];
+}
+
+// ---------------------------------------------------------------------------
+// .env (merge aditivo)
+// ---------------------------------------------------------------------------
+
+function parseEnv(content: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of content.split('\n')) {
+    const m = line.match(/^\s*([A-Z0-9_]+)\s*=(.*)$/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+function mergeEnv(
+  existing: string,
+  next: Record<string, string>
+): { content: string; added: string[]; preserved: string[] } {
+  const current = parseEnv(existing);
+  const added: string[] = [];
+  const preserved: string[] = [];
+  const extra: string[] = [];
+
+  for (const [k, v] of Object.entries(next)) {
+    if (k in current) {
+      preserved.push(k); // respeita o que o usuário já tem
+    } else {
+      added.push(k);
+      extra.push(`${k}=${v}`);
+    }
+  }
+
+  let content = existing;
+  if (extra.length) {
+    const block =
+      '\n# adicionado pelo mcp-chat (link)\n' + extra.join('\n') + '\n';
+    content = existing.trimEnd() + '\n' + block;
+  }
+  return { content, added, preserved };
+}
+
+// ---------------------------------------------------------------------------
+// config de Preview da Strapi
+// ---------------------------------------------------------------------------
+
+/**
+ * Gera o conteúdo de config/admin.ts com o Preview configurado: mapeia cada uid
+ * para a rota de preview declarada no manifest e monta a URL com o slug do doc.
+ */
+export function buildPreviewConfig(manifest: Manifest): string {
+  const routes: Record<string, string> = {};
+  for (const ct of manifest.contentTypes) {
+    if (ct.preview?.route) routes[apiUid(ct.singularName)] = ct.preview.route;
+  }
+  const routesJson = JSON.stringify(routes, null, 2);
+
+  return `// Preview gerado pelo mcp-chat a partir do strapi.manifest.json.
+// Mapa uid -> rota do frontend (placeholders :campo são preenchidos pelo doc).
+const PREVIEW_ROUTES: Record<string, string> = ${routesJson};
+
+export default ({ env }) => ({
+  auth: {
+    secret: env('ADMIN_JWT_SECRET'),
+  },
+  apiToken: { salt: env('API_TOKEN_SALT') },
+  transfer: { token: { salt: env('TRANSFER_TOKEN_SALT') } },
+  preview: {
+    enabled: true,
+    config: {
+      allowedOrigins: [env('CLIENT_URL', 'http://localhost:3000')],
+      async handler(uid: string, { documentId, locale, status }: any) {
+        const route = PREVIEW_ROUTES[uid];
+        if (!route) return null;
+        const doc = await strapi.documents(uid as any).findOne({ documentId, locale });
+        if (!doc) return null;
+        // substitui :campo pelos valores do documento (ex.: :slug)
+        const pathname = route.replace(/:([a-zA-Z0-9_]+)/g, (_m, f) =>
+          encodeURIComponent(String((doc as any)[f] ?? ''))
+        );
+        const clientUrl = env('CLIENT_URL', 'http://localhost:3000');
+        const secret = env('PREVIEW_SECRET', '');
+        const qs = new URLSearchParams({ secret, status: status ?? 'draft', path: pathname });
+        return \`\${clientUrl}/api/preview?\${qs.toString()}\`;
+      },
+    },
+  },
+});
+`;
+}
+
+// ---------------------------------------------------------------------------
+// orquestração do link
+// ---------------------------------------------------------------------------
+
+function ensureInside(base: string, target: string): boolean {
+  const n = path.normalize(target);
+  return n === base || n.startsWith(base + path.sep);
+}
+
+export function linkFrontend(
+  manifest: Manifest,
+  opts: LinkOptions
+): LinkResult {
+  const adapter = adapterForManifest(manifest);
+  const result: LinkResult = {
+    ok: false,
+    envFile: adapter.envFileName,
+    envAdded: [],
+    envPreserved: [],
+    typesFile: 'strapi-types.ts',
+    previewFile: 'config/admin.ts',
+    previewAction: 'skipped',
+    errors: [],
+  };
+
+  if (!path.isAbsolute(opts.frontendDir) || !path.isAbsolute(opts.strapiAppDir)) {
+    result.errors.push('frontendDir e strapiAppDir devem ser absolutos');
+    return result;
+  }
+
+  // 1) .env (aditivo)
+  try {
+    const envPath = path.join(opts.frontendDir, adapter.envFileName);
+    if (!ensureInside(opts.frontendDir, envPath)) throw new Error('env fora do frontendDir');
+    const existing = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
+    const vars = adapter.buildEnv(opts.context);
+    const { content, added, preserved } = mergeEnv(existing, vars);
+    result.envAdded = added;
+    result.envPreserved = preserved;
+    if (!opts.dryRun && added.length) fs.writeFileSync(envPath, content, 'utf8');
+  } catch (e: any) {
+    result.errors.push(`env: ${e?.message ?? e}`);
+  }
+
+  // 2) tipos TS (regenerado sempre — arquivo é totalmente owned pelo gerador)
+  try {
+    const typesPath = path.join(opts.frontendDir, result.typesFile);
+    if (!ensureInside(opts.frontendDir, typesPath)) throw new Error('types fora do frontendDir');
+    if (!opts.dryRun) fs.writeFileSync(typesPath, generateTypes(manifest), 'utf8');
+  } catch (e: any) {
+    result.errors.push(`types: ${e?.message ?? e}`);
+  }
+
+  // 3) config de Preview (não-destrutivo)
+  try {
+    const adminPath = path.join(opts.strapiAppDir, 'config', 'admin.ts');
+    const content = buildPreviewConfig(manifest);
+    if (fs.existsSync(adminPath)) {
+      // não sobrescreve config existente: escreve sidecar e reporta
+      result.previewFile = 'config/admin.mcp-chat-preview.ts';
+      const sidecar = path.join(opts.strapiAppDir, 'config', 'admin.mcp-chat-preview.ts');
+      if (!opts.dryRun) fs.writeFileSync(sidecar, content, 'utf8');
+      result.previewAction = 'sidecar';
+    } else {
+      if (!opts.dryRun) {
+        fs.mkdirSync(path.dirname(adminPath), { recursive: true });
+        fs.writeFileSync(adminPath, content, 'utf8');
+      }
+      result.previewAction = 'created';
+    }
+  } catch (e: any) {
+    result.errors.push(`preview: ${e?.message ?? e}`);
+  }
+
+  result.ok = result.errors.length === 0;
+  return result;
+}

package/server/src/provision/manifest.ts

@@ -0,0 +1,281 @@
+import { z } from '@strapi/utils';
+
+/**
+ * O CONTRATO.
+ *
+ * Todo frontend "abençoado" (Next ou TanStack) traz um `strapi.manifest.json`
+ * na raiz. O plugin NUNCA executa código vindo do upload — ele apenas lê e
+ * valida este manifest com o schema abaixo e, a partir dele, provisiona o
+ * backend (gera content-types, semeia conteúdo, liga o preview).
+ *
+ * Validar aqui, ANTES de tocar no disco, é o que torna o upload seguro e
+ * previsível ("nunca quebra"). Tudo que não casar com o schema é rejeitado
+ * com uma mensagem clara, e nada é escrito.
+ */
+
+// ---------------------------------------------------------------------------
+// Nomes seguros
+// ---------------------------------------------------------------------------
+
+/** kebab-case, começa com letra, sem colidir com termos reservados da Strapi. */
+const kebab = z
+  .string()
+  .min(1)
+  .max(48)
+  .regex(/^[a-z][a-z0-9-]*$/, 'use kebab-case (ex.: "produto", "post-blog")');
+
+/** identificador de atributo: snake/camel simples, sem espaços. */
+const attrKey = z
+  .string()
+  .min(1)
+  .max(48)
+  .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, 'nome de campo inválido (use letras/números/_)');
+
+/** Campos que a Strapi cria sozinha — o manifest não pode redefinir. */
+const RESERVED_ATTRS = new Set([
+  'id',
+  'documentId',
+  'createdAt',
+  'updatedAt',
+  'publishedAt',
+  'createdBy',
+  'updatedBy',
+  'locale',
+  'localizations',
+]);
+
+// ---------------------------------------------------------------------------
+// Atributos (subconjunto seguro do Strapi 5 — fase 1)
+// Componentes e dynamic zones ficam para a fase 2.
+// ---------------------------------------------------------------------------
+
+const SCALAR_TYPES = [
+  'string',
+  'text',
+  'richtext',
+  'blocks',
+  'email',
+  'integer',
+  'biginteger',
+  'float',
+  'decimal',
+  'boolean',
+  'date',
+  'datetime',
+  'time',
+  'json',
+] as const;
+
+const commonOpts = {
+  required: z.boolean().optional(),
+  unique: z.boolean().optional(),
+  private: z.boolean().optional(),
+  default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  /**
+   * Marca o campo como traduzível por locale (i18n). Opt-in: ausente ⇒ o campo
+   * é compartilhado entre locales (comportamento atual). Vira
+   * `pluginOptions.i18n.localized:true` no schema gerado. Só faz efeito se a
+   * própria content-type também tiver `localized:true`.
+   */
+  localized: z.boolean().optional(),
+};
+
+const scalarAttr = z.object({
+  type: z.enum(SCALAR_TYPES),
+  ...commonOpts,
+});
+
+/** uid: precisa apontar para um campo string da mesma content-type. */
+const uidAttr = z.object({
+  type: z.literal('uid'),
+  targetField: attrKey.optional(),
+  required: z.boolean().optional(),
+});
+
+const enumAttr = z.object({
+  type: z.literal('enumeration'),
+  enum: z.array(z.string().min(1)).min(1),
+  ...commonOpts,
+});
+
+const mediaAttr = z.object({
+  type: z.literal('media'),
+  multiple: z.boolean().optional(),
+  allowedTypes: z
+    .array(z.enum(['images', 'videos', 'files', 'audios']))
+    .optional(),
+  required: z.boolean().optional(),
+});
+
+const RELATION_KINDS = [
+  'oneToOne',
+  'oneToMany',
+  'manyToOne',
+  'manyToMany',
+] as const;
+
+/**
+ * Relação: `target` deve ser o singularName de OUTRA content-type declarada
+ * neste mesmo manifest (validado no refinamento global abaixo). Mantemos as
+ * relações internas ao manifest para garantir que nada aponte para um type
+ * inexistente — uma das fontes clássicas de "schema quebrado".
+ */
+const relationAttr = z.object({
+  type: z.literal('relation'),
+  relation: z.enum(RELATION_KINDS),
+  target: kebab,
+  required: z.boolean().optional(),
+});
+
+const attribute = z.union([
+  scalarAttr,
+  uidAttr,
+  enumAttr,
+  mediaAttr,
+  relationAttr,
+]);
+
+export type ManifestAttribute = z.infer<typeof attribute>;
+
+// ---------------------------------------------------------------------------
+// Content-type
+// ---------------------------------------------------------------------------
+
+const contentType = z
+  .object({
+    singularName: kebab,
+    pluralName: kebab.optional(),
+    displayName: z.string().min(1).max(64).optional(),
+    kind: z.enum(['collectionType', 'singleType']).default('collectionType'),
+    draftAndPublish: z.boolean().default(true),
+    /**
+     * Liga a localização (i18n) na content-type. Necessário no nível da CT
+     * (confirmado em @strapi/i18n: `isLocalizedContentType` checa
+     * `pluginOptions.i18n.localized`). Os campos a traduzir devem marcar
+     * `localized:true` individualmente.
+     */
+    localized: z.boolean().optional(),
+    description: z.string().max(255).optional(),
+    attributes: z
+      .record(attrKey, attribute)
+      .refine((attrs) => Object.keys(attrs).length > 0, {
+        message: 'a content-type precisa de pelo menos 1 campo',
+      })
+      .refine(
+        (attrs) => Object.keys(attrs).every((k) => !RESERVED_ATTRS.has(k)),
+        { message: 'um campo usa nome reservado da Strapi (ex.: id, createdAt)' }
+      ),
+    /**
+     * Rota do frontend usada para o preview, com placeholders de campo entre
+     * dois-pontos. Ex.: "/produtos/:slug". O adapter de cada framework usa isso
+     * para montar a URL de preview no PreviewPanel.
+     */
+    preview: z
+      .object({
+        route: z
+          .string()
+          .startsWith('/', 'a rota de preview deve começar com "/"'),
+      })
+      .optional(),
+  })
+  // uid.targetField precisa existir e ser string/text
+  .superRefine((ct, ctx) => {
+    for (const [key, attr] of Object.entries(ct.attributes)) {
+      if (attr.type === 'uid' && attr.targetField) {
+        const target = ct.attributes[attr.targetField];
+        if (!target) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `uid "${key}" aponta para campo inexistente "${attr.targetField}"`,
+          });
+        } else if (!['string', 'text'].includes((target as any).type)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `uid "${key}" deve apontar para um campo string/text`,
+          });
+        }
+      }
+    }
+  });
+
+export type ManifestContentType = z.infer<typeof contentType>;
+
+// ---------------------------------------------------------------------------
+// Manifest raiz
+// ---------------------------------------------------------------------------
+
+export const FRAMEWORKS = ['next', 'tanstack'] as const;
+export type Framework = (typeof FRAMEWORKS)[number];
+
+export const manifestSchema = z
+  .object({
+    /** versão do formato do manifest, não do app. */
+    manifestVersion: z.literal(1).default(1),
+    name: kebab,
+    framework: z.enum(FRAMEWORKS),
+    strapiVersion: z.string().optional(),
+    contentTypes: z.array(contentType).min(1).max(60),
+    /** dados demo opcionais, semeados via Document Service após o restart. */
+    seed: z
+      .array(
+        z.object({
+          uid: z.string().optional(), // resolvido pelo provisionador
+          singularName: kebab,
+          entries: z.array(z.record(z.string(), z.any())).max(500),
+        })
+      )
+      .optional(),
+    /** nomes de env vars que o frontend espera (o adapter escreve o .env). */
+    env: z.array(z.string()).optional(),
+  })
+  // nenhum singularName repetido + relações apontam para types existentes
+  .superRefine((m, ctx) => {
+    const names = m.contentTypes.map((c) => c.singularName);
+    const seen = new Set<string>();
+    for (const n of names) {
+      if (seen.has(n)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `content-type duplicada: "${n}"`,
+        });
+      }
+      seen.add(n);
+    }
+    const known = new Set(names);
+    for (const ct of m.contentTypes) {
+      for (const [key, attr] of Object.entries(ct.attributes)) {
+        if (attr.type === 'relation' && !known.has(attr.target)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `relação "${ct.singularName}.${key}" aponta para "${attr.target}", que não está no manifest`,
+          });
+        }
+      }
+    }
+  });
+
+export type Manifest = z.infer<typeof manifestSchema>;
+
+// ---------------------------------------------------------------------------
+// Validador público
+// ---------------------------------------------------------------------------
+
+export type ValidationResult =
+  | { ok: true; data: Manifest }
+  | { ok: false; errors: string[] };
+
+/**
+ * Valida um manifest cru (objeto JS já parseado de JSON). Retorna ou os dados
+ * já normalizados (defaults aplicados), ou uma lista de erros legíveis. Esta é
+ * a única porta de entrada: o provisionador só roda com `ok: true`.
+ */
+export function validateManifest(raw: unknown): ValidationResult {
+  const parsed = manifestSchema.safeParse(raw);
+  if (parsed.success) return { ok: true, data: parsed.data };
+
+  const errors = parsed.error.issues.map((i) => {
+    const path = i.path.length ? `${i.path.join('.')}: ` : '';
+    return `${path}${i.message}`;
+  });
+  return { ok: false, errors };
+}