hono-takibi 0.8.0-beta → 0.8.0

package/README.md

@@ -30,69 +30,49 @@ If you have OpenAPI specifications, Hono Takibi automates the conversion process
 ## Usage
 
 ```bash
-npx hono-takibi path/to/openapi.yaml -o path/to/output_hono.ts
+npx hono-takibi path/to/input.{yaml,json,tsp} -o path/to/output.ts
 ```
 
-## Demo 
+## CLI
 
-![](https://raw.githubusercontent.com/nakita628/hono-takibi/refs/heads/main/assets/demo/hono-takibi.gif)
+### Options
+
+basic
+
+```bash
+Options:
+  --export-type        export TypeScript type aliases
+  --export-schema      export Zod schema objects
+  --template           generate app file and handler stubs
+  --test               generate empty *.test.ts files
+  --base-path <path>   api prefix (default: /)
+```
+
+template
+
+> **⚠️** When using the `--template` option, you must specify a valid directory path. Ensure the directory exists before executing the 
+
+### Example
+
+```bash
+npx hono-takibi path/to/input.{yaml,json,tsp} -o path/to/output.ts --export-type --export-schema --template --base-path '/api/v1'
+```
 
 input:
 
 ```yaml
 openapi: 3.1.0
 info:
-  title: Hono API
-  version: v1
-tags:
-  - name: Hono
-    description: Endpoints related to general Hono operations
-  - name: Post
-    description: Endpoints for creating, retrieving, updating, and deleting posts
-components:
-  schemas:
-    Error:
-      type: object
-      properties:
-        message:
-          type: string
-      required:
-        - message
-    Post:
-      type: object
-      properties:
-        id:
-          type: string
-          format: uuid
-          description: Unique identifier of the post
-        post:
-          type: string
-          minLength: 1
-          maxLength: 140
-          description: Content of the post
-        createdAt:
-          type: string
-          format: date-time
-          description: Timestamp when the post was created
-        updatedAt:
-          type: string
-          format: date-time
-          description: Timestamp when the post was last updated
-      required:
-        - id
-        - post
-        - createdAt
-        - updatedAt
+  title: Hono Takibi API
+  version: "1.0.0"
 paths:
   /:
     get:
-      tags:
-        - Hono
-      summary: Welcome message
-      description: Retrieve a simple welcome message from the Hono API.
+      summary: Welcome
+      description: Returns a welcome message from Hono Takibi.
       responses:
-        '200':
-          description: Successful response with a welcome message.
+        "200":
+          description: OK
           content:
             application/json:
               schema:
@@ -100,163 +80,9 @@ paths:
                 properties:
                   message:
                     type: string
-                    example: Hono🔥
+                    example: Hono Takibi🔥
                 required:
                   - message
-  /posts:
-    post:
-      tags:
-        - Post
-      summary: Create a new post
-      description: Submit a new post with a maximum length of 140 characters.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                post:
-                  type: string
-                  minLength: 1
-                  maxLength: 140
-                  description: Content of the post
-              required:
-                - post
-      responses:
-        '201':
-          description: Post successfully created.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  message:
-                    type: string
-                    example: Post created successfully.
-                required:
-                  - message
-        '400':
-          description: Invalid request due to bad input.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        '500':
-          description: Internal server error.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-    get:
-      tags:
-        - Post
-      summary: Retrieve a list of posts
-      description: Retrieve a paginated list of posts. Specify the page number and the number of posts per page.
-      parameters:
-        - name: page
-          in: query
-          required: true
-          schema:
-            type: integer
-        - name: rows
-          in: query
-          required: true
-          schema:
-            type: integer
-      responses:
-        '200':
-          description: Successfully retrieved a list of posts.
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Post'
-        '400':
-          description: Invalid request due to bad input.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        '500':
-          description: Internal server error.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-  /posts/{id}:
-    put:
-      tags:
-        - Post
-      summary: Update an existing post
-      description: Update the content of an existing post identified by its unique ID.
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: string
-            format: uuid
-            description: Unique identifier of the post.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                post:
-                  type: string
-                  minLength: 1
-                  maxLength: 140
-                  description: Updated content for the post
-              required:
-                - post
-      responses:
-        '204':
-          description: Post successfully updated.
-        '400':
-          description: Invalid input.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        '500':
-          description: Internal server error.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-    delete:
-      tags:
-        - Post
-      summary: Delete a post
-      description: Delete an existing post identified by its unique ID.
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: string
-            format: uuid
-            description: Unique identifier of the post.
-            example: 123e4567-e89b-12d3-a456-426614174000
-      responses:
-        '204':
-          description: Post successfully deleted.
-        '400':
-          description: Invalid input.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        '500':
-          description: Internal server error.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
 ```
 
 output:
@@ -264,213 +90,117 @@ output:
 ```ts
 import { createRoute, z } from '@hono/zod-openapi'
 
-const ErrorSchema = z.object({ message: z.string() }).openapi('Error')
-
-const PostSchema = z
-  .object({
-    id: z.uuid().openapi({ description: 'Unique identifier of the post' }),
-    post: z.string().min(1).max(140).openapi({ description: 'Content of the post' }),
-    createdAt: z.iso.date().openapi({ description: 'Timestamp when the post was created' }),
-    updatedAt: z.date().openapi({ description: 'Timestamp when the post was last updated' }),
-  })
-  .openapi('Post')
-
 export const getRoute = createRoute({
-  tags: ['Hono'],
   method: 'get',
   path: '/',
-  summary: 'Welcome message',
-  description: 'Retrieve a simple welcome message from the Hono API.',
+  summary: 'Welcome',
+  description: 'Returns a welcome message from Hono Takibi.',
   responses: {
     200: {
-      description: 'Successful response with a welcome message.',
+      description: 'OK',
       content: {
         'application/json': {
-          schema: z.object({ message: z.string().openapi({ example: 'Hono🔥' }) }),
+          schema: z.object({ message: z.string().openapi({ example: 'Hono Takibi🔥' }) }),
         },
       },
     },
   },
 })
+```
 
-export const postPostsRoute = createRoute({
-  tags: ['Post'],
-  method: 'post',
-  path: '/posts',
-  summary: 'Create a new post',
-  description: 'Submit a new post with a maximum length of 140 characters.',
-  request: {
-    body: {
-      required: true,
-      content: {
-        'application/json': {
-          schema: z.object({
-            post: z.string().min(1).max(140).openapi({ description: 'Content of the post' }),
-          }),
-        },
-      },
-    },
-  },
-  responses: {
-    201: {
-      description: 'Post successfully created.',
-      content: {
-        'application/json': {
-          schema: z.object({
-            message: z.string().openapi({ example: 'Post created successfully.' }),
-          }),
-        },
-      },
-    },
-    400: {
-      description: 'Invalid request due to bad input.',
-      content: { 'application/json': { schema: ErrorSchema } },
-    },
-    500: {
-      description: 'Internal server error.',
-      content: { 'application/json': { schema: ErrorSchema } },
-    },
-  },
-})
+### Demo 
 
-export const getPostsRoute = createRoute({
-  tags: ['Post'],
-  method: 'get',
-  path: '/posts',
-  summary: 'Retrieve a list of posts',
-  description:
-    'Retrieve a paginated list of posts. Specify the page number and the number of posts per page.',
-  request: {
-    query: z.object({
-      page: z.coerce
-        .number()
-        .int()
-        .min(0)
-        .openapi({ param: { in: 'query', name: 'page', required: false } }),
-
-      rows: z.coerce
-        .number()
-        .int()
-        .min(0)
-        .openapi({ param: { in: 'query', name: 'rows', required: false } }),
-    }),
-  },
-  responses: {
-    200: {
-      description: 'Successfully retrieved a list of posts.',
-      content: { 'application/json': { schema: z.array(PostSchema) } },
-    },
-    400: {
-      description: 'Invalid request due to bad input.',
-      content: { 'application/json': { schema: ErrorSchema } },
-    },
-    500: {
-      description: 'Internal server error.',
-      content: { 'application/json': { schema: ErrorSchema } },
-    },
-  },
-})
+![](https://raw.githubusercontent.com/nakita628/hono-takibi/refs/heads/main/assets/demo/hono-takibi.gif)
 
-export const putPostsIdRoute = createRoute({
-  tags: ['Post'],
-  method: 'put',
-  path: '/posts/{id}',
-  summary: 'Update an existing post',
-  description: 'Update the content of an existing post identified by its unique ID.',
-  request: {
-    body: {
-      required: true,
-      content: {
-        'application/json': {
-          schema: z.object({
-            post: z
-              .string()
-              .min(1)
-              .max(140)
-              .openapi({ description: 'Updated content for the post' }),
-          }),
-        },
-      },
-    },
-    params: z.object({
-      id: z.uuid().openapi({
-        param: { in: 'path', name: 'id', required: true },
-        description: 'Unique identifier of the post.',
-      }),
-    }),
-  },
-  responses: {
-    204: { description: 'Post successfully updated.' },
-    400: {
-      description: 'Invalid input.',
-      content: { 'application/json': { schema: ErrorSchema } },
-    },
-    500: {
-      description: 'Internal server error.',
-      content: { 'application/json': { schema: ErrorSchema } },
-    },
-  },
-})
+## HonoTakibiVite
+
+### Automatic Code Regeneration & HMR
+
+With **HonoTakibiVite**, saving your OpenAPI spec while the Vite dev server is running instantly regenerates the code.
+
+### OpenAPI Schema Requirements
+
+- Your OpenAPI definition must include **only the `#/components/schemas/` section**.
+- It must be fully compliant with **OpenAPI 3.0 or later (e.g., 3.0 or 3.1)**.
+- Do **not** include `paths`, `tags`, or any other OpenAPI sections.
+
+### Supported Input Formats
+
+You may specify the input file in one of the following formats:
+
+- `.yaml` — OpenAPI YAML (schemas only)
+- `.json` — OpenAPI JSON (schemas only)
+- `.tsp` — TypeSpec source file
 
-export const deletePostsIdRoute = createRoute({
-  tags: ['Post'],
-  method: 'delete',
-  path: '/posts/{id}',
-  summary: 'Delete a post',
-  description: 'Delete an existing post identified by its unique ID.',
-  request: {
-    params: z.object({
-      id: z.uuid().openapi({
-        param: { in: 'path', name: 'id', required: true },
-        example: '123e4567-e89b-12d3-a456-426614174000',
-        description: 'Unique identifier of the post.',
-      }),
+### TypeSpec Setup (if using `.tsp`)
+
+If you use a `.tsp` TypeSpec file, you must set up the TypeSpec environment and install required libraries:
+
+- @typespec/http
+- @typespec/rest
+- ...other
+
+### Example
+
+`vite.config.ts`
+
+```ts
+import { defineConfig } from 'vite'
+import HonoTakibiVite from './src/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    HonoTakibiVite({
+      input: 'main.tsp',
+      output: 'index.ts',
+      exportType: true,
+      exportSchema: true,
     }),
-  },
-  responses: {
-    204: { description: 'Post successfully deleted.' },
-    400: {
-      description: 'Invalid input.',
-      content: { 'application/json': { schema: ErrorSchema } },
-    },
-    500: {
-      description: 'Internal server error.',
-      content: { 'application/json': { schema: ErrorSchema } },
-    },
-  },
+  ],
 })
 ```
 
-## CLI
+### Demo
 
-### Options
+![](https://raw.githubusercontent.com/nakita628/hono-takibi/refs/heads/main/assets/vite/hono-takibi-vite.gif)
 
-basic
 
-```bash
-Options:
-  --export-schema      exports all schema definitions
-  --export-type        exports all type definitions
-```
+## With AI Prompt
 
-template
+### Sample Prompt — Schemas-Only Extractor (OpenAPI 3+)
 
-> **⚠️** When using the `--template` option, you must specify a valid directory path. Ensure the directory exists before executing the 
+A copy‑and‑paste prompt for **any LLM** that extracts **only** the contents of `#/components/schemas/` from an OpenAPI document.
 
-```bash
-Options:
-  --template            generation of application and handler files
-  --test                automatic generation of test files
-  --base-path           base URL path for your API endpoints
-```
+## Prompt　Example
 
-### Example
+```md
+You are a **Schemas‑Only Extractor** for OpenAPI 3+.
 
-```bash
-npx hono-takibi openapi.yaml -o src/routes.ts --template -test --base-path 'api'
-```
+## 1. Version
+- Accept files that start with `openapi: "3.0.0"` or newer.
+- Otherwise reply with: `Unsupported OpenAPI version (must be 3.0+).`
+
+## 2. Scope
+- Look **only** inside `#/components/schemas/`. Ignore everything else.
+- `$ref` must also point inside that section.
 
-This project is in **early development** and being maintained by a developer with about 2 years of experience. While I'm doing my best to create a useful tool:
+## 3. Schemas section present?
+- If `components.schemas` is missing, reply with: `Missing '#/components/schemas/' section. Cannot proceed.`
+
+## 4. File type
+- Accept **.yaml**, **.json**, or **.tsp** files.
+- Otherwise reply with: `Unsupported input file extension.`
+
+## Format tips
+- `format: uuid` usually means **UUID v4**.
+- Other accepted identifiers include `uuidv6`, `uuidv7`, `ulid`, `cuid`, etc.
+- With **hono‑takibi**, you can generate **Zod schemas** directly from a custom OpenAPI file.
+
+## What the LLM should do
+1. Validate the file with the four rules above.
+2. If it passes, output **only** the YAML/JSON fragment under `#/components/schemas/` (preserve indentation).
+3. Otherwise, output the exact error message above—nothing more.
+```
 
 ### ⚠️ WARNING: Potential Breaking Changes Without Notice
 
@@ -496,27 +226,6 @@ We welcome feedback and contributions to improve the tool!
    - Limited support for certain response types
    - Some OpenAPI validations may not be perfectly converted to Zod validations
 
-### 🙏 Seeking Advice
-
-As a relatively new developer, I would greatly appreciate feedback on:
-
-- Code architecture and best practices
-- Error handling approaches
-- Testing strategies
-- Performance improvements
-- Security considerations
-- Naming convention flexibility
-- OpenAPI to Zod conversion strategies
-
-I welcome any feedback, suggestions, or contributions that could help make this tool more robust and reliable. Feel free to:
-- Open issues for bugs or suggestions
-- Submit PRs with improvements
-- Share your experience using the tool
-- Provide guidance on better coding practices
-- Report any conversion inconsistencies you find
-
-Let's make this tool better together! 🔥
-
 ## License
 
 Distributed under the MIT License. See [LICENSE](https://github.com/nakita-Ypm/hono-takibi?tab=MIT-1-ov-file) for more information.

package/dist/cli/hono-takibi/index.js

@@ -1,23 +1,17 @@
 import { ok, asyncAndThen } from '../../result/index.js';
 import { takibi } from './takibi.js';
-import { parseCli } from '../args/parse-cli.js';
+import { parseCli } from '../parse/parse-cli.js';
 import { isHelpRequested, sliceArgv } from '../utils/index.js';
 const HELP_TEXT = `
-Usage:
-  hono-takibi <input.{yaml,json,tsp}> -o <routes.ts> [options]
+Usage: hono-takibi <input.{yaml,json,tsp}> -o <routes.ts> [options]
 
 Options:
-  --export-type             Export TypeScript type aliases
-  --export-schema           Export Zod schema objects
-  --template                Generate app file and handler stubs
-  --test                    Generate empty *.test.ts files
-  --base-path <path>        API prefix (default: /)
-  -h, --help                Show this help and exit
-
-Examples:
-  hono-takibi api.yaml -o routes.ts
-  hono-takibi api.yaml -o routes.ts --export-schema --export-type --base-path /api/v1
-`.trimStart();
+  --export-type        export TypeScript type aliases
+  --export-schema      export Zod schema objects
+  --template           generate app file and handler stubs
+  --test               generate empty *.test.ts files
+  --base-path <path>   api prefix (default: /)
+  -h, --help           display help for command`.trimStart();
 export async function honoTakibi() {
     const args = sliceArgv(process.argv);
     return isHelpRequested(sliceArgv(process.argv))

package/dist/cli/hono-takibi/takibi.d.ts

@@ -1,4 +1,15 @@
-import type { Result } from '../../result/types.js';
+import type { Result } from '../../result/index.js';
+/**
+ * @param { `${string}.yaml` | `${string}.json` | `${string}.tsp` } input - The input OpenAPI file.
+ * @param { `${string}.ts` } output - The output TypeScript file.
+ * @param { boolean } exportSchema - Whether to export the schema.
+ * @param { boolean } exportType - Whether to export the type.
+ * @param { boolean } template - Whether to generate a template.
+ * @param { boolean } test - Whether to generate test files.
+ * @param { string } [basePath] - The base path for the template.
+ * @returns { Promise<Result<{ message: string }, string>> }
+ * @description Generates TypeScript code from an OpenAPI specification and optionally creates template files.
+ */
 export declare function takibi(input: `${string}.yaml` | `${string}.json` | `${string}.tsp`, output: `${string}.ts`, exportSchema: boolean, exportType: boolean, template: boolean, test: boolean, basePath?: string): Promise<Result<{
     message: string;
 }, string>>;

package/dist/cli/hono-takibi/takibi.js

@@ -5,6 +5,17 @@ import { parseOpenAPI } from '../../openapi/parse-openapi.js';
 import { zodOpenAPIHono } from '../../generator/zod-openapi-hono/openapi/zod-openapi-hono.js';
 import { templateCode } from './template-code.js';
 import { mkdir, writeFile } from '../../fsp/index.js';
+/**
+ * @param { `${string}.yaml` | `${string}.json` | `${string}.tsp` } input - The input OpenAPI file.
+ * @param { `${string}.ts` } output - The output TypeScript file.
+ * @param { boolean } exportSchema - Whether to export the schema.
+ * @param { boolean } exportType - Whether to export the type.
+ * @param { boolean } template - Whether to generate a template.
+ * @param { boolean } test - Whether to generate test files.
+ * @param { string } [basePath] - The base path for the template.
+ * @returns { Promise<Result<{ message: string }, string>> }
+ * @description Generates TypeScript code from an OpenAPI specification and optionally creates template files.
+ */
 export async function takibi(input, output, exportSchema, exportType, template, test, basePath) {
     return await asyncAndThen(await parseOpenAPI(input), async (openAPI) => asyncAndThen(await fmt(zodOpenAPIHono(openAPI, exportSchema, exportType)), async (code) => asyncAndThen(await mkdir(path.dirname(output)), async () => asyncAndThen(await writeFile(output, code), async () => asyncAndThen(await templateCode(openAPI, output, template, test, basePath), async () => ok({
         message: template

package/dist/cli/hono-takibi/template-code.d.ts

@@ -1,3 +1,12 @@
 import type { OpenAPI } from '../../openapi/index.js';
 import type { Result } from '../../result/index.js';
+/**
+ * @param { OpenAPI } openAPI - OpenAPI specification
+ * @param { `${string}.ts` } output - Output file path
+ * @param { boolean } template - Whether to generate a template
+ * @param { boolean } test - Whether to generate test files
+ * @param { string } basePath - Optional base path for the application
+ * @returns { Promise<Result<void, string>> }
+ * @description Generates a Hono Takibi application template code based on the OpenAPI specification.
+ */
 export declare function templateCode(openAPI: OpenAPI, output: `${string}.ts`, template: boolean, test: boolean, basePath?: string): Promise<Result<void, string>>;

package/dist/cli/hono-takibi/template-code.js

@@ -4,6 +4,15 @@ import { readdir, writeFile } from '../../fsp/index.js';
 import { fmt } from '../../format/index.js';
 import { app } from '../../generator/zod-openapi-hono/app/index.js';
 import { zodOpenapiHonoHandler } from '../../generator/zod-openapi-hono/handler/zod-openapi-hono-handler.js';
+/**
+ * @param { OpenAPI } openAPI - OpenAPI specification
+ * @param { `${string}.ts` } output - Output file path
+ * @param { boolean } template - Whether to generate a template
+ * @param { boolean } test - Whether to generate test files
+ * @param { string } basePath - Optional base path for the application
+ * @returns { Promise<Result<void, string>> }
+ * @description Generates a Hono Takibi application template code based on the OpenAPI specification.
+ */
 export async function templateCode(openAPI, output, template, test, basePath) {
     if (!(template && output.includes('/')))
         return ok(undefined);