create-yss-spec 1.0.0

package/template/.codex/skills/yss-web-controller/scripts/generate_controller.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import argparse
+import json
+import os
+import re
+import sys
+from string import Template
+
+def to_camel_case(snake_str):
+    components = snake_str.lower().split('_')
+    return "".join(x.title() for x in components)
+
+def to_lower_camel_case(snake_str):
+    camel = to_camel_case(snake_str)
+    if not camel:
+        return ""
+    return camel[0].lower() + camel[1:]
+
+def to_kebab_case(snake_str):
+    return snake_str.lower().replace('_', '-')
+
+def package_to_path(package_name):
+    return package_name.replace(".", os.sep)
+
+def ensure_subdir(root_path, subdir_name):
+    if os.path.basename(os.path.normpath(root_path)) == subdir_name:
+        return root_path
+    return os.path.join(root_path, subdir_name)
+
+TYPE_MAPPING = {
+    "bigint": "Long",
+    "int": "Integer",
+    "integer": "Integer",
+    "smallint": "Integer",
+    "tinyint": "Integer",
+    "number": "Long",
+    "numeric": "BigDecimal",
+    "decimal": "BigDecimal",
+    "float": "Float",
+    "double": "Double",
+    "real": "Float",
+    "varchar": "String",
+    "varchar2": "String",
+    "nvarchar2": "String",
+    "char": "String",
+    "nchar": "String",
+    "text": "String",
+    "clob": "String",
+    "nclob": "String",
+    "date": "LocalDateTime",
+    "datetime": "LocalDateTime",
+    "timestamp": "LocalDateTime",
+    "timestamp with time zone": "LocalDateTime",
+    "boolean": "Boolean",
+    "bool": "Boolean",
+    "bit": "Boolean",
+    "json": "String",
+    "jsonb": "String",
+    "uuid": "String"
+}
+
+def get_java_type(sql_type):
+    sql_type = sql_type.lower()
+    # Handle types like varchar(255)
+    base_type = re.split(r'\(', sql_type)[0]
+    return TYPE_MAPPING.get(base_type, "String")
+
+def generate_fields(columns, skip_pk=False, is_cmd=False, skip_audit=True):
+    fields = []
+    for col in columns:
+        col_name = col["name"]
+        if skip_pk and col.get("primary"):
+            continue
+        
+        # Skip audit columns if they are standard
+        if skip_audit and col_name.lower() in ["create_time", "update_time", "create_by", "update_by", "deleted", "version"]:
+            continue
+
+        java_type = get_java_type(col["sql_type"])
+        java_name = to_lower_camel_case(col_name)
+        comment = col.get("comment", "")
+        
+        field_str = ""
+        if comment:
+            field_str += f"    /**\n     * {comment}\n     */\n"
+        
+        if is_cmd:
+            if not col.get("nullable"):
+                if java_type == "String":
+                    field_str += f"    @NotBlank(message = \"{comment or java_name}不能为空\")\n"
+                else:
+                    field_str += f"    @NotNull(message = \"{comment or java_name}不能为空\")\n"
+        
+        field_str += f"    private {java_type} {java_name};"
+        fields.append(field_str)
+    
+    return "\n\n".join(fields)
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate YSS Web Controller and DTOs")
+    parser.add_argument("--metadata-file", required=True, help="Path to metadata.json")
+    parser.add_argument("--base-package", required=True, help="Base package name")
+    parser.add_argument("--module-name", required=True, help="Module name")
+    parser.add_argument("--output-dir", default="./output", help="Output directory")
+    parser.add_argument("--domain-project-dir", help="Domain module root directory")
+    parser.add_argument("--web-project-dir", help="Web module root directory")
+    parser.add_argument("--domain-output-dir", help="Domain module output directory (for DTOs/VOs)")
+    parser.add_argument("--web-output-dir", help="Web module output directory (for Controller)")
+    parser.add_argument("--author", default="System", help="Author name")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing files")
+    parser.add_argument("--domain-segment", required=True, help="Domain segment package name")
+
+    args = parser.parse_args()
+
+    if not os.path.exists(args.metadata_file):
+        print(f"Error: Metadata file not found: {args.metadata_file}")
+        sys.exit(1)
+
+    try:
+        with open(args.metadata_file, 'r', encoding='utf-8') as f:
+            metadata = json.load(f)
+    except Exception as e:
+        print(f"Error reading metadata file: {e}")
+        sys.exit(1)
+
+    tables = metadata.get("tables", [])
+    if not tables:
+        print("Warning: No tables found in metadata.")
+        return
+
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    templates_dir = os.path.join(script_dir, "../assets/templates")
+    
+    def load_tpl(name):
+        path = os.path.join(templates_dir, name)
+        if not os.path.exists(path):
+            print(f"Warning: Template not found: {path}")
+            return None
+        with open(path, 'r', encoding='utf-8') as f:
+            return f.read()
+
+    controller_tpl = load_tpl("Controller.java.template")
+    web_convertor_tpl = load_tpl("WebConvertor.java.template")
+    vo_tpl = load_tpl("domain/vo/VO.java.template")
+    add_cmd_tpl = load_tpl("domain/dto/cmd/AddCmd.java.template")
+    update_cmd_tpl = load_tpl("domain/dto/cmd/UpdateCmd.java.template")
+    page_query_tpl = load_tpl("domain/dto/query/PageQuery.java.template")
+    package_path = package_to_path(args.base_package)
+
+    if args.domain_output_dir:
+        domain_base_root = args.domain_output_dir
+    elif args.domain_project_dir:
+        domain_base_root = os.path.join(args.domain_project_dir, "src", "main", "java", package_path)
+    else:
+        domain_base_root = os.path.join(args.output_dir, package_path)
+
+    if args.web_output_dir:
+        web_base_root = args.web_output_dir
+    elif args.web_project_dir:
+        web_base_root = os.path.join(args.web_project_dir, "src", "main", "java", package_path)
+    else:
+        web_base_root = os.path.join(args.output_dir, package_path)
+
+    domain_root = ensure_subdir(domain_base_root, "client")
+    web_root = ensure_subdir(web_base_root, "rest")
+
+    for table in tables:
+        table_name = table["table_name"]
+        clean_name = to_camel_case(table_name)
+        
+        domain_class = clean_name
+        domain_var = to_lower_camel_case(table_name)
+        domain_desc = table.get("table_comment") or domain_class
+        domain_desc = domain_desc.strip().replace('\n', ' ')
+        domain_pkg_name = args.domain_segment
+        domain_url_path = to_kebab_case(table_name)
+
+        gateway_pkg = f"{args.base_package}.domain.{domain_pkg_name}.gateway"
+        domain_model_pkg = f"{args.base_package}.domain.{domain_pkg_name}.model"
+        web_convertor_pkg = f"{args.base_package}.rest.convertor"
+
+        # Field generation for DTOs
+        columns = table.get("columns", [])
+        field_declarations_vo = generate_fields(columns, skip_audit=False)
+        field_declarations_add = generate_fields(columns, skip_pk=True, is_cmd=True, skip_audit=True)
+        field_declarations_update = generate_fields(columns, skip_pk=False, is_cmd=True, skip_audit=True)
+        field_declarations_query = generate_fields(columns, skip_audit=True) # Query usually has all fields as optional filters
+
+        use_gateway = True
+        vo_class = f"{domain_class}VO"
+        add_cmd_class = f"{domain_class}AddCmd"
+        update_cmd_class = f"{domain_class}UpdateCmd"
+        query_class = f"{domain_class}Page"
+        domain_import = f"import {domain_model_pkg}.{domain_class};"
+
+        query_call = f"{domain_var}Gateway.page{domain_class}(query)"
+        detail_call = f"{domain_var}Gateway.get{domain_class}ById(id).orElse(null)"
+        add_call = f"{domain_var}Gateway.add{domain_class}(CONVERTOR.toDomain(cmd))"
+        update_call = f"{domain_var}Gateway.update{domain_class}(CONVERTOR.toDomain(cmd))"
+        delete_call = f"{domain_var}Gateway.delete{domain_class}(id)"
+
+        gateway_import = f"import {gateway_pkg}.{domain_class}Gateway;" if use_gateway else ""
+        dto_imports = "\n".join([
+            f"import {args.base_package}.client.dto.cmd.{domain_class}AddCmd;",
+            f"import {args.base_package}.client.dto.cmd.{domain_class}UpdateCmd;",
+            f"import {args.base_package}.client.dto.query.{domain_class}Page;",
+            f"import {args.base_package}.client.vo.{domain_class}VO;"
+        ])
+        gateway_field = f"private final {domain_class}Gateway {domain_var}Gateway;" if use_gateway else ""
+        web_convertor_class = f"{domain_class}WebConvertor"
+        web_convertor_import = f"import {web_convertor_pkg}.{web_convertor_class};"
+
+        ctx = {
+            "base_package": args.base_package,
+            "module_name": args.module_name,
+            "domain_class": domain_class,
+            "domain_var": domain_var,
+            "domain_desc": domain_desc,
+            "domain_url_path": domain_url_path,
+            "domain_pkg_name": domain_pkg_name,
+            "author": args.author,
+            "dto_imports": dto_imports,
+            "gateway_import": gateway_import,
+            "domain_import": domain_import,
+            "web_convertor_import": web_convertor_import,
+            "web_convertor_class": web_convertor_class,
+            "gateway_pkg": gateway_pkg,
+            "gateway_field": gateway_field,
+            "query_call": query_call,
+            "detail_call": detail_call,
+            "add_call": add_call,
+            "update_call": update_call,
+            "delete_call": delete_call,
+            "vo_class": vo_class,
+            "add_cmd_class": add_cmd_class,
+            "update_cmd_class": update_cmd_class,
+            "query_class": query_class,
+            "field_declarations": "" # placeholder
+        }
+
+        def write_file(path, content):
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            if not os.path.exists(path) or args.force:
+                with open(path, 'w', encoding='utf-8') as f:
+                    f.write(content)
+                print(f"Generated: {path}")
+            else:
+                print(f"Skipped (exists): {path}")
+
+        # 1. Controller (Web Layer)
+        write_file(os.path.join(web_root, f"{domain_class}Controller.java"), Template(controller_tpl).substitute(ctx))
+        write_file(
+            os.path.join(web_root, "convertor", f"{web_convertor_class}.java"),
+            Template(web_convertor_tpl).substitute(ctx)
+        )
+
+        # 2. DTOs & VO (Domain Layer)
+        ctx["field_declarations"] = field_declarations_vo
+        write_file(os.path.join(domain_root, "vo", f"{domain_class}VO.java"), Template(vo_tpl).substitute(ctx))
+        
+        ctx["field_declarations"] = field_declarations_add
+        write_file(os.path.join(domain_root, "dto/cmd", f"{domain_class}AddCmd.java"), Template(add_cmd_tpl).substitute(ctx))
+        
+        ctx["field_declarations"] = field_declarations_update
+        write_file(os.path.join(domain_root, "dto/cmd", f"{domain_class}UpdateCmd.java"), Template(update_cmd_tpl).substitute(ctx))
+        
+        ctx["field_declarations"] = field_declarations_query
+        write_file(os.path.join(domain_root, "dto/query", f"{domain_class}Page.java"), Template(page_query_tpl).substitute(ctx))
+
+if __name__ == "__main__":
+    main()

package/template/.hermes/skills/ask-matt/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ask-matt
+description: Ask which skill or flow fits your situation. A router over the skills in this repo.
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+You don't remember every skill, so ask.
+
+A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
+
+## The main flow: idea → ship
+
+The route most work travels. You have an idea and want it built.
+
+1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail.)
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions):
+   - **`/handoff`** out, then open a fresh session against that file,
+   - **`/prototype`** to answer the question with throwaway code,
+   - **`/handoff`** back what you learned, and reference it from the original idea thread.
+3. **Branch — is this a multi-session build?**
+   - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on.
+   - **No** → **`/implement`** right here, in the same context window.
+
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+
+### Context hygiene
+
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue.
+
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread.
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
+
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Issues that `/to-issues` produced are already agent-ready, so **don't triage them**.
+
+- **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
+
+## Codebase health
+
+Not feature work — upkeep.
+
+- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on.
+
+## Vocabulary underneath
+
+Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
+
+- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
+- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
+
+## Crossing sessions
+
+- **`/handoff`** — when a thread is full or you need to branch off (e.g. into a `/prototype` session), this compacts the conversation into a markdown file. You don't continue in place — you **open a new session and reference that file** to carry the context across. It's the bridge between context windows, in either direction. Use it when you want a **fresh session** but need the **current conversation preserved**.
+- **`/compact`** (built-in) — stay in the **same conversation**, letting the earlier turns be summarized. Use it at **intentional breaks between phases**, when you don't mind losing the verbatim history. Don't compact mid-phase — the agent can lose its way. `/handoff` forks; `/compact` continues.
+
+## Standalone
+
+Off the main flow entirely.
+
+- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo.
+- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway from day one — keep the answer, delete the code. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
+- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
+- **`/writing-great-skills`** — reference for writing and editing skills well.
+
+## Precondition
+
+**`/setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.