@monkeyplus/flow 5.0.0-rc.98 → 6.0.0

package/README.md

@@ -0,0 +1,34 @@
+# @monkeyplus/flow
+
+`@monkeyplus/flow` es ahora un paquete reusable con un `playground/` de referencia dentro del mismo workspace.
+
+## Desarrollo diario
+
+- `pnpm dev`: arranca el proyecto de referencia en `playground/`
+- `pnpm build`: construye el `playground/`
+- `pnpm preview`: previsualiza el `playground/`
+
+## Empaquetado del paquete
+
+- `pnpm build:package`: compila el paquete publicable en `dist/`
+- `pnpm pack:package`: genera un tarball npm desde `dist/`
+- `pnpm publish:package`: publica el paquete desde `dist/` con acceso publico
+
+El workspace consume la API fuente del root para mantener DX local, mientras que `dist/` genera un artefacto publicable con exports ya compilados.
+
+## API pública
+
+```ts
+import { defineFlowConfig, definePage } from '@monkeyplus/flow';
+import { FlowIsland } from '@monkeyplus/flow/components';
+import { getClientHead } from '@monkeyplus/flow/head';
+import sitemapModule from '@monkeyplus/flow/modules/sitemap';
+import strapiModule from '@monkeyplus/flow/modules/strapi';
+import { createFlowNitroConfig } from '@monkeyplus/flow/nitro';
+import { createFlowViteConfig } from '@monkeyplus/flow/vite';
+import { installFlowVuePlugins } from '@monkeyplus/flow/vue';
+```
+
+## Playground
+
+La app de referencia vive en `playground/` y ya no en la raíz. Eso permite mantener el root enfocado en la distribución del paquete sin perder el flujo de desarrollo existente.

package/entry-server.d.ts

@@ -0,0 +1 @@
+export {};

package/entry-server.mjs

@@ -0,0 +1,5 @@
+import { renderPageRequest } from './server/lib/handler.mjs';
+
+export default {
+  fetch: renderPageRequest,
+};

package/modules/content/module.d.ts

@@ -0,0 +1,6 @@
+export interface ContentModuleOptions {
+    apiBase: string;
+    dir: string;
+}
+declare const _default: import("../../src/runtime/config.ts").FlowModuleDefinition<ContentModuleOptions>;
+export default _default;

package/modules/content/module.mjs

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import { defineFlowModule } from "../../src/runtime/config.ts";
+import { resolvePackageFile, resolvePackagePath } from "../../src/public/shared.ts";
+export default defineFlowModule({
+  meta: {
+    name: "content",
+    configKey: "content"
+  },
+  defaults: {
+    apiBase: "/api/_content",
+    dir: "content"
+  },
+  setup(options, context) {
+    const contentDir = resolve(context.projectRoot, options.dir);
+    const queryHandlerPath = context.projectRoot === resolvePackagePath() ? resolve(context.projectRoot, "modules/content/query.ts") : resolvePackageFile("modules/content/query.ts", "modules/content/query.mjs", "modules/content/query.js");
+    context.nitro.handlers.push({
+      method: "get",
+      route: `${options.apiBase}/query`,
+      handler: queryHandlerPath
+    });
+    context.nitro.routeRules[`${options.apiBase}/**`] = {
+      cors: true
+    };
+    context.nitro.runtimeConfig.flow = {
+      ...typeof context.nitro.runtimeConfig.flow === "object" && context.nitro.runtimeConfig.flow ? context.nitro.runtimeConfig.flow : {},
+      content: {
+        apiBase: options.apiBase,
+        dir: contentDir
+      }
+    };
+  }
+});

package/modules/content/query.mjs

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { extname, relative, resolve } from "node:path";
+import { defineEventHandler, getQuery } from "nitro/h3";
+import { useRuntimeConfig } from "nitro/runtime-config";
+function collectFiles(rootDir, currentDir = rootDir) {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = resolve(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectFiles(rootDir, fullPath));
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    const extension = extname(entry.name);
+    if (![".md", ".json", ".yml", ".yaml", ".txt"].includes(extension)) {
+      continue;
+    }
+    files.push(fullPath);
+  }
+  return files.sort((left, right) => left.localeCompare(right));
+}
+function normalizeContentPath(rootDir, filePath) {
+  const shortPath = relative(rootDir, filePath).replaceAll("\\", "/");
+  return `/${shortPath.replace(/\.(md|json|ya?ml|txt)$/i, "")}`;
+}
+function parseKeyValueBlock(block) {
+  return block.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).reduce((data, line) => {
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex <= 0) {
+      return data;
+    }
+    const key = line.slice(0, separatorIndex).trim();
+    const value = line.slice(separatorIndex + 1).trim();
+    data[key] = value;
+    return data;
+  }, {});
+}
+function parseContentFile(rootDir, filePath) {
+  const raw = readFileSync(filePath, "utf8");
+  const extension = extname(filePath).toLowerCase();
+  const path = normalizeContentPath(rootDir, filePath);
+  if (extension === ".json") {
+    const parsed = JSON.parse(raw);
+    return {
+      path,
+      extension,
+      title: typeof parsed.title === "string" ? parsed.title : void 0,
+      body: JSON.stringify(parsed, null, 2),
+      data: Object.entries(parsed).reduce((result, [key, value]) => {
+        if (typeof value === "string") {
+          result[key] = value;
+        }
+        return result;
+      }, {})
+    };
+  }
+  if ((extension === ".yml" || extension === ".yaml") && raw.trim()) {
+    const data = parseKeyValueBlock(raw);
+    return {
+      path,
+      extension,
+      title: data.title,
+      body: raw,
+      data
+    };
+  }
+  if (raw.startsWith("---\n")) {
+    const end = raw.indexOf("\n---\n", 4);
+    if (end >= 0) {
+      const frontmatter = raw.slice(4, end);
+      const body = raw.slice(end + 5).trim();
+      const data = parseKeyValueBlock(frontmatter);
+      return {
+        path,
+        extension,
+        title: data.title,
+        body,
+        data
+      };
+    }
+  }
+  return {
+    path,
+    extension,
+    body: raw,
+    data: {}
+  };
+}
+export default defineEventHandler((event) => {
+  const runtimeConfig = useRuntimeConfig();
+  const query = getQuery(event);
+  const contentDir = runtimeConfig.flow?.content?.dir;
+  if (!contentDir || !existsSync(contentDir)) {
+    return [];
+  }
+  const entries = collectFiles(contentDir).map((filePath) => parseContentFile(contentDir, filePath));
+  if (query.path) {
+    return entries.filter((entry) => entry.path === query.path || entry.path.startsWith(`${query.path}/`));
+  }
+  return entries;
+});

package/modules/sitemap/handler.mjs

@@ -0,0 +1,17 @@
+import { defineEventHandler, getRequestURL, setHeader } from "nitro/h3";
+import { useRuntimeConfig } from "nitro/runtime-config";
+import { getUrls } from "../../server/lib/pages.ts";
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+export default defineEventHandler(async (event) => {
+  const urls = await getUrls(true, true);
+  const runtimeConfig = useRuntimeConfig();
+  const origin = runtimeConfig.flow?.siteUrl || getRequestURL(event).origin;
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.map((entry) => typeof entry === "string" ? `  <url><loc>${escapeXml(new URL(entry, origin).toString())}</loc></url>` : `  <url><loc>${escapeXml(new URL(entry.url, origin).toString())}</loc><xhtml:link rel="alternate" hreflang="${escapeXml(entry.locale)}" href="${escapeXml(new URL(entry.url, origin).toString())}" xmlns:xhtml="http://www.w3.org/1999/xhtml" /></url>`).join("\n")}
+</urlset>`;
+  setHeader(event, "content-type", "application/xml; charset=utf-8");
+  return xml;
+});

package/modules/sitemap/module.d.ts

@@ -0,0 +1,6 @@
+export interface SitemapModuleOptions {
+    route: string;
+    prerender: boolean;
+}
+declare const _default: import("../../src/runtime/config.ts").FlowModuleDefinition<SitemapModuleOptions>;
+export default _default;

package/modules/sitemap/module.mjs

@@ -0,0 +1,28 @@
+import { resolve } from "node:path";
+import { defineFlowModule } from "../../src/runtime/config.ts";
+import { resolvePackageFile, resolvePackagePath } from "../../src/public/shared.ts";
+export default defineFlowModule({
+  meta: {
+    name: "sitemap",
+    configKey: "sitemap"
+  },
+  defaults: {
+    route: "/sitemap.xml",
+    prerender: true
+  },
+  setup(options, context) {
+    const localHandlerPath = resolve(context.projectRoot, "modules/sitemap/handler.ts");
+    const handlerPath = context.projectRoot === resolvePackagePath() ? localHandlerPath : resolvePackageFile("modules/sitemap/handler.ts", "modules/sitemap/handler.mjs", "modules/sitemap/handler.js");
+    context.nitro.handlers.push({
+      method: "get",
+      route: options.route,
+      handler: handlerPath
+    });
+    context.nitro.routeRules[options.route] = {
+      prerender: options.prerender
+    };
+    if (options.prerender) {
+      context.prerenderRoutes.add(options.route);
+    }
+  }
+});

package/modules/strapi/README.md

@@ -0,0 +1,235 @@
+# Flow Strapi Module
+
+Este modulo integra Strapi en Flow con una API de uso inspirada en `@nuxtjs/strapi`.
+
+Hoy cubre tres piezas:
+
+- Configuracion del modulo desde `flow.config.ts`
+- Proxy servidor para llamadas REST y GraphQL
+- Helpers de runtime expuestos mediante el alias `#strapi`
+
+La capa de autenticacion se implementara despues. Por ahora no incluye `login`, `logout`, `me` ni manejo de cookies/JWT en cliente.
+
+## Activacion
+
+```ts
+import { defineFlowConfig } from './src/runtime/config.ts';
+
+export default defineFlowConfig({
+  modules: [
+    './modules/strapi/module.ts',
+  ],
+  strapi: {
+    url: process.env.STRAPI_URL,
+    token: process.env.STRAPI_TOKEN,
+    prefix: '/api',
+    admin: '/admin',
+    version: 'v5',
+  },
+});
+```
+
+## Opciones
+
+Opciones disponibles en `strapi`:
+
+```ts
+{
+  apiBase: '/api/_strapi',
+  url: process.env.STRAPI_URL || 'http://localhost:1337',
+  prefix: '/api',
+  admin: '/admin',
+  version: 'v5',
+  token: process.env.STRAPI_TOKEN || ''
+}
+```
+
+Descripcion de cada opcion:
+
+- `apiBase`: ruta interna en Flow usada por el proxy cuando el codigo corre en cliente.
+- `url`: URL base de la instancia de Strapi.
+- `prefix`: prefijo REST de Strapi, normalmente `/api`.
+- `admin`: prefijo del panel admin de Strapi.
+- `version`: version objetivo de Strapi. Actualmente se expone para consumo de runtime y documentacion; la API helper actual esta enfocada en REST moderno tipo v4/v5.
+- `token`: token Bearer usado del lado servidor para reenviar peticiones autenticadas al backend de Strapi.
+
+## Como funciona
+
+Cuando el modulo se carga:
+
+- registra un handler Nitro en `${apiBase}/**`
+- publica configuracion segura para cliente
+- conserva el `token` solo en runtime del servidor
+- expone el alias `#strapi`
+
+En cliente, las llamadas van contra el proxy de Flow, por defecto `/api/_strapi`.
+
+En servidor, las llamadas pueden resolverse directamente contra `STRAPI_URL`, adjuntando el `Bearer token` si existe.
+
+## API de runtime
+
+Importa desde `#strapi`:
+
+```ts
+import {
+  useStrapi,
+  useStrapiClient,
+  useStrapiGraphQL,
+  useStrapiVersion,
+  useStrapiUrl,
+  useStrapiAdminUrl,
+  useStrapiMedia,
+} from '#strapi';
+```
+
+### `useStrapi()`
+
+Devuelve helpers REST de alto nivel:
+
+- `find(contentType, params?, options?)`
+- `findOne(contentType, documentId, params?, options?)`
+- `create(contentType, data, params?, options?)`
+- `update(contentType, documentId, data?, params?, options?)`
+- `delete(contentType, documentId?, params?, options?)`
+
+Ejemplo:
+
+```ts
+import { useStrapi } from '#strapi';
+
+const { find, findOne, create, update, delete: remove } = useStrapi();
+
+const articles = await find('articles', {
+  populate: '*',
+  sort: ['publishedAt:desc'],
+});
+
+const article = await findOne('articles', 'my-document-id', {
+  populate: '*',
+});
+
+await create('articles', {
+  title: 'Nuevo articulo',
+});
+
+await update('articles', 'my-document-id', {
+  title: 'Titulo actualizado',
+});
+
+await remove('articles', 'my-document-id');
+```
+
+### `useStrapiClient()`
+
+Es un wrapper de `fetch` para endpoints no cubiertos por los helpers REST.
+
+```ts
+import { useStrapiClient } from '#strapi';
+
+const client = useStrapiClient();
+
+const response = await client('/articles', {
+  params: {
+    populate: '*',
+  },
+});
+```
+
+### `useStrapiGraphQL()`
+
+Envuelve llamadas a GraphQL usando `POST` sobre `/graphql`.
+
+```ts
+import { useStrapiGraphQL } from '#strapi';
+
+const graphql = useStrapiGraphQL();
+
+const data = await graphql(`
+  query Article($id: ID!) {
+    article(documentId: $id) {
+      documentId
+      title
+    }
+  }
+`, {
+  id: 'my-document-id',
+});
+```
+
+### `useStrapiUrl()`
+
+Devuelve la URL REST de Strapi con `prefix` aplicado.
+
+```ts
+import { useStrapiUrl } from '#strapi';
+
+const articlesUrl = useStrapiUrl('/articles');
+```
+
+### `useStrapiAdminUrl()`
+
+Devuelve la URL del admin de Strapi usando `admin`.
+
+```ts
+import { useStrapiAdminUrl } from '#strapi';
+
+const adminUrl = useStrapiAdminUrl();
+```
+
+### `useStrapiVersion()`
+
+Expone la version configurada:
+
+```ts
+import { useStrapiVersion } from '#strapi';
+
+const version = useStrapiVersion();
+```
+
+### `useStrapiMedia()`
+
+Convierte rutas relativas de medios en URLs absolutas cuando `url` esta configurado.
+
+```ts
+import { useStrapiMedia } from '#strapi';
+
+const imageUrl = useStrapiMedia('/uploads/hero.jpg');
+```
+
+## Parametros de consulta
+
+Los helpers aceptan un objeto `params` y lo serializan a query string soportando objetos y arrays anidados.
+
+Ejemplo:
+
+```ts
+const { find } = useStrapi();
+
+await find('articles', {
+  populate: {
+    cover: true,
+    author: {
+      fields: ['name', 'slug'],
+    },
+  },
+  filters: {
+    slug: {
+      $eq: 'hello-world',
+    },
+  },
+});
+```
+
+## Consideraciones
+
+- El modulo esta pensado para trabajar bien en SSR y en cliente.
+- En cliente no se expone el token privado; las llamadas pasan por el proxy.
+- En servidor, si `STRAPI_URL` existe, se llama directo a Strapi.
+- `version` hoy es informativa; la capa helper actual no separa clientes distintos por v3, v4 y v5.
+- La autenticacion estilo Nuxt Strapi todavia no esta implementada.
+
+## Archivos principales
+
+- `modules/strapi/module.ts`: registro del modulo y configuracion
+- `modules/strapi/proxy.ts`: proxy Nitro hacia Strapi
+- `modules/strapi/runtime/client.ts`: helpers consumidos desde `#strapi`

package/modules/strapi/module.d.ts

@@ -0,0 +1,11 @@
+export type StrapiVersion = 'v5' | 'v4' | 'v3';
+export interface StrapiModuleOptions {
+    apiBase: string;
+    url: string;
+    prefix: string;
+    admin: string;
+    version: StrapiVersion;
+    token?: string;
+}
+declare const _default: import("../../src/runtime/config.ts").FlowModuleDefinition<StrapiModuleOptions>;
+export default _default;

package/modules/strapi/module.mjs

@@ -0,0 +1,69 @@
+import { resolve } from "node:path";
+import { defineFlowModule } from "../../src/runtime/config.ts";
+import { resolvePackageFile, resolvePackagePath } from "../../src/public/shared.ts";
+function createStrapiConfigPlugin(config) {
+  const virtualId = "virtual:flow/strapi-config";
+  const resolvedVirtualId = `\0${virtualId}`;
+  return {
+    name: "flow:strapi-config",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === virtualId) {
+        return resolvedVirtualId;
+      }
+    },
+    load(id) {
+      if (id !== resolvedVirtualId) {
+        return null;
+      }
+      return `export default ${JSON.stringify(config)};
+`;
+    }
+  };
+}
+export default defineFlowModule({
+  meta: {
+    name: "strapi",
+    configKey: "strapi"
+  },
+  defaults: {
+    apiBase: "/api/_strapi",
+    url: process.env.STRAPI_URL || "http://localhost:1337",
+    prefix: "/api",
+    admin: "/admin",
+    version: "v5",
+    token: process.env.STRAPI_TOKEN || ""
+  },
+  setup(options, context) {
+    const publicConfig = {
+      apiBase: options.apiBase,
+      url: options.url,
+      prefix: options.prefix,
+      admin: options.admin,
+      version: options.version
+    };
+    context.nitro.handlers.push({
+      route: `${options.apiBase}/**`,
+      handler: context.projectRoot === resolvePackagePath() ? resolve(context.projectRoot, "modules/strapi/proxy.ts") : resolvePackageFile("modules/strapi/proxy.ts", "modules/strapi/proxy.mjs", "modules/strapi/proxy.js")
+    });
+    context.nitro.routeRules[`${options.apiBase}/**`] = {
+      cors: true
+    };
+    context.nitro.runtimeConfig.flow = {
+      ...typeof context.nitro.runtimeConfig.flow === "object" && context.nitro.runtimeConfig.flow ? context.nitro.runtimeConfig.flow : {},
+      strapi: {
+        ...publicConfig,
+        token: options.token || ""
+      }
+    };
+    context.nitro.runtimeConfig.public = {
+      ...typeof context.nitro.runtimeConfig.public === "object" && context.nitro.runtimeConfig.public ? context.nitro.runtimeConfig.public : {},
+      flow: {
+        ...typeof context.nitro.runtimeConfig.public?.flow === "object" && context.nitro.runtimeConfig.public.flow ? context.nitro.runtimeConfig.public.flow : {},
+        strapi: publicConfig
+      }
+    };
+    context.vite.resolve.alias["#strapi"] = context.projectRoot === resolvePackagePath() ? resolve(context.projectRoot, "modules/strapi/runtime/client.ts") : resolvePackageFile("modules/strapi/runtime/client.ts", "modules/strapi/runtime/client.mjs", "modules/strapi/runtime/client.js");
+    context.vite.plugins.push(createStrapiConfigPlugin(publicConfig));
+  }
+});

package/modules/strapi/proxy.mjs

@@ -0,0 +1,54 @@
+import { appendHeader, createError, defineEventHandler, getHeaders, getMethod, getQuery, getRequestURL, getRouterParam, readRawBody, setResponseStatus } from "nitro/h3";
+import { useRuntimeConfig } from "nitro/runtime-config";
+function withLeadingSlash(value) {
+  return value.startsWith("/") ? value : `/${value}`;
+}
+export default defineEventHandler(async (event) => {
+  const runtimeConfig = useRuntimeConfig();
+  const strapi = runtimeConfig.flow?.strapi;
+  if (!strapi?.url) {
+    throw createError({
+      statusCode: 500,
+      statusMessage: "Missing Strapi URL in flow.strapi.url"
+    });
+  }
+  const slug = getRouterParam(event, "_") || "";
+  const prefix = withLeadingSlash(strapi.prefix || "/api");
+  const target = new URL(`${prefix}/${slug}`.replace(/\/+/g, "/"), strapi.url);
+  const incomingUrl = getRequestURL(event);
+  for (const [key, value] of Object.entries(getQuery(event))) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        target.searchParams.append(key, item);
+      }
+      continue;
+    }
+    if (value != null) {
+      target.searchParams.set(key, String(value));
+    }
+  }
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(getHeaders(event))) {
+    if (value && key.toLowerCase() !== "host") {
+      headers.set(key, value);
+    }
+  }
+  if (strapi.token) {
+    headers.set("authorization", `Bearer ${strapi.token}`);
+  }
+  const method = getMethod(event);
+  const body = method === "GET" || method === "HEAD" ? void 0 : await readRawBody(event, false);
+  const response = await fetch(target, {
+    method,
+    headers,
+    body
+  });
+  setResponseStatus(event, response.status, response.statusText);
+  response.headers.forEach((value, key) => {
+    appendHeader(event, key, value);
+  });
+  if (incomingUrl.pathname.endsWith(".json") || response.headers.get("content-type")?.includes("application/json")) {
+    return await response.json();
+  }
+  return await response.text();
+});

package/modules/strapi/runtime/client.d.ts

@@ -0,0 +1,30 @@
+export interface StrapiFetchOptions extends RequestInit {
+    params?: Record<string, unknown>;
+}
+export interface StrapiPublicConfig {
+    apiBase: string;
+    url: string;
+    prefix: string;
+    admin: string;
+    version: 'v5' | 'v4' | 'v3';
+}
+export declare const strapiConfig: StrapiPublicConfig;
+export declare function useStrapiVersion(): "v5" | "v4" | "v3";
+export declare function useStrapiUrl(path?: string): string;
+export declare function useStrapiAdminUrl(path?: string): string;
+export declare function useStrapiMedia(url?: string | null): string | null | undefined;
+export declare function useStrapiClient(): <T>(url: string, options?: StrapiFetchOptions) => Promise<T>;
+export declare function useStrapi<T = unknown>(): {
+    find<TResult = T>(contentType: string, params?: Record<string, unknown>, options?: StrapiFetchOptions): Promise<TResult>;
+    findOne<TResult = T>(contentType: string, documentId: string, params?: Record<string, unknown>, options?: StrapiFetchOptions): Promise<TResult>;
+    create<TResult = T>(contentType: string, data: Partial<TResult>, params?: Record<string, unknown>, options?: StrapiFetchOptions): Promise<TResult>;
+    update<TResult = T>(contentType: string, documentId: string, data?: Partial<TResult>, params?: Record<string, unknown>, options?: StrapiFetchOptions): Promise<TResult>;
+    delete(contentType: string, documentId?: string, params?: Record<string, unknown>, options?: StrapiFetchOptions): Promise<void>;
+};
+export declare function useStrapiGraphQL(): <T>(query: string | {
+    loc?: {
+        source?: {
+            body?: string;
+        };
+    };
+}, variables?: Record<string, unknown>, options?: StrapiFetchOptions) => Promise<T>;