@gqlkit-ts/cli 0.1.0 → 0.3.0

package/src/commands/docs.ts

@@ -0,0 +1,211 @@
+import { access, mkdir, readFile, symlink, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { define } from "gunshi";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_DOCS_DIR = join(__dirname, "../../docs");
+const SKILL_NAME = "gqlkit-guide";
+
+export interface RunDocsCommandOptions {
+  readonly output: string;
+  readonly claude: boolean;
+  readonly codex: boolean;
+}
+
+export interface RunDocsCommandResult {
+  readonly exitCode: number;
+  readonly filesWritten: string[];
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function detectClaudeEnvironment(dir: string): Promise<boolean> {
+  const claudeMdExists = await exists(join(dir, "CLAUDE.md"));
+  const claudeDirExists = await exists(join(dir, ".claude"));
+  return claudeMdExists || claudeDirExists;
+}
+
+async function detectCodexEnvironment(dir: string): Promise<boolean> {
+  const agentsMdExists = await exists(join(dir, "AGENTS.md"));
+  const codexDirExists = await exists(join(dir, ".codex"));
+  return agentsMdExists || codexDirExists;
+}
+
+function generateSkillMd(): string {
+  return `---
+name: ${SKILL_NAME}
+description: Use when the user asks about "gqlkit", "gqlkit usage", "gqlkit schema definition", "gqlkit configuration", "gqlkit resolvers", "GraphQL code generation with gqlkit", or needs guidance on gqlkit conventions, type definitions, or integration with GraphQL servers or ORMs.
+---
+
+# gqlkit Guide
+
+gqlkit generates GraphQL schema and resolver maps from TypeScript types and functions.
+
+## How it works
+
+1. Write TypeScript types in \`src/gqlkit/schema/\` → become GraphQL types
+2. Write resolver functions using \`defineQuery\`, \`defineMutation\`, \`defineField\` → become GraphQL resolvers
+3. Run \`gqlkit gen\` → outputs \`typeDefs\` and \`resolvers\` to \`src/gqlkit/__generated__/\`
+
+## Design principles
+
+- **Implement first**: Write types and resolvers, generate schema when ready. No edit-regenerate-implement loops.
+- **Just types and functions**: Plain TypeScript with a thin API. No decorators, no complex generics.
+- **Type-safe**: TypeScript types become GraphQL types. Resolver signatures checked at compile time.
+
+## How to Use This Skill
+
+Read [references/index.md](references/index.md) first. It contains the complete documentation index with all available topics.
+
+Navigate to specific documentation files based on user needs as indicated in the index.
+`;
+}
+
+function generateRules(): string {
+  return `## gqlkit
+
+When working with GraphQL schema, types, or resolvers using gqlkit, use the \`${SKILL_NAME}\` skill.
+`;
+}
+
+async function createSymlinkIfNotExists(
+  linkPath: string,
+  target: string,
+): Promise<void> {
+  try {
+    await symlink(target, linkPath, "dir");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+  }
+}
+
+async function appendOrCreateFile(
+  filePath: string,
+  content: string,
+): Promise<void> {
+  try {
+    const existing = await readFile(filePath, "utf-8");
+    if (!existing.includes("## gqlkit")) {
+      await writeFile(filePath, `${existing}\n${content}`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      await writeFile(filePath, content);
+    } else {
+      throw error;
+    }
+  }
+}
+
+interface AiToolConfig {
+  readonly configDir: string;
+  readonly rulesFile: string;
+}
+
+async function generateToolFiles(
+  outputDir: string,
+  config: AiToolConfig,
+  filesWritten: string[],
+): Promise<void> {
+  const skillDir = join(outputDir, `${config.configDir}/skills/${SKILL_NAME}`);
+  await mkdir(skillDir, { recursive: true });
+
+  const skillMdPath = join(skillDir, "SKILL.md");
+  await writeFile(skillMdPath, generateSkillMd());
+  filesWritten.push(skillMdPath);
+
+  const referencesPath = join(skillDir, "references");
+  const relativePath = relative(skillDir, CLI_DOCS_DIR);
+  await createSymlinkIfNotExists(referencesPath, relativePath);
+  filesWritten.push(referencesPath);
+
+  const rulesPath = join(outputDir, config.rulesFile);
+  await appendOrCreateFile(rulesPath, generateRules());
+  filesWritten.push(rulesPath);
+}
+
+export async function runDocsCommand(
+  options: RunDocsCommandOptions,
+): Promise<RunDocsCommandResult> {
+  if (!(await exists(CLI_DOCS_DIR))) {
+    console.error(
+      `Documentation directory not found: ${CLI_DOCS_DIR}\nRun "pnpm build" to generate documentation files.`,
+    );
+    return { exitCode: 1, filesWritten: [] };
+  }
+
+  const filesWritten: string[] = [];
+
+  const autoDetect = !options.claude && !options.codex;
+  const generateClaude =
+    options.claude ||
+    (autoDetect && (await detectClaudeEnvironment(options.output)));
+  const generateCodex =
+    options.codex ||
+    (autoDetect && (await detectCodexEnvironment(options.output)));
+
+  if (!generateClaude && !generateCodex) {
+    console.log(
+      "No AI tool environment detected. Use --claude or --codex to generate explicitly.",
+    );
+    return { exitCode: 0, filesWritten: [] };
+  }
+
+  if (generateClaude) {
+    await generateToolFiles(
+      options.output,
+      { configDir: ".claude", rulesFile: "CLAUDE.md" },
+      filesWritten,
+    );
+  }
+
+  if (generateCodex) {
+    await generateToolFiles(
+      options.output,
+      { configDir: ".codex", rulesFile: "AGENTS.md" },
+      filesWritten,
+    );
+  }
+
+  return { exitCode: 0, filesWritten };
+}
+
+export const docsCommand = define({
+  name: "docs",
+  args: {
+    output: {
+      type: "string",
+      description: "Output directory for generated files",
+    },
+    claude: {
+      type: "boolean",
+      description: `Generate Claude Code files (.claude/skills/${SKILL_NAME}/, CLAUDE.md)`,
+    },
+    codex: {
+      type: "boolean",
+      description: `Generate Codex files (.codex/skills/${SKILL_NAME}/, AGENTS.md)`,
+    },
+  },
+  run: async (ctx) => {
+    const output = ctx.values.output ?? process.cwd();
+    const claude = ctx.values.claude ?? false;
+    const codex = ctx.values.codex ?? false;
+    const result = await runDocsCommand({ output, claude, codex });
+    for (const file of result.filesWritten) {
+      console.log(`Generated: ${file}`);
+    }
+    if (result.exitCode !== 0) {
+      process.exitCode = result.exitCode;
+    }
+  },
+});

package/src/commands/gen.ts

@@ -0,0 +1,141 @@
+import { dirname } from "node:path";
+import { define } from "gunshi";
+import { loadConfig } from "../config-loader/index.js";
+import { executeHooks } from "../gen-orchestrator/hook-executor/hook-executor.js";
+import {
+  executeGeneration,
+  type GenerationConfig,
+  writeGeneratedFiles,
+} from "../gen-orchestrator/orchestrator.js";
+import { createDiagnosticReporter } from "../gen-orchestrator/reporter/diagnostic-reporter.js";
+import { createProgressReporter } from "../gen-orchestrator/reporter/progress-reporter.js";
+
+export interface RunGenCommandOptions {
+  readonly cwd: string;
+}
+
+export interface RunGenCommandResult {
+  readonly exitCode: number;
+}
+
+export async function runGenCommand(
+  options: RunGenCommandOptions,
+): Promise<RunGenCommandResult> {
+  const writer = {
+    stdout: (msg: string) => console.log(msg),
+    stderr: (msg: string) => console.error(msg),
+  };
+
+  const progressReporter = createProgressReporter(writer);
+  const diagnosticReporter = createDiagnosticReporter(writer);
+
+  const configResult = await loadConfig({ cwd: options.cwd });
+
+  if (configResult.diagnostics.length > 0) {
+    diagnosticReporter.reportDiagnostics(configResult.diagnostics);
+    diagnosticReporter.reportError("Config load failed");
+    return { exitCode: 1 };
+  }
+
+  const configDir = configResult.configPath
+    ? dirname(configResult.configPath)
+    : options.cwd;
+
+  const { sourceDir, sourceIgnoreGlobs, output, scalars, tsconfigPath } =
+    configResult.config;
+
+  const config: GenerationConfig = {
+    cwd: options.cwd,
+    sourceDir,
+    sourceIgnoreGlobs,
+    output,
+    configDir,
+    customScalars: scalars,
+    tsconfigPath,
+  };
+
+  progressReporter.startPhase("Extracting types");
+  progressReporter.startPhase("Extracting resolvers");
+  progressReporter.startPhase("Generating schema");
+
+  const result = await executeGeneration(config);
+
+  if (result.diagnostics.length > 0) {
+    diagnosticReporter.reportDiagnostics(result.diagnostics);
+  }
+
+  if (!result.success) {
+    diagnosticReporter.reportError("Generation failed");
+    return { exitCode: 1 };
+  }
+
+  const writeResult = await writeGeneratedFiles({
+    files: result.files,
+  });
+
+  if (!writeResult.success) {
+    diagnosticReporter.reportError("Failed to write output files");
+    return { exitCode: 1 };
+  }
+
+  for (const filePath of writeResult.filesWritten) {
+    progressReporter.fileWritten(filePath);
+  }
+  progressReporter.complete();
+
+  const { hooks } = configResult.config;
+  let hookFailed = false;
+
+  if (
+    writeResult.filesWritten.length > 0 &&
+    hooks.afterAllFileWrite.length > 0
+  ) {
+    progressReporter.startHookPhase();
+
+    const hookResult = await executeHooks({
+      commands: hooks.afterAllFileWrite,
+      filePaths: writeResult.filesWritten,
+      cwd: options.cwd,
+      onHookComplete: (result) => {
+        if (result.success) {
+          progressReporter.hookCompleted(result.command);
+        } else {
+          progressReporter.hookFailed(
+            result.command,
+            result.exitCode,
+            result.stderr,
+          );
+        }
+      },
+    });
+
+    hookFailed = !hookResult.success;
+    const failedCount = hookResult.results.filter((r) => !r.success).length;
+    progressReporter.hookPhaseSummary(hookResult.results.length, failedCount);
+  }
+
+  if (hookFailed) {
+    diagnosticReporter.reportError("Hook execution failed");
+    return { exitCode: 1 };
+  }
+
+  diagnosticReporter.reportSuccess("Generation complete!");
+  return { exitCode: 0 };
+}
+
+export const genCommand = define({
+  name: "gen",
+  args: {
+    cwd: {
+      type: "string",
+      description: "Working directory for code generation",
+    },
+  },
+  run: async (ctx) => {
+    const cwd = ctx.values.cwd ?? process.cwd();
+    const result = await runGenCommand({ cwd });
+    if (result.exitCode !== 0) {
+      process.exitCode = result.exitCode;
+    }
+  },
+});

package/src/commands/main.ts

@@ -0,0 +1,5 @@
+import { define } from "gunshi";
+
+export const mainCommand = define({
+  name: "gqlkit",
+});

package/src/config/define-config.ts

@@ -0,0 +1,28 @@
+import type { GqlkitConfig } from "./types.js";
+
+/**
+ * 型安全な設定オブジェクトを作成するヘルパー関数。
+ * IDE での型補完とコンパイル時の型チェックを提供する。
+ *
+ * @example
+ * ```typescript
+ * // gqlkit.config.ts
+ * import { defineConfig } from "@gqlkit-ts/cli";
+ *
+ * export default defineConfig({
+ *   scalars: [
+ *     {
+ *       graphqlName: "DateTime",
+ *       type: { from: "./src/types/scalars", name: "DateTime" },
+ *     },
+ *     {
+ *       graphqlName: "UUID",
+ *       type: { from: "./src/types/scalars", name: "UUID" },
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export function defineConfig(config: GqlkitConfig): GqlkitConfig {
+  return config;
+}

package/src/config/index.ts

@@ -0,0 +1,7 @@
+export { defineConfig } from "./define-config.js";
+export type {
+  GqlkitConfig,
+  HooksConfig,
+  OutputConfig,
+  ScalarMappingConfig,
+} from "./types.js";

package/src/config/types.ts

@@ -0,0 +1,144 @@
+/**
+ * Output configuration for generated files.
+ * All paths are relative to project root.
+ */
+export interface OutputConfig {
+  /**
+   * Output path for resolver map file.
+   * - If relative, resolved from project root
+   * - If null, suppresses resolvers output
+   * - If undefined, uses default path
+   * @default "src/gqlkit/__generated__/resolvers.ts"
+   */
+  readonly resolversPath?: string | null;
+
+  /**
+   * Output path for GraphQL schema AST (DocumentNode).
+   * - If relative, resolved from project root
+   * - If null, suppresses AST output
+   * - If undefined, uses default path
+   * @default "src/gqlkit/__generated__/typeDefs.ts"
+   */
+  readonly typeDefsPath?: string | null;
+
+  /**
+   * Output path for GraphQL schema SDL.
+   * - If relative, resolved from project root
+   * - If null, suppresses SDL output
+   * - If undefined, uses default path
+   * @default "src/gqlkit/__generated__/schema.graphql"
+   */
+  readonly schemaPath?: string | null;
+}
+
+/**
+ * Hook configuration for lifecycle events.
+ */
+export interface HooksConfig {
+  /**
+   * Commands to execute after all files are written.
+   * Each command receives all written file paths as arguments.
+   * Commands are executed sequentially in order.
+   */
+  readonly afterAllFileWrite?: string | ReadonlyArray<string>;
+}
+
+/**
+ * Type definition for gqlkit configuration file.
+ * Used in `gqlkit.config.ts`.
+ */
+export interface GqlkitConfig {
+  /**
+   * Source directory to scan for types and resolvers.
+   * All TypeScript files (.ts, .cts, .mts) under this directory will be scanned.
+   * @default "src/gqlkit/schema"
+   */
+  readonly sourceDir?: string;
+
+  /**
+   * Glob patterns to exclude from source scanning.
+   * Patterns are matched against file paths relative to sourceDir.
+   * @default []
+   */
+  readonly sourceIgnoreGlobs?: ReadonlyArray<string>;
+
+  /**
+   * Output configuration for generated files.
+   */
+  readonly output?: OutputConfig;
+
+  /**
+   * Custom scalar mapping definitions.
+   * Configures the mapping between TypeScript types and GraphQL scalars.
+   */
+  readonly scalars?: ReadonlyArray<ScalarMappingConfig>;
+
+  /**
+   * Path to TypeScript configuration file.
+   * - If relative, resolved from config file
+   * - Absolute paths are also supported
+   * - If unspecified, automatically searches for tsconfig.json in project root
+   */
+  readonly tsconfigPath?: string;
+
+  /**
+   * Hook configuration for lifecycle events.
+   */
+  readonly hooks?: HooksConfig;
+}
+
+/**
+ * Custom scalar mapping configuration.
+ * Maps TypeScript types to GraphQL scalar types.
+ *
+ * @example
+ * // Global type (e.g., Date)
+ * { name: "DateTime", tsType: { name: "Date" } }
+ *
+ * // Module type
+ * { name: "DateTime", tsType: { name: "DateTimeString", from: "./src/types" } }
+ *
+ * // With usage constraint
+ * { name: "DateTime", tsType: { name: "Date" }, only: "input" }
+ *
+ * // With description
+ * { name: "DateTime", tsType: { name: "Date" }, description: "ISO 8601 format" }
+ */
+export interface ScalarMappingConfig {
+  /**
+   * GraphQL scalar name.
+   * Example: "DateTime", "UUID", "URL"
+   */
+  readonly name: string;
+
+  /**
+   * TypeScript type information to map.
+   */
+  readonly tsType: {
+    /**
+     * TypeScript type name.
+     * Example: "Date", "DateTime", "UUID"
+     */
+    readonly name: string;
+
+    /**
+     * Import path for the type. If omitted, treated as a global type.
+     * Example: "./src/types/scalars", "@my-lib/scalars"
+     */
+    readonly from?: string;
+  };
+
+  /**
+   * Usage constraint for the scalar type.
+   * - "input": Only use this type for input positions (arguments, input type fields)
+   * - "output": Only use this type for output positions (return types, object type fields)
+   * - undefined: Use for both input and output positions
+   */
+  readonly only?: "input" | "output";
+
+  /**
+   * Description for the scalar type.
+   * Will be included in the generated GraphQL schema.
+   */
+  readonly description?: string;
+}

package/src/config-loader/index.ts

@@ -0,0 +1,14 @@
+export {
+  type LoadConfigOptions,
+  type LoadConfigResult,
+  loadConfig,
+  type ResolvedConfig,
+  type ResolvedHooksConfig,
+  type ResolvedOutputConfig,
+  type ResolvedScalarMapping,
+} from "./loader.js";
+
+export type {
+  ValidateConfigOptions,
+  ValidateConfigResult,
+} from "./validator.js";

package/src/config-loader/loader.ts

@@ -0,0 +1,143 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createJiti } from "jiti";
+import type { Diagnostic } from "../type-extractor/types/index.js";
+import { validateConfig } from "./validator.js";
+
+export interface LoadConfigOptions {
+  readonly cwd: string;
+}
+
+export interface ResolvedScalarMapping {
+  readonly graphqlName: string;
+  readonly typeName: string;
+  readonly importPath: string | null;
+  readonly only: "input" | "output" | null;
+  readonly description: string | null;
+}
+
+/**
+ * Resolved output configuration.
+ * Undefined values are resolved to defaults.
+ */
+export interface ResolvedOutputConfig {
+  /** Resolver map output path. Null suppresses output */
+  readonly resolversPath: string | null;
+  /** Schema AST (typeDefs) output path. Null suppresses output */
+  readonly typeDefsPath: string | null;
+  /** Schema SDL output path. Null suppresses output */
+  readonly schemaPath: string | null;
+}
+
+/**
+ * Resolved hook configuration.
+ * Commands are normalized to array format.
+ */
+export interface ResolvedHooksConfig {
+  /** Normalized to array (empty if not configured) */
+  readonly afterAllFileWrite: ReadonlyArray<string>;
+}
+
+export interface ResolvedConfig {
+  readonly sourceDir: string;
+  readonly sourceIgnoreGlobs: ReadonlyArray<string>;
+  readonly output: ResolvedOutputConfig;
+  readonly scalars: ReadonlyArray<ResolvedScalarMapping>;
+  readonly tsconfigPath: string | null;
+  readonly hooks: ResolvedHooksConfig;
+}
+
+export interface LoadConfigResult {
+  readonly config: ResolvedConfig;
+  readonly configPath: string | undefined;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+const CONFIG_FILE_NAME = "gqlkit.config.ts";
+
+export const DEFAULT_SOURCE_DIR = "src/gqlkit/schema";
+export const DEFAULT_RESOLVERS_PATH = "src/gqlkit/__generated__/resolvers.ts";
+export const DEFAULT_TYPEDEFS_PATH = "src/gqlkit/__generated__/typeDefs.ts";
+export const DEFAULT_SCHEMA_PATH = "src/gqlkit/__generated__/schema.graphql";
+
+const DEFAULT_OUTPUT_CONFIG: ResolvedOutputConfig = {
+  resolversPath: DEFAULT_RESOLVERS_PATH,
+  typeDefsPath: DEFAULT_TYPEDEFS_PATH,
+  schemaPath: DEFAULT_SCHEMA_PATH,
+};
+
+const DEFAULT_HOOKS_CONFIG: ResolvedHooksConfig = {
+  afterAllFileWrite: [],
+};
+
+const DEFAULT_RESOLVED_CONFIG: ResolvedConfig = {
+  sourceDir: DEFAULT_SOURCE_DIR,
+  sourceIgnoreGlobs: [],
+  output: DEFAULT_OUTPUT_CONFIG,
+  scalars: [],
+  tsconfigPath: null,
+  hooks: DEFAULT_HOOKS_CONFIG,
+};
+
+export async function loadConfig(
+  options: LoadConfigOptions,
+): Promise<LoadConfigResult> {
+  const configPath = join(options.cwd, CONFIG_FILE_NAME);
+
+  if (!existsSync(configPath)) {
+    return {
+      config: DEFAULT_RESOLVED_CONFIG,
+      configPath: undefined,
+      diagnostics: [],
+    };
+  }
+
+  const jiti = createJiti(options.cwd, {
+    interopDefault: true,
+  });
+
+  try {
+    const loadedModule = await jiti.import(configPath);
+    const rawConfig =
+      (loadedModule as { default?: unknown }).default ?? loadedModule;
+
+    const validationResult = validateConfig({
+      config: rawConfig,
+      configPath,
+    });
+
+    if (!validationResult.valid || !validationResult.resolvedConfig) {
+      return {
+        config: DEFAULT_RESOLVED_CONFIG,
+        configPath,
+        diagnostics: validationResult.diagnostics,
+      };
+    }
+
+    return {
+      config: validationResult.resolvedConfig,
+      configPath,
+      diagnostics: [],
+    };
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Unknown error occurred";
+
+    return {
+      config: DEFAULT_RESOLVED_CONFIG,
+      configPath,
+      diagnostics: [
+        {
+          code: "CONFIG_SYNTAX_ERROR",
+          message: `Failed to load config file: ${message}`,
+          severity: "error",
+          location: {
+            file: configPath,
+            line: 1,
+            column: 1,
+          },
+        },
+      ],
+    };
+  }
+}