southpaw 0.2.7

package/README.md

@@ -0,0 +1,51 @@
+# Southpaw
+
+A behavior-driven Next.js framework.
+
+Southpaw is a superset of Next.js that enforces a strict separation between **UI (Blocks)**, **Logic (Behaviors)**, and **Pages**. It comes with a visual editor, AI-powered code generation, and a built-in component library.
+
+## Quick Start
+
+Create a new Southpaw project:
+
+```bash
+npx southpaw
+```
+
+You'll be prompted to choose a project name and template. Then:
+
+```bash
+cd your-project
+npm install
+npm run dev
+```
+
+## CLI Commands
+
+| Command | Description |
+| --- | --- |
+| `npx southpaw` | Create a new project from a template |
+| `npx southpaw generate-block` | AI-powered block (component) generation |
+| `npx southpaw generate-behavior` | Scaffold a new behavior |
+| `npx southpaw generate-page` | Scaffold a new page |
+| `npx southpaw test` | Run route-level tests with Puppeteer |
+
+## Core Concepts
+
+### Behaviors
+Manage global or shared state with `create_behaviors`. Define `state`, `actions`, `when` (action labels), `then` (state labels), and `given` (test scenarios).
+
+### Blocks
+Reusable UI components built with `create_component`. Define `propsDef` for visual editor integration, local `state`, `computed` values, `methods`, and `lifecycle` hooks.
+
+### Pages
+Connect blocks and behaviors using `create_page`. Access behaviors via `this.do` and `this.get`, and translations via `this.trans`.
+
+## Requirements
+
+- Node.js >= 18
+- Next.js >= 15.2.4
+
+## License
+
+MIT

package/api/client.ts

@@ -0,0 +1,83 @@
+import { ApiType, StreamCallback, StreamIterator } from "../types/api";
+import { UTILS } from "../utils";
+
+const post = async <
+  T extends Extract<keyof ApiType, string>,
+  K extends Extract<keyof ApiType[T], string>,
+>(
+  parentSlug: T,
+  childSlug: K,
+  //@ts-expect-error Whatever
+  args?: Parameters<ApiType[T][K]>[0] = {},
+  //@ts-expect-error Whatever
+): Promise<ReturnType<ApiType[T][K]>> => {
+  const result = await fetch(
+    `/api/dev/${String(parentSlug)}/${String(childSlug)}`,
+    {
+      method: "POST",
+      body: JSON.stringify(args),
+    },
+  );
+  const isJson = result.headers
+    .get("Content-Type")
+    ?.startsWith("application/json;");
+  if (isJson) {
+    const json = await result.json();
+    UTILS.event.dispatch("next-ide-notification", {
+      type: json.type,
+      message: json.message,
+    });
+    return json;
+  } else {
+    const stream = result.body as StreamIterator;
+    const fn: StreamCallback = async (cb) => {
+      for await (const chunk of stream) {
+        const decoder = new TextDecoder();
+        const value = decoder.decode(chunk, { stream: true });
+        cb(value, stream);
+      }
+    };
+    return fn as any;
+  }
+};
+export const FETCH: ApiType = {
+  application: {},
+  page: {
+    async writeSEO(args) {
+      const result = await post("page", "writeSEO", args);
+      return Promise.resolve(result);
+    },
+    async insertNode(args) {
+      const result = await post("page", "insertNode", args);
+      return Promise.resolve(result);
+    },
+    async duplicateNode(args) {
+      const result = await post("page", "duplicateNode", args);
+      return Promise.resolve(result);
+    },
+    async deleteNode(args) {
+      const result = await post("page", "deleteNode", args);
+      return Promise.resolve(result);
+    },
+    async moveUpNode(args) {
+      const result = await post("page", "moveUpNode", args);
+      return Promise.resolve(result);
+    },
+    async moveDownNode(args) {
+      const result = await post("page", "moveDownNode", args);
+      return Promise.resolve(result);
+    },
+    async moveNode(args) {
+      const result = await post("page", "moveNode", args);
+      return Promise.resolve(result);
+    },
+    async setPropNode(args) {
+      const result = await post("page", "setPropNode", args);
+      return Promise.resolve(result);
+    },
+    async getRawPropsNode(args) {
+      const result = await post("page", "getRawPropsNode", args);
+      return Promise.resolve(result);
+    },
+  },
+};

package/api/helpers/fs.ts

@@ -0,0 +1,98 @@
+import path, { ParsedPath } from "path";
+import fs from "fs";
+
+export type GlobFile = {
+  name: string;
+  url: string;
+  content: string;
+  parsedPath: ParsedPath;
+  type:
+    | "page"
+    | "component"
+    | "public"
+    | "api"
+    | "module"
+    | "behavior"
+    | "translation";
+};
+export function isPathPage(url: string) {
+  const normalizedUrl = normalizeSeparator(url);
+  const nextPageRegex = /src\/pages\/.*?\.(tsx|jsx)$/;
+  return nextPageRegex.test(normalizedUrl);
+}
+export function isPathComponent(url: string) {
+  const normalizedUrl = normalizeSeparator(url);
+  const nextComponentsRegex = /src\/components\/.*?\.(tsx|jsx)$/;
+  return nextComponentsRegex.test(normalizedUrl);
+}
+export function isPathBehavior(url: string) {
+  const normalizedUrl = normalizeSeparator(url);
+  const nextBehaviorRegex = /src\/behaviors\/.*?\.(ts)$/;
+  return nextBehaviorRegex.test(normalizedUrl);
+}
+export function isPathTranslation(url: string) {
+  const normalizedUrl = normalizeSeparator(url);
+  const nextTranslationRegex = /src\/translations\/.*?\.(ts)$/;
+  return nextTranslationRegex.test(normalizedUrl);
+}
+export function isPathApi(url: string) {
+  const normalizedUrl = normalizeSeparator(url);
+  const nextApiRegex = /src\/pages\/api\/[^/]+\.(js|ts)$/;
+  return nextApiRegex.test(normalizedUrl);
+}
+export function normalizeSeparator(url: string) {
+  return url.replace(/\\/g, "/");
+}
+export async function readDir(dirPath: string) {
+  const fs = await import("fs/promises");
+  return fs.readdir(dirPath);
+}
+export async function readPages(): Promise<GlobFile[]> {
+  const fastGlob = await import("fast-glob");
+  const pages: GlobFile[] = fastGlob
+    .sync(["src/pages/**/*"], {
+      onlyFiles: true,
+      ignore: [
+        "src/pages/api/**/*",
+        "src/pages/_app.tsx",
+        "src/pages/_document.tsx",
+      ],
+    })
+    .map((url) => {
+      const parsedPath = path.parse(url);
+      const content = fs
+        .readFileSync(url, "utf-8")
+        // .replace(/^\s*[\r]/gm, "") // remove empty lines
+        .trim();
+      return {
+        name: parsedPath.name,
+        content,
+        url,
+        parsedPath,
+        type: "page",
+      };
+    });
+  return pages;
+}
+export async function readModules(): Promise<GlobFile[]> {
+  const fastGlob = await import("fast-glob");
+  const modules: GlobFile[] = fastGlob
+    .sync(["node_modules/southpaw/modules/**/*"], {
+      onlyFiles: true,
+    })
+    .map((url) => {
+      const parsedPath = path.parse(url);
+      const content = fs
+        .readFileSync(url, "utf-8")
+        // .replace(/^\s*[\r]/gm, "") // remove empty lines
+        .trim();
+      return {
+        name: parsedPath.name,
+        content,
+        url,
+        parsedPath,
+        type: "module",
+      };
+    });
+  return modules;
+}

package/api/helpers/stream.ts

@@ -0,0 +1,6 @@
+export const encodeControllerChunk = (
+  controller: ReadableStreamDefaultController,
+  chunk: string
+) => {
+  controller.enqueue(new TextEncoder().encode(chunk));
+};

package/api/index.ts

@@ -0,0 +1,50 @@
+import type { NextApiRequest, NextApiResponse } from "next";
+import { API } from "./server";
+
+export async function handler<T extends keyof typeof API = keyof typeof API>(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  const { dev } = req.query;
+
+  if (dev) {
+    const parentSlug = dev[0];
+    const genreSlug = dev[1] as T;
+    const actionSlug = dev[2] as keyof (typeof API)[T];
+    if (parentSlug === "dev" && genreSlug && actionSlug) {
+      const action = API[genreSlug][actionSlug] as unknown as (
+        arg: unknown
+      ) => unknown;
+      try {
+        if (!req.body) {
+          throw new Error("body is missing");
+        }
+        const result = await action(JSON.parse(req.body));
+        if (result instanceof ReadableStream) {
+          result.pipeTo(
+            new WritableStream({
+              write(chunk: Uint8Array) {
+                res.write(chunk);
+              },
+              close() {
+                res.end();
+              },
+            })
+          );
+        } else {
+          res.status(200).json(result);
+        }
+      } catch (error) {
+        res.status(500).json({
+          type: "error",
+          message: (error as Error).message,
+          payload: {},
+        });
+      }
+    } else {
+      res.status(500).json({});
+    }
+  } else {
+    res.status(500).json({});
+  }
+}