codeply-cli 0.5.6 → 0.6.0

package/skills/tinystruct-patterns/references/architecture.md

@@ -1,90 +1,90 @@
-# tinystruct Architecture and Configuration
-
-## When to Use
-
-Choose **tinystruct** when you need a lightweight, high-performance Java framework that treats CLI and HTTP as equal citizens. Ideal for microservices, CLI utilities, and data-driven applications with a small footprint and zero-dependency JSON handling.
-
-## How It Works
-
-### Core Architecture
-
-The framework operates on a singleton `ActionRegistry` that maps URL patterns (or command strings) to `Action` objects. When a request arrives, the system resolves the path and invokes the corresponding method handle.
-
-#### Key Abstractions
-
-| Class/Interface | Role |
-|---|---|
-| `AbstractApplication` | Base class for all tinystruct applications. Extend this. |
-| `@Action` annotation | Maps a method to a URI path (web) or command name (CLI). The single routing primitive. |
-| `ActionRegistry` | Singleton that maps URL patterns to `Action` objects via regex. Never instantiate directly. |
-| `Action` | Wraps a `MethodHandle` + regex pattern + priority + `Mode` for dispatch. |
-| `Context` | Per-request state store. Access via `getContext()`. Holds CLI args and HTTP request/response. |
-| `Dispatcher` | CLI entry point (`bin/dispatcher`). Reads `--import` to load applications. |
-| `HttpServer` | Built-in HTTP server. Start with `bin/dispatcher start --import org.tinystruct.system.HttpServer`. |
-
-### Package Map
-
-```
-org.tinystruct/
-├── AbstractApplication.java      ← extend this
-├── Application.java              ← interface
-├── ApplicationException.java     ← checked exception
-├── ApplicationRuntimeException.java ← unchecked exception
-├── application/
-│   ├── Action.java               ← runtime action wrapper
-│   ├── ActionRegistry.java       ← singleton route registry
-│   └── Context.java              ← request context
-├── system/
-│   ├── annotation/Action.java    ← @Action annotation + Mode enum
-│   ├── Dispatcher.java           ← CLI dispatcher
-│   ├── HttpServer.java           ← built-in HTTP server
-│   ├── EventDispatcher.java      ← event bus
-│   └── Settings.java             ← reads application.properties
-├── data/
-│   ├── component/Builder.java    ← JSON object (use instead of Gson/Jackson)
-│   ├── component/Builders.java   ← JSON array
-│   ├── component/AbstractData.java ← base POJO for DB persistence
-│   ├── component/Condition.java  ← fluent SQL query builder
-│   ├── component/FieldType.java  ← SQL-to-Java type mappings
-│   ├── Mapping.java              ← reads .map.xml metadata
-│   ├── DatabaseOperator.java     ← low-level JDBC wrapper
-│   └── FileEntity.java           ← file upload representation
-├── http/                         ← Request, Response, Constants
-│   └── SSEPushManager.java       ← Server-Sent Events management
-└── net/                          ← URLRequest, HTTPHandler (outbound HTTP)
-```
-
-### Template Behavior and Dispatch Flow
-
-By default, the framework assumes a view template is required. If `templateRequired` is `true`, `toString()` looks for a `.view` file in `src/main/resources/themes/<ClassName>.view`. Use `setVariable("name", value)` to pass data to templates, which use `{%name%}` for interpolation.
-
-## Examples
-
-### Minimal Application Initialization
-```java
-@Override
-public void init() {
-    this.setTemplateRequired(false); // Skip .view template lookup for data-only apps
-    // Do NOT call setAction() here — use @Action annotation instead
-}
-```
-
-### Action Definition and CLI Invocation
-```java
-@Action("hello")
-public String hello() {
-    return "Hello, tinystruct!";
-}
-```
-**Execution via Dispatcher:**
-```bash
-bin/dispatcher hello
-bin/dispatcher greet/James
-bin/dispatcher echo --words "Hello" --import com.example.HelloApp
-```
-
-### Configuration Access
-Located at `src/main/resources/application.properties`:
-```java
-String port = this.getConfiguration("server.port");
-```
+# tinystruct Architecture and Configuration
+
+## When to Use
+
+Choose **tinystruct** when you need a lightweight, high-performance Java framework that treats CLI and HTTP as equal citizens. Ideal for microservices, CLI utilities, and data-driven applications with a small footprint and zero-dependency JSON handling.
+
+## How It Works
+
+### Core Architecture
+
+The framework operates on a singleton `ActionRegistry` that maps URL patterns (or command strings) to `Action` objects. When a request arrives, the system resolves the path and invokes the corresponding method handle.
+
+#### Key Abstractions
+
+| Class/Interface | Role |
+|---|---|
+| `AbstractApplication` | Base class for all tinystruct applications. Extend this. |
+| `@Action` annotation | Maps a method to a URI path (web) or command name (CLI). The single routing primitive. |
+| `ActionRegistry` | Singleton that maps URL patterns to `Action` objects via regex. Never instantiate directly. |
+| `Action` | Wraps a `MethodHandle` + regex pattern + priority + `Mode` for dispatch. |
+| `Context` | Per-request state store. Access via `getContext()`. Holds CLI args and HTTP request/response. |
+| `Dispatcher` | CLI entry point (`bin/dispatcher`). Reads `--import` to load applications. |
+| `HttpServer` | Built-in HTTP server. Start with `bin/dispatcher start --import org.tinystruct.system.HttpServer`. |
+
+### Package Map
+
+```
+org.tinystruct/
+├── AbstractApplication.java      ← extend this
+├── Application.java              ← interface
+├── ApplicationException.java     ← checked exception
+├── ApplicationRuntimeException.java ← unchecked exception
+├── application/
+│   ├── Action.java               ← runtime action wrapper
+│   ├── ActionRegistry.java       ← singleton route registry
+│   └── Context.java              ← request context
+├── system/
+│   ├── annotation/Action.java    ← @Action annotation + Mode enum
+│   ├── Dispatcher.java           ← CLI dispatcher
+│   ├── HttpServer.java           ← built-in HTTP server
+│   ├── EventDispatcher.java      ← event bus
+│   └── Settings.java             ← reads application.properties
+├── data/
+│   ├── component/Builder.java    ← JSON object (use instead of Gson/Jackson)
+│   ├── component/Builders.java   ← JSON array
+│   ├── component/AbstractData.java ← base POJO for DB persistence
+│   ├── component/Condition.java  ← fluent SQL query builder
+│   ├── component/FieldType.java  ← SQL-to-Java type mappings
+│   ├── Mapping.java              ← reads .map.xml metadata
+│   ├── DatabaseOperator.java     ← low-level JDBC wrapper
+│   └── FileEntity.java           ← file upload representation
+├── http/                         ← Request, Response, Constants
+│   └── SSEPushManager.java       ← Server-Sent Events management
+└── net/                          ← URLRequest, HTTPHandler (outbound HTTP)
+```
+
+### Template Behavior and Dispatch Flow
+
+By default, the framework assumes a view template is required. If `templateRequired` is `true`, `toString()` looks for a `.view` file in `src/main/resources/themes/<ClassName>.view`. Use `setVariable("name", value)` to pass data to templates, which use `{%name%}` for interpolation.
+
+## Examples
+
+### Minimal Application Initialization
+```java
+@Override
+public void init() {
+    this.setTemplateRequired(false); // Skip .view template lookup for data-only apps
+    // Do NOT call setAction() here — use @Action annotation instead
+}
+```
+
+### Action Definition and CLI Invocation
+```java
+@Action("hello")
+public String hello() {
+    return "Hello, tinystruct!";
+}
+```
+**Execution via Dispatcher:**
+```bash
+bin/dispatcher hello
+bin/dispatcher greet/James
+bin/dispatcher echo --words "Hello" --import com.example.HelloApp
+```
+
+### Configuration Access
+Located at `src/main/resources/application.properties`:
+```java
+String port = this.getConfiguration("server.port");
+```

package/skills/tinystruct-patterns/references/data-handling.md

@@ -1,60 +1,60 @@
-# tinystruct Data Handling (JSON)
-
-## When to Use
-
-Prefer `org.tinystruct.data.component.Builder` and `Builders` for lightweight, zero-dependency JSON. Use `Builder` for JSON objects (`{}`), `Builders` for JSON arrays (`[]`). **Always use `Builders` instead of `List<Builder>`** to avoid generic type erasure issues.
-
-## How It Works
-
-`Builder` provides a key-value interface for creating and reading JSON objects. `Builders` provides an indexed list for JSON arrays. Both integrate directly with `AbstractApplication` result handling.
-
-### Why Builder/Builders?
-- **Zero External Dependencies** — lean and fast
-- **Native Integration** — works with framework result handling
-- **Type Safety** — `Builders` serializes properly to `[]`; `List<Builder>` can cause casting issues
-
-## Examples
-
-### Serialize a Single Object
-```java
-import org.tinystruct.data.component.Builder;
-
-Builder response = new Builder();
-response.put("status", "success");
-response.put("count", 42);
-return response.toString(); // {"status":"success","count":42}
-```
-
-### Serialize a List using Builders
-```java
-import org.tinystruct.data.component.Builder;
-import org.tinystruct.data.component.Builders;
-
-Builders dataList = new Builders();
-for (MyModel item : myCollection) {
-    Builder b = new Builder();
-    b.put("id", item.getId());
-    b.put("name", item.getName());
-    dataList.add(b);
-}
-Builder response = new Builder();
-response.put("data", dataList);
-return response.toString(); // {"data":[{"id":1,"name":"X"}]}
-```
-
-### Parse a JSON Object
-```java
-Builder parsed = new Builder();
-parsed.parse(jsonString);
-String status = parsed.get("status").toString();
-```
-
-### Parse a JSON Array
-```java
-Builders parsedArray = new Builders();
-parsedArray.parse(jsonArrayString);
-for (int i = 0; i < parsedArray.size(); i++) {
-    Builder item = parsedArray.get(i);
-    System.out.println(item.get("name"));
-}
-```
+# tinystruct Data Handling (JSON)
+
+## When to Use
+
+Prefer `org.tinystruct.data.component.Builder` and `Builders` for lightweight, zero-dependency JSON. Use `Builder` for JSON objects (`{}`), `Builders` for JSON arrays (`[]`). **Always use `Builders` instead of `List<Builder>`** to avoid generic type erasure issues.
+
+## How It Works
+
+`Builder` provides a key-value interface for creating and reading JSON objects. `Builders` provides an indexed list for JSON arrays. Both integrate directly with `AbstractApplication` result handling.
+
+### Why Builder/Builders?
+- **Zero External Dependencies** — lean and fast
+- **Native Integration** — works with framework result handling
+- **Type Safety** — `Builders` serializes properly to `[]`; `List<Builder>` can cause casting issues
+
+## Examples
+
+### Serialize a Single Object
+```java
+import org.tinystruct.data.component.Builder;
+
+Builder response = new Builder();
+response.put("status", "success");
+response.put("count", 42);
+return response.toString(); // {"status":"success","count":42}
+```
+
+### Serialize a List using Builders
+```java
+import org.tinystruct.data.component.Builder;
+import org.tinystruct.data.component.Builders;
+
+Builders dataList = new Builders();
+for (MyModel item : myCollection) {
+    Builder b = new Builder();
+    b.put("id", item.getId());
+    b.put("name", item.getName());
+    dataList.add(b);
+}
+Builder response = new Builder();
+response.put("data", dataList);
+return response.toString(); // {"data":[{"id":1,"name":"X"}]}
+```
+
+### Parse a JSON Object
+```java
+Builder parsed = new Builder();
+parsed.parse(jsonString);
+String status = parsed.get("status").toString();
+```
+
+### Parse a JSON Array
+```java
+Builders parsedArray = new Builders();
+parsedArray.parse(jsonArrayString);
+for (int i = 0; i < parsedArray.size(); i++) {
+    Builder item = parsedArray.get(i);
+    System.out.println(item.get("name"));
+}
+```

package/skills/tinystruct-patterns/references/database.md

@@ -1,99 +1,99 @@
-# tinystruct Database Persistence
-
-## When to Use
-
-Use the built-in ORM-like data layer for database operations. It provides a lightweight alternative to JPA/Hibernate using POJOs extending `AbstractData` and XML mapping files.
-
-## How It Works
-
-### Architecture
-
-Each table is represented by:
-1. **Java POJO**: Extends `AbstractData`, provides getters/setters and `setData(Row)`.
-2. **Mapping XML**: `ClassName.map.xml` in resources, binding Java fields to DB columns.
-
-#### Key Base Class: `AbstractData`
-Provides CRUD methods:
-- `append()` / `appendAndGetId()`
-- `update()`
-- `delete()`
-- `findAll()` / `findOneById()` / `findOneByKey(key, value)`
-- `findWith(where, params)`
-- `find(SQL, params)`
-
-### POJO Generation (CLI)
-
-Introspect a live database table to produce the POJO and mapping file.
-
-#### Configuration
-`application.properties`:
-```properties
-driver=com.mysql.cj.jdbc.Driver
-database.url=jdbc:mysql://localhost:3306/mydb
-database.user=root
-database.password=secret
-```
-
-#### Command
-```bash
-# Interactive mode
-bin/dispatcher generate
-
-# Specify table
-bin/dispatcher generate --tables users
-```
-
-## Examples
-
-### CRUD Operations
-```java
-// CREATE
-User user = new User();
-user.setUsername("james");
-user.append();
-
-// READ
-User user = new User();
-user.setId(42);
-user.findOneById();
-
-// UPDATE
-user.setEmail("new@example.com");
-user.update();
-
-// DELETE
-user.delete();
-```
-
-### Querying with Conditions
-```java
-User user = new User();
-Table results = user.findWith("username LIKE ?", new Object[]{"%jam%"});
-
-// Fluent Condition Builder
-Condition condition = new Condition();
-condition.setRequestFields("id,username");
-Table filtered = user.find(
-    condition.select("`users`").and("email LIKE ?").orderBy("id DESC"),
-    new Object[]{"%@example.com"}
-);
-```
-
-### Mapping XML Structure
-`User.map.xml`:
-```xml
-<mapping>
-  <class name="User" table="users">
-    <id name="Id" column="id" increment="true" generate="false" length="11" type="int"/>
-    <property name="username" column="username" length="50" type="varchar"/>
-    <property name="email" column="email" length="100" type="varchar"/>
-  </class>
-</mapping>
-```
-
-## Important Rules
-
-1. **File Placement**: The mapping XML **must** mirror the POJO's package path under `src/main/resources/`.
-2. **Naming**: Table names are singularized for class names (`users` → `User`). Underscored columns become camelCase fields (`created_at` → `createdAt`).
-3. **Setters**: Use `setFieldAsXxx` methods (e.g., `setFieldAsString`) in setters to sync state with the internal field map.
-4. **Id Field**: The primary key field in Java is always named `Id` (inherited from `AbstractData`).
+# tinystruct Database Persistence
+
+## When to Use
+
+Use the built-in ORM-like data layer for database operations. It provides a lightweight alternative to JPA/Hibernate using POJOs extending `AbstractData` and XML mapping files.
+
+## How It Works
+
+### Architecture
+
+Each table is represented by:
+1. **Java POJO**: Extends `AbstractData`, provides getters/setters and `setData(Row)`.
+2. **Mapping XML**: `ClassName.map.xml` in resources, binding Java fields to DB columns.
+
+#### Key Base Class: `AbstractData`
+Provides CRUD methods:
+- `append()` / `appendAndGetId()`
+- `update()`
+- `delete()`
+- `findAll()` / `findOneById()` / `findOneByKey(key, value)`
+- `findWith(where, params)`
+- `find(SQL, params)`
+
+### POJO Generation (CLI)
+
+Introspect a live database table to produce the POJO and mapping file.
+
+#### Configuration
+`application.properties`:
+```properties
+driver=com.mysql.cj.jdbc.Driver
+database.url=jdbc:mysql://localhost:3306/mydb
+database.user=root
+database.password=secret
+```
+
+#### Command
+```bash
+# Interactive mode
+bin/dispatcher generate
+
+# Specify table
+bin/dispatcher generate --tables users
+```
+
+## Examples
+
+### CRUD Operations
+```java
+// CREATE
+User user = new User();
+user.setUsername("james");
+user.append();
+
+// READ
+User user = new User();
+user.setId(42);
+user.findOneById();
+
+// UPDATE
+user.setEmail("new@example.com");
+user.update();
+
+// DELETE
+user.delete();
+```
+
+### Querying with Conditions
+```java
+User user = new User();
+Table results = user.findWith("username LIKE ?", new Object[]{"%jam%"});
+
+// Fluent Condition Builder
+Condition condition = new Condition();
+condition.setRequestFields("id,username");
+Table filtered = user.find(
+    condition.select("`users`").and("email LIKE ?").orderBy("id DESC"),
+    new Object[]{"%@example.com"}
+);
+```
+
+### Mapping XML Structure
+`User.map.xml`:
+```xml
+<mapping>
+  <class name="User" table="users">
+    <id name="Id" column="id" increment="true" generate="false" length="11" type="int"/>
+    <property name="username" column="username" length="50" type="varchar"/>
+    <property name="email" column="email" length="100" type="varchar"/>
+  </class>
+</mapping>
+```
+
+## Important Rules
+
+1. **File Placement**: The mapping XML **must** mirror the POJO's package path under `src/main/resources/`.
+2. **Naming**: Table names are singularized for class names (`users` → `User`). Underscored columns become camelCase fields (`created_at` → `createdAt`).
+3. **Setters**: Use `setFieldAsXxx` methods (e.g., `setFieldAsString`) in setters to sync state with the internal field map.
+4. **Id Field**: The primary key field in Java is always named `Id` (inherited from `AbstractData`).

package/skills/tinystruct-patterns/references/routing.md

@@ -1,64 +1,64 @@
-# tinystruct @Action Routing Reference
-
-## When to Use
-
-Use the `@Action` annotation in your applications to define routes for both CLI commands and HTTP endpoints. It is appropriate whenever you need to map logic to a specific path, handle parameterized requests, or restrict execution to specific HTTP methods while maintaining a consistent command structure across environments.
-
-## How It Works
-
-The `ActionRegistry` parses `@Action` annotations to build a routing table. For parameterized methods, the framework automatically maps Java parameter types to corresponding regex segments.
-
-### Regex Generation Rules
-- `getUser(int id)` → pattern: `^/?user/(-?\d+)$`
-- `search(String query)` → pattern: `^/?search/([^/]+)$`
-
-Supported parameter types: `String`, `int/Integer`, `long/Long`, `float/Float`, `double/Double`, `boolean/Boolean`, `char/Character`, `short/Short`, `byte/Byte`, `Date` (parsed as `yyyy-MM-dd HH:mm:ss`).
-
-### Mode Values
-
-| Mode | When it triggers |
-|---|---|
-| `DEFAULT` | Both CLI and HTTP (GET, POST, etc.) |
-| `CLI` | CLI dispatcher only |
-| `HTTP_GET` | HTTP GET only |
-| `HTTP_POST` | HTTP POST only |
-| `HTTP_PUT` | HTTP PUT only |
-| `HTTP_DELETE` | HTTP DELETE only |
-| `HTTP_PATCH` | HTTP PATCH only |
-
-> **Note:** You can map HTTP method names to `Mode` using `Action.Mode.fromName(String methodName)`. Unknown or null values return `Mode.DEFAULT`.
-
-## Examples
-
-### Basic Action Declaration
-```java
-@Action(
-    value = "path/subpath",          // required: URI segment or CLI command
-    description = "What it does",    // shown in --help output
-    mode = Mode.DEFAULT,             // default: Mode.DEFAULT
-    example = "bin/dispatcher path/subpath/42"
-)
-public String myAction(int id) { ... }
-```
-
-### Parameterized Paths
-```java
-@Action("user/{id}")
-public String getUser(int id) { ... }
-// → CLI: bin/dispatcher user/42
-// → HTTP: /?q=user/42
-```
-
-### Dependency Injection
-`ActionRegistry` automatically injects `Request` and/or `Response` from `Context` if they are parameters:
-
-```java
-@Action(value = "upload", mode = Mode.HTTP_POST)
-public String upload(Request<?, ?> req, Response<?, ?> res) throws ApplicationException {
-    // Access raw request/response if needed
-    return "ok";
-}
-```
-
-### Path Matching Priority
-If two methods share the same path, the framework uses the first match in the `ActionRegistry`. Use explicit `Mode` values to disambiguate (e.g., separating a GET for a form and a POST for submission).
+# tinystruct @Action Routing Reference
+
+## When to Use
+
+Use the `@Action` annotation in your applications to define routes for both CLI commands and HTTP endpoints. It is appropriate whenever you need to map logic to a specific path, handle parameterized requests, or restrict execution to specific HTTP methods while maintaining a consistent command structure across environments.
+
+## How It Works
+
+The `ActionRegistry` parses `@Action` annotations to build a routing table. For parameterized methods, the framework automatically maps Java parameter types to corresponding regex segments.
+
+### Regex Generation Rules
+- `getUser(int id)` → pattern: `^/?user/(-?\d+)$`
+- `search(String query)` → pattern: `^/?search/([^/]+)$`
+
+Supported parameter types: `String`, `int/Integer`, `long/Long`, `float/Float`, `double/Double`, `boolean/Boolean`, `char/Character`, `short/Short`, `byte/Byte`, `Date` (parsed as `yyyy-MM-dd HH:mm:ss`).
+
+### Mode Values
+
+| Mode | When it triggers |
+|---|---|
+| `DEFAULT` | Both CLI and HTTP (GET, POST, etc.) |
+| `CLI` | CLI dispatcher only |
+| `HTTP_GET` | HTTP GET only |
+| `HTTP_POST` | HTTP POST only |
+| `HTTP_PUT` | HTTP PUT only |
+| `HTTP_DELETE` | HTTP DELETE only |
+| `HTTP_PATCH` | HTTP PATCH only |
+
+> **Note:** You can map HTTP method names to `Mode` using `Action.Mode.fromName(String methodName)`. Unknown or null values return `Mode.DEFAULT`.
+
+## Examples
+
+### Basic Action Declaration
+```java
+@Action(
+    value = "path/subpath",          // required: URI segment or CLI command
+    description = "What it does",    // shown in --help output
+    mode = Mode.DEFAULT,             // default: Mode.DEFAULT
+    example = "bin/dispatcher path/subpath/42"
+)
+public String myAction(int id) { ... }
+```
+
+### Parameterized Paths
+```java
+@Action("user/{id}")
+public String getUser(int id) { ... }
+// → CLI: bin/dispatcher user/42
+// → HTTP: /?q=user/42
+```
+
+### Dependency Injection
+`ActionRegistry` automatically injects `Request` and/or `Response` from `Context` if they are parameters:
+
+```java
+@Action(value = "upload", mode = Mode.HTTP_POST)
+public String upload(Request<?, ?> req, Response<?, ?> res) throws ApplicationException {
+    // Access raw request/response if needed
+    return "ok";
+}
+```
+
+### Path Matching Priority
+If two methods share the same path, the framework uses the first match in the `ActionRegistry`. Use explicit `Mode` values to disambiguate (e.g., separating a GET for a form and a POST for submission).