backeneko 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 backeneko contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# backeneko
+```text
+   /\_/\
+  ( =.= ) ( (
+  /    \  / /
+ (_|__|_)/_/
+```
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+
+Mock GraphQL backend generated from `.graphql` schema files, with hot reload.
+
+## Requirements
+
+Bun >= 1.1 — backeneko runs on Bun (`Bun.serve`, `Bun.build`, recursive
+`fs.watch`).
+
+## Install
+
+```bash
+bun add -g backeneko   # or: npm i -g backeneko
+```
+
+## Quick start
+
+```bash
+backeneko --source=./schemas --port=4000
+```
+
+`--source` is scanned recursively for `*.graphql` / `*.gql`. Open
+<http://localhost:4000/> for a minimal query inspector, or POST to `/graphql`:
+
+```bash
+curl -s http://localhost:4000/graphql \
+  -H 'content-type: application/json' \
+  -d '{"query":"{ users { id name role } }"}'
+```
+
+## How it works
+
+On the first run backeneko scans `--source`, merges the files into one schema
+and creates a workspace:
+
+```
+.backeneko/
+├── schema.graphql              # merged schema (rewritten each start)
+├── tsconfig.json               # @<kind>/* aliases: override → generated
+├── generated/                  # disposable mirror, rewritten each start
+│   ├── entities/
+│   │   ├── User.ts             # mock entity (default export)
+│   │   └── Post.ts
+│   ├── queries/
+│   │   ├── users.ts            # one file per Query field: (parent, args, ...) => value
+│   │   └── user.ts
+│   └── mutations/
+│       └── createUser.ts
+├── override/                   # your files win; never written by backeneko
+│   └── entities/User.ts        # shadows generated/entities/User.ts
+└── cache/                      # bundled mock modules (per content hash)
+```
+
+- Every root field gets its own TS file exporting a resolver function.
+- Every entity type gets a file exporting a `default` mock value.
+- `generated/` is disposable: with `--source` it is rewritten on every start
+  (added/removed fields and types are synced) and files you edited there are
+  overwritten.
+- Put lasting changes in `override/` with the same path — an override file
+  always shadows the generated one and is never written or removed. For
+  example, create `override/entities/User.ts` to replace the generated
+  `generated/entities/User.ts`.
+- Relations are imported through `@entities/...`, which resolves override-first,
+  so a generated entity picks up your overridden related entity automatically.
+- Edit any mock file — the backend reloads automatically.
+- Entity named exports matching a field name override that field's resolver.
+
+Without `--source`, an existing `.backeneko` is served as-is.
+
+## Mock directives
+
+Pin an entity field's generated value straight from the schema with
+`@backeneko(value: "...")` or its alias `@mock(value: "...")`:
+
+```graphql
+type Product {
+  id: ID!
+  title: String @backeneko(value: "Pinned Title")
+  price: Int @mock(value: "199")
+  inStock: Boolean @backeneko(value: "true")
+}
+```
+
+- No need to declare the directive — backeneko provides it on its own.
+- The value is a string and is cast to the field's type where possible:
+  `Int`/`Float` → number, `Boolean` → boolean, `String`/`ID`/enum/custom
+  scalars → string. An uncastable value is ignored with a warning and the type
+  default is kept.
+- Only single scalar/enum fields are supported. On list or object/interface/
+  union fields the directive is ignored with a warning.
+- Generated values are only defaults: an `override/<kind>/<name>.ts` file still
+  replaces them entirely.
+
+## CLI
+
+```
+backeneko --source=<dir> [--port=4000] [--dir=.backeneko] [--no-validate]
+```
+
+- `--source=<dir>` — directory with schema files (recursive).
+- `--port=<n>` — HTTP port (default `4000`).
+- `--dir=<dir>` — workspace directory (default `.backeneko`).
+- `--no-validate` — skip validating incoming queries against the schema.
+
+## Development
+
+```bash
+bun install
+bun run demo        # run against examples/source on :4000
+bun run typecheck
+bun test
+```
+
+## Publishing
+
+Releases are published to npm by the [Publish](.github/workflows/publish.yml)
+GitHub Actions workflow. To cut a release:
+
+1. Bump `version` in `package.json` and commit it.
+2. Push a matching tag: `git tag v0.1.0 && git push origin v0.1.0`.
+
+The workflow runs typecheck + tests and publishes with provenance. It needs:
+
+- an `NPM_TOKEN` repository secret (an npm automation token with publish rights);
+- a `repository` field in `package.json` pointing at the public GitHub repo
+  (required by npm provenance) — the `repository` field already points at
+  `iliyat/backeneko`.
+
+See `AGENTS.md` for contributor guidance.

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "backeneko",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Mock GraphQL backend generated from .graphql schema files, with hot reload",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iliyat/backeneko.git"
+  },
+  "homepage": "https://github.com/iliyat/backeneko#readme",
+  "bugs": {
+    "url": "https://github.com/iliyat/backeneko/issues"
+  },
+  "bin": {
+    "backeneko": "./src/cli.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "packageManager": "bun@1.3.14",
+  "keywords": [
+    "graphql",
+    "mock",
+    "schema",
+    "bun",
+    "backend",
+    "hot-reload",
+    "sdl"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun run src/cli.ts",
+    "demo": "bun run src/cli.ts --source=examples/source --port=4000",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck && bun test"
+  },
+  "dependencies": {
+    "graphql": "^16.11.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.4",
+    "typescript": "^5.9.3"
+  }
+}

package/src/args.ts

@@ -0,0 +1,64 @@
+import { parseArgs } from "node:util";
+
+export interface CliOptions {
+  source: string | null;
+  port: number;
+  dir: string;
+  validate: boolean;
+  help: boolean;
+}
+
+export const DEFAULT_PORT = 4000;
+export const DEFAULT_WORKSPACE_DIR = ".backeneko";
+
+export function parseCliArgs(argv: string[] = process.argv.slice(2)): CliOptions {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      source: { type: "string" },
+      port: { type: "string" },
+      dir: { type: "string" },
+      "no-validate": { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+
+  const port = values.port === undefined ? DEFAULT_PORT : Number(values.port);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`invalid --port value: ${values.port}`);
+  }
+
+  return {
+    source: values.source ?? null,
+    port,
+    dir: values.dir ?? DEFAULT_WORKSPACE_DIR,
+    validate: !(values["no-validate"] ?? false),
+    help: values.help ?? false,
+  };
+}
+
+export function printHelp(): void {
+  console.log(`backeneko — mock GraphQL backend generated from .graphql schema files
+
+Usage:
+  backeneko [--source=<schema-directory>] [options]
+
+Options:
+  --source=<dir>   Directory with .graphql/.gql schema files. Regenerates the
+                   workspace: overwrites schema.graphql and everything under
+                   generated/, leaves override/ alone. Omit to serve <dir> as-is.
+  --port=<n>       HTTP port (default: ${DEFAULT_PORT})
+  --dir=<dir>      Workspace directory (default: ${DEFAULT_WORKSPACE_DIR})
+  --no-validate    Skip validating queries against the schema (default: validate)
+  -h, --help       Show this help
+
+Behavior:
+  * with --source: schema.graphql and generated/ are rewritten on every start,
+    including files whose type or field disappeared from the schema
+  * override/entities|queries|mutations|subscriptions/<name>.ts wins over
+    generated/<same path>; overrides are loaded, never written or removed
+  * without --source: an existing <dir> is served unchanged
+  * mock files and schema hot-reload on change`);
+}

package/src/cli.ts

@@ -0,0 +1,199 @@
+#!/usr/bin/env bun
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseCliArgs, printHelp } from "./args.ts";
+import { collectSchemaFiles } from "./collect.ts";
+import { compileDocument } from "./compile.ts";
+import {
+  GENERATED_DIR,
+  OVERRIDE_DIR,
+  ensureWorkspaceTsconfig,
+  generateWorkspace,
+} from "./generate.ts";
+import { mergeSchemaDocuments, renderSdl } from "./merge.ts";
+import { loadMockModules } from "./mocks.ts";
+import { buildExecutableSchema } from "./resolvers.ts";
+import { runtime } from "./runtime.ts";
+import { startServer } from "./server.ts";
+import { watchWorkspace } from "./watch.ts";
+
+function colorEnabled(stream: { isTTY?: boolean }): boolean {
+  if (process.env.NO_COLOR) return false;
+  const force = process.env.FORCE_COLOR;
+  if (force !== undefined && force !== "" && force !== "0") return true;
+  return Boolean(stream.isTTY);
+}
+
+function paint(stream: { isTTY?: boolean }, code: string, text: string): string {
+  return colorEnabled(stream) ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+
+function log(message: string): void {
+  console.log(`[backeneko] ${message}`);
+}
+
+function warn(message: string): void {
+  console.warn(paint(process.stderr, "1;33", `[backeneko] warning: ${message}`));
+}
+
+function logError(message: string): void {
+  console.error(paint(process.stderr, "1;31", `[backeneko] error: ${message}`));
+}
+
+function fail(message: string): never {
+  console.error(paint(process.stderr, "1;31", `[backeneko] error: ${message}`));
+  process.exit(1);
+}
+
+const LOGO = [
+  "   /\\_/\\",
+  "  ( =.= ) ( (",
+  "  /    \\  / /",
+  " (_|__|_)/_/",
+].join("\n");
+
+function printLogo(): void {
+  console.log(paint(process.stdout, "36", LOGO));
+  console.log("");
+}
+
+async function main(): Promise<void> {
+  printLogo();
+
+  const options = parseCliArgs();
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const cwd = process.cwd();
+  const targetDir = path.resolve(cwd, options.dir);
+  const schemaPath = path.join(targetDir, "schema.graphql");
+
+  if (options.source) {
+    await generateFromSource(path.resolve(cwd, options.source), targetDir);
+  } else if (!existsSync(targetDir)) {
+    printHelp();
+    fail(`--source is required when ${options.dir} does not exist`);
+  } else {
+    log(`serving existing ${options.dir} as-is (no --source, schema not regenerated)`);
+    await ensureWorkspaceTsconfig(targetDir);
+  }
+
+  if (!existsSync(schemaPath)) {
+    fail(`no schema found at ${path.relative(cwd, schemaPath)}`);
+  }
+
+  await loadSchema(schemaPath);
+  runtime.modules = await loadMockModules(targetDir);
+  await logSummary(targetDir);
+
+  const server = startServer(options.port, { validate: options.validate });
+  log(`mock GraphQL backend on http://localhost:${server.port}/graphql`);
+  if (!options.validate) warn("query validation disabled");
+  log(`hot reload watching ${path.relative(cwd, targetDir)}`);
+
+  watchWorkspace(targetDir, async (changed) => {
+    const rel = changed.map((file) => path.relative(cwd, path.join(targetDir, file))).join(", ");
+    if (changed.some((file) => path.basename(file) === "schema.graphql")) {
+      try {
+        await loadSchema(schemaPath);
+        log(`schema reloaded (${rel})`);
+      } catch (error) {
+        console.error(
+          paint(
+            process.stderr,
+            "1;31",
+            `[backeneko] schema reload failed: ${error instanceof Error ? error.message : error}`,
+          ),
+        );
+      }
+    }
+    const previous = runtime.modules;
+    runtime.modules = await loadMockModules(targetDir, previous);
+    log(`mocks reloaded (${rel})`);
+  });
+
+  process.on("SIGINT", () => {
+    server.stop();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    server.stop();
+    process.exit(0);
+  });
+}
+
+async function generateFromSource(sourceDir: string, targetDir: string): Promise<void> {
+  if (!existsSync(sourceDir)) {
+    fail(`source directory not found: ${sourceDir}`);
+  }
+
+  const files = await collectSchemaFiles(sourceDir);
+  if (files.length === 0) {
+    fail(`no .graphql/.gql files found in ${sourceDir}`);
+  }
+
+  const merged = mergeSchemaDocuments(files);
+  for (const error of merged.errors) logError(error);
+  if (merged.skippedExecutables.length > 0) {
+    log(`ignored ${merged.skippedExecutables.length} executable definition(s) (queries/fragments are not part of the schema)`);
+    for (const entry of merged.skippedExecutables) warn(`skipped ${entry}`);
+  }
+
+  const compiled = compileDocument(merged.document);
+  for (const entry of compiled.skipped) warn(`skipped "${entry.name}": ${entry.reason}`);
+  for (const warning of compiled.warnings) warn(warning);
+
+  const sdl = renderSdl(
+    compiled.document,
+    files.map((file) => file.relativePath),
+    compiled.skipped,
+  );
+  const result = await generateWorkspace({ targetDir, sdl });
+
+  for (const warning of result.warnings) warn(warning);
+  log(`collected ${files.length} schema file(s) from ${sourceDir}`);
+  log(`generated ${path.basename(result.schemaPath)}`);
+  log(
+    `${GENERATED_DIR}/: ${result.created.length} created, ${result.updated.length} updated, ` +
+      `${result.unchanged.length} unchanged, ${result.removed.length} removed`,
+  );
+  if (result.removed.length > 0) log(`pruned ${result.removed.join(", ")}`);
+  log(`${OVERRIDE_DIR}/ is never written`);
+}
+
+async function logSummary(targetDir: string): Promise<void> {
+  const { entities, root } = runtime.modules;
+  const parts = [`${entities.size} entit${entities.size === 1 ? "y" : "ies"}`];
+  for (const [typeName, resolvers] of root) {
+    parts.push(`${resolvers.size} ${typeName.toLowerCase()} resolver(s)`);
+  }
+  log(`loaded ${parts.join(", ")} from ${path.relative(process.cwd(), targetDir)}`);
+
+  const overrides = await countFiles(path.join(targetDir, OVERRIDE_DIR));
+  if (overrides > 0) {
+    log(`${overrides} override file(s) in ${path.relative(process.cwd(), path.join(targetDir, OVERRIDE_DIR))}`);
+  }
+}
+
+async function countFiles(directory: string): Promise<number> {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+  let count = 0;
+  for (const entry of entries) {
+    if (entry.isDirectory()) count += await countFiles(path.join(directory, entry.name));
+    else count += 1;
+  }
+  return count;
+}
+
+async function loadSchema(schemaPath: string): Promise<void> {
+  const sdl = await readFile(schemaPath, "utf8");
+  runtime.schema = buildExecutableSchema(sdl);
+}
+
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+});

package/src/collect.ts

@@ -0,0 +1,38 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+const SCHEMA_EXTENSIONS = new Set([".graphql", ".gql"]);
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", "dist"]);
+
+export interface SchemaSourceFile {
+  absolutePath: string;
+  relativePath: string;
+  content: string;
+}
+
+export async function collectSchemaFiles(root: string): Promise<SchemaSourceFile[]> {
+  const files: SchemaSourceFile[] = [];
+
+  async function walk(dir: string, prefix: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const relative = prefix + entry.name;
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith(".") || IGNORED_DIRECTORIES.has(entry.name)) continue;
+        await walk(path.join(dir, entry.name), relative + "/");
+        continue;
+      }
+      if (!entry.isFile() || !SCHEMA_EXTENSIONS.has(path.extname(entry.name))) continue;
+      const absolutePath = path.join(dir, entry.name);
+      files.push({
+        absolutePath,
+        relativePath: relative,
+        content: await readFile(absolutePath, "utf8"),
+      });
+    }
+  }
+
+  await walk(root, "");
+  return files;
+}