@fiyuu/core 0.1.0 → 0.1.1

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@fiyuu/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
-  "main": "./src/index.js",
-  "types": "./src/index.d.ts",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./client": "./src/client.js"
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts"
   },
   "dependencies": {
     "zod": "^3.24.2"

package/src/artifacts.ts

@@ -0,0 +1,328 @@
+import { existsSync, promises as fs } from "node:fs";
+import path from "node:path";
+import { createProjectGraph, type ProjectGraph } from "./scanner.js";
+
+export async function syncProjectArtifacts(rootDirectory: string, appDirectory: string): Promise<ProjectGraph> {
+  const graph = await createProjectGraph(appDirectory);
+  const outputDirectory = path.join(rootDirectory, ".fiyuu");
+
+  await fs.mkdir(outputDirectory, { recursive: true });
+  await fs.writeFile(path.join(outputDirectory, "graph.json"), `${JSON.stringify(graph, null, 2)}\n`);
+
+  const skills = await loadSkillSummaries(rootDirectory);
+  const docs = createAiDocs(graph, rootDirectory, skills);
+
+  await Promise.all([
+    fs.writeFile(path.join(outputDirectory, "PROJECT.md"), docs.project),
+    fs.writeFile(path.join(outputDirectory, "PATHS.md"), docs.paths),
+    fs.writeFile(path.join(outputDirectory, "STATES.md"), docs.states),
+    fs.writeFile(path.join(outputDirectory, "FEATURES.md"), docs.features),
+    fs.writeFile(path.join(outputDirectory, "WARNINGS.md"), docs.warnings),
+    fs.writeFile(path.join(outputDirectory, "SKILLS.md"), docs.skills),
+    fs.writeFile(path.join(outputDirectory, "EXECUTION.md"), docs.execution),
+    fs.writeFile(path.join(outputDirectory, "INTERVENTIONS.md"), docs.interventions),
+    fs.writeFile(path.join(outputDirectory, "DOCTOR.md"), docs.doctor),
+  ]);
+
+  return graph;
+}
+
+interface SkillSummary {
+  name: string;
+  description: string;
+  tags: string[];
+  filePath: string;
+}
+
+async function loadSkillSummaries(rootDirectory: string): Promise<SkillSummary[]> {
+  const skillsDir = path.join(rootDirectory, "skills");
+  if (!existsSync(skillsDir)) return [];
+
+  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+  const skillFiles = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".ts"));
+
+  return Promise.all(
+    skillFiles.map(async (entry) => {
+      const filePath = path.join(skillsDir, entry.name);
+      const source = await fs.readFile(filePath, "utf8");
+
+      const nameMatch = source.match(/name\s*:\s*["'`]([^"'`]+)["'`]/);
+      const descMatch = source.match(/description\s*:\s*["'`]([^"'`]+)["'`]/);
+      const tagsMatch = source.match(/tags\s*:\s*\[([^\]]*)\]/);
+      const tags = tagsMatch
+        ? tagsMatch[1].match(/["'`]([^"'`]+)["'`]/g)?.map((t) => t.replace(/["'`]/g, "")) ?? []
+        : [];
+
+      return {
+        name: nameMatch?.[1] ?? entry.name.replace(/\.ts$/, ""),
+        description: descMatch?.[1] ?? "no description",
+        tags,
+        filePath: `skills/${entry.name}`,
+      };
+    }),
+  );
+}
+
+export function createAiDocs(
+  graph: ProjectGraph,
+  rootDirectory: string,
+  skills: SkillSummary[] = [],
+): {
+  project: string;
+  paths: string;
+  states: string;
+  features: string;
+  warnings: string;
+  skills: string;
+  execution: string;
+  interventions: string;
+  doctor: string;
+} {
+  const project = `# Fiyuu Project Context
+
+This file is auto-generated for AI systems reading the project.
+Do not edit manually — run \`fiyuu sync\` to regenerate.
+
+## Summary
+
+- root: ${rootDirectory}
+- routes: ${graph.routes.length}
+- features: ${graph.features.length}
+- actions: ${graph.actions.length}
+- queries: ${graph.queries.length}
+- skills: ${skills.length}
+
+## Architecture
+
+Fiyuu is a file-based fullstack framework built on GEA (@geajs/core).
+Each route is a feature directory under \`app/\` with these fixed files:
+- \`meta.ts\` — intent, title, render mode, SEO (required)
+- \`schema.ts\` — Zod input/output contracts (required)
+- \`page.tsx\` — GEA component for UI (optional)
+- \`query.ts\` — data fetching with \`execute()\` (optional)
+- \`action.ts\` — server mutations with \`execute()\` (optional)
+- \`layout.tsx\` — route-scoped layout wrapper (optional)
+- \`middleware.ts\` — request middleware (optional)
+- \`route.ts\` — raw API route (optional, for \`/api/*\`)
+
+## Route Overview
+
+${graph.features
+  .map(
+    (feature) =>
+      `- route: ${feature.route}\n  intent: ${feature.intent ?? "missing"}\n  render: ${feature.render}\n  missing: ${feature.missingRequiredFiles.join(", ") || "none"}`,
+  )
+  .join("\n")}
+`;
+
+  const paths = `# Fiyuu Paths
+
+Maps route folders to their fixed files.
+Auto-generated — run \`fiyuu sync\` to update.
+
+${graph.features
+  .map((feature) => {
+    const entries = Object.entries(feature.files)
+      .filter(([, value]) => Boolean(value))
+      .map(([name, value]) => `  - ${name}: ${value}`)
+      .join("\n");
+    return `## ${feature.route}\n- directory: ${feature.directory}\n${entries}`;
+  })
+  .join("\n\n")}
+`;
+
+  const states = `# Fiyuu States
+
+Current structural state snapshot for AI review.
+Auto-generated — run \`fiyuu sync\` to update.
+
+## Render Modes
+
+${graph.features.map((feature) => `- ${feature.route}: ${feature.render}`).join("\n")}
+
+## Intent State
+
+${graph.features.map((feature) => `- ${feature.route}: ${feature.intent ?? "MISSING"}`).join("\n")}
+
+## Schema Descriptions
+
+${graph.features.map((feature) => `- ${feature.route}: ${feature.descriptions.join(" | ") || "MISSING"}`).join("\n")}
+`;
+
+  const warnings = `# Fiyuu Warnings
+
+Auto-generated — run \`fiyuu sync\` to update.
+
+${
+  graph.features.some((feature) => feature.warnings.length > 0)
+    ? graph.features
+        .filter((feature) => feature.warnings.length > 0)
+        .map((feature) => `## ${feature.route}\n${feature.warnings.map((w) => `- ${w}`).join("\n")}`)
+        .join("\n\n")
+    : "No structural warnings detected.\n"
+}`;
+
+  const features = `# Fiyuu Features
+
+## Runtime Capabilities
+
+- route count: ${graph.routes.length}
+- action count: ${graph.actions.length}
+- query count: ${graph.queries.length}
+
+## Per-Route Capabilities
+
+${graph.features
+  .map(
+    (feature) =>
+      `- ${feature.route}:\n  render=${feature.render}, page=${Boolean(feature.files["page.tsx"])}, action=${Boolean(feature.files["action.ts"])}, query=${Boolean(feature.files["query.ts"])}`,
+  )
+  .join("\n")}
+`;
+
+  const skillsDoc =
+    skills.length === 0
+      ? `# Fiyuu Skills
+
+No skills found. Create one with \`fiyuu skill new <name>\`.
+
+Skills are project-aware scripts in the \`skills/\` directory.
+AI assistants can read and run them for automated project tasks.
+`
+      : `# Fiyuu Skills
+
+Skills are project-aware scripts AI assistants can read and execute.
+Run a skill: \`fiyuu skill run <name>\`
+
+## Available Skills
+
+${skills
+  .map(
+    (skill) =>
+      `### ${skill.name}\n- file: ${skill.filePath}\n- description: ${skill.description}\n- tags: ${skill.tags.join(", ") || "none"}`,
+  )
+  .join("\n\n")}
+`;
+
+  const execution = buildExecutionDoc(graph);
+  const interventions = buildInterventionsDoc();
+  const doctor = buildDoctorDoc();
+
+  return {
+    project: `${project.trim()}\n`,
+    paths: `${paths.trim()}\n`,
+    states: `${states.trim()}\n`,
+    features: `${features.trim()}\n`,
+    warnings: `${warnings.trim()}\n`,
+    skills: skillsDoc,
+    execution,
+    interventions,
+    doctor,
+  };
+}
+
+function buildExecutionDoc(graph: ProjectGraph): string {
+  const header = `# Fiyuu Execution Graph
+
+Shows the server-side execution chain for every route.
+Auto-generated — run \`fiyuu sync\` to update.
+
+Each request follows this deterministic order:
+  1. Middleware (if middleware.ts exists)
+  2. Query     (if query.ts exists) → fetches data, optional cache
+  3. Layout    (if layout.tsx exists) → wraps page content
+  4. Page      (page.tsx) → renders HTML
+  5. Document  → injects meta, client runtime, scripts
+  6. Response  → sent to browser
+
+`;
+
+  const routeSections = graph.features
+    .map((feature) => {
+      const steps: string[] = [];
+      const hasMiddleware = Boolean((feature.files as Record<string, string | undefined>)["middleware.ts"]);
+      const hasQuery = Boolean(feature.files["query.ts"]);
+      const hasLayout = Boolean((feature.files as Record<string, string | undefined>)["layout.tsx"]);
+      const hasPage = Boolean(feature.files["page.tsx"]);
+
+      if (hasMiddleware) steps.push(`  → middleware.ts        intercept / auth / headers`);
+      if (hasQuery) steps.push(`  → query.ts::execute()  fetch data → injected as page props`);
+      if (hasLayout) steps.push(`  → layout.tsx::template() wrap content`);
+      if (hasPage) steps.push(`  → page.tsx::Page()     render HTML  [${feature.render.toUpperCase()}]`);
+      steps.push(`  → renderDocument()     inject meta, runtime, scripts`);
+      steps.push(`  → HTTP 200 text/html`);
+
+      const flags: string[] = [];
+      if (feature.render === "ssg") flags.push("cached after first render");
+      if (feature.render === "csr") flags.push("body empty — client bundle renders");
+
+      return [
+        `## ${feature.route}`,
+        `- render: ${feature.render}`,
+        `- intent: ${feature.intent ?? "missing"}`,
+        flags.length > 0 ? `- notes: ${flags.join(", ")}` : null,
+        ``,
+        `\`\`\``,
+        `Request GET ${feature.route}`,
+        ...steps,
+        `\`\`\``,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    })
+    .join("\n\n");
+
+  return `${header}${routeSections}\n`;
+}
+
+function buildInterventionsDoc(): string {
+  return `# Fiyuu Interventions
+
+Safe framework interventions that can be applied automatically.
+
+## Supported via \`fiyuu doctor --fix\`
+
+- Replace \`className=\` with \`class=\` in route source files.
+- Add missing \`export async function execute()\` in \`action.ts\` and \`query.ts\`.
+- Create missing \`app/not-found.tsx\` and \`app/error.tsx\` fallback pages.
+- Add missing \`seo.title\` and \`seo.description\` fields in route \`meta.ts\`.
+
+## Not auto-fixed (manual review required)
+
+- \`dangerouslySetInnerHTML\` usage.
+- React imports or hook usage in GEA routes.
+- noJs violations where \`meta.ts\` sets \`noJs: true\` and page uses \`<script>\`.
+
+## SEO baseline
+
+- Use route-specific \`seo.title\`.
+- Keep \`seo.description\` around 12-28 words.
+`;
+}
+
+function buildDoctorDoc(): string {
+  return `# Fiyuu Doctor
+
+Command reference for deterministic checks and safe fixes.
+
+## Check only
+
+\`fiyuu doctor\`
+
+- Reports structure violations and quality warnings.
+
+## Check + safe fixes
+
+\`fiyuu doctor --fix\`
+
+- Applies only deterministic, low-risk fixes.
+- Prints each fixed item with \`(fixed)\` marker.
+
+## Typical workflow
+
+1. \`fiyuu sync\`
+2. \`fiyuu doctor --fix\`
+3. \`fiyuu doctor\`
+4. \`fiyuu build\`
+`;
+}

package/src/config.ts

@@ -0,0 +1,260 @@
+import { existsSync } from "node:fs";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export interface FiyuuConfig {
+  app?: {
+    name?: string;
+    runtime?: "node" | "bun";
+    port?: number;
+  };
+  ai?: {
+    enabled?: boolean;
+    skillsDirectory?: string;
+    defaultSkills?: string[];
+    graphContext?: boolean;
+    inspector?: {
+      enabled?: boolean;
+      localModelCommand?: string;
+      timeoutMs?: number;
+      autoSetupPrompt?: boolean;
+    };
+  };
+  fullstack?: {
+    client?: boolean;
+    serverActions?: boolean;
+    serverQueries?: boolean;
+    sockets?: boolean;
+  };
+  data?: {
+    driver?: string;
+    path?: string;
+    autosave?: boolean;
+    autosaveIntervalMs?: number;
+    tables?: string[];
+  };
+  security?: {
+    requestEncryption?: boolean;
+    serverSecretFile?: string;
+  };
+  websocket?: {
+    enabled?: boolean;
+    path?: string;
+    heartbeatMs?: number;
+    maxPayloadBytes?: number;
+  };
+  realtime?: {
+    enabled?: boolean;
+    transports?: ("websocket" | "nats")[];
+    websocket?: {
+      path?: string;
+      heartbeatMs?: number;
+      maxPayloadBytes?: number;
+    };
+    nats?: {
+      url?: string;
+      name?: string;
+    };
+  };
+  services?: {
+    enabled?: boolean;
+    directory?: string;
+    failFast?: boolean;
+  };
+  middleware?: {
+    enabled?: boolean;
+  };
+  developerTools?: {
+    enabled?: boolean;
+    renderTiming?: boolean;
+  };
+  observability?: {
+    requestId?: boolean;
+    warningsAsOverlay?: boolean;
+  };
+  auth?: {
+    enabled?: boolean;
+    sessionStrategy?: "cookie" | "token";
+  };
+  analytics?: {
+    enabled?: boolean;
+    provider?: string;
+  };
+  featureFlags?: {
+    enabled?: boolean;
+    defaults?: Record<string, boolean>;
+  };
+  errors?: {
+    /**
+     * Called for every unhandled server error.
+     * Use this to send errors to Sentry, Datadog, etc.
+     */
+    handler?: (error: Error, context: { route: string; method: string; requestId: string }) => void | Promise<void>;
+    /**
+     * Whether to expose error details (stack trace, message) in responses.
+     * Defaults to true in dev, false in production.
+     */
+    expose?: boolean;
+  };
+  deploy?: {
+    /**
+     * Enables `fiyuu deploy` workflow.
+     * If undefined, deploy command still works when `deploy.ssh` is configured.
+     */
+    enabled?: boolean;
+    /**
+     * Build locally before upload. Defaults to true.
+     */
+    localBuild?: boolean;
+    /**
+     * Extra archive exclude patterns for `tar`.
+     */
+    excludes?: string[];
+    ssh?: {
+      host: string;
+      user: string;
+      port?: number;
+      privateKeyPath?: string;
+      /**
+       * Absolute path on remote server (for example: /var/www/my-app)
+       */
+      destinationPath: string;
+      /**
+       * Number of old releases to keep on the server.
+       */
+      keepReleases?: number;
+    };
+    remote?: {
+      /**
+       * Command executed on remote server in release directory.
+       */
+      installCommand?: string;
+      /**
+       * Command executed on remote server after install.
+       */
+      buildCommand?: string;
+      /**
+       * Command executed on remote server to start/reload the app.
+       */
+      startCommand?: string;
+      /**
+       * Optional validation command after start.
+       */
+      healthcheckCommand?: string;
+    };
+    pm2?: {
+      enabled?: boolean;
+      /**
+       * Auto-generate ecosystem file in project root if missing.
+       */
+      autoCreate?: boolean;
+      ecosystemFile?: string;
+      appName?: string;
+      instances?: number | "max";
+      execMode?: "fork" | "cluster";
+      maxMemoryRestart?: string;
+      env?: Record<string, string>;
+    };
+  };
+  cloud?: {
+    /**
+     * Control-plane API endpoint for `fiyuu cloud`.
+     * Example: https://api.fiyuu.work
+     */
+    endpoint?: string;
+    /**
+     * Default project slug used by `fiyuu cloud deploy`.
+     */
+    project?: string;
+    /**
+     * Extra archive exclude patterns used by cloud deploy packaging.
+     */
+    excludes?: string[];
+  };
+  seo?: {
+    /**
+     * Base URL used in sitemap.xml and canonical links.
+     * Example: https://hacimertgokhan.me
+     */
+    baseUrl?: string;
+    /**
+     * Enable automatic sitemap.xml generation from scanned routes.
+     * Defaults to false.
+     */
+    sitemap?: boolean;
+    /**
+     * Enable automatic robots.txt generation.
+     * Defaults to false.
+     */
+    robots?: boolean;
+  };
+}
+
+export interface LoadedFiyuuConfig {
+  config: FiyuuConfig;
+  env: Record<string, string>;
+}
+
+export async function loadFiyuuConfig(rootDirectory: string, mode: "dev" | "start" = "dev"): Promise<LoadedFiyuuConfig> {
+  const env = await loadFiyuuEnvironment(rootDirectory, mode);
+  const configPath = path.join(rootDirectory, "fiyuu.config.ts");
+
+  if (!existsSync(configPath)) {
+    applyEnv(env);
+    return { config: {}, env };
+  }
+
+  const moduleUrl = pathToFileURL(configPath).href;
+  const loaded = await import(`${moduleUrl}?t=${Date.now()}`);
+  const config = ((loaded.default ?? loaded.config ?? {}) as FiyuuConfig) ?? {};
+  applyEnv(env);
+  return { config, env };
+}
+
+async function loadFiyuuEnvironment(rootDirectory: string, mode: "dev" | "start"): Promise<Record<string, string>> {
+  const directory = path.join(rootDirectory, ".fiyuu");
+  const files = [
+    path.join(directory, "env"),
+    path.join(directory, `${mode}.env`),
+    path.join(directory, "SECRET"),
+  ];
+  const env: Record<string, string> = {};
+
+  for (const filePath of files) {
+    if (!existsSync(filePath)) {
+      continue;
+    }
+
+    const name = path.basename(filePath);
+    if (name === "SECRET") {
+      env.FIYUU_SECRET = (await fs.readFile(filePath, "utf8")).trim();
+      continue;
+    }
+
+    const content = await fs.readFile(filePath, "utf8");
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) {
+        continue;
+      }
+      const separator = trimmed.indexOf("=");
+      if (separator <= 0) {
+        continue;
+      }
+      const key = trimmed.slice(0, separator).trim();
+      const value = trimmed.slice(separator + 1).trim();
+      env[key] = value;
+    }
+  }
+
+  return env;
+}
+
+function applyEnv(env: Record<string, string>): void {
+  for (const [key, value] of Object.entries(env)) {
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}