ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-spec-tools/scripts/target_query.py

@@ -0,0 +1,407 @@
+#!/usr/bin/env python3
+import sys
+
+sys.dont_write_bytecode = True
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+from queue_contract import (
+    COVERAGE_COLUMNS,
+    MAIN_COLUMNS,
+    SOURCE_TYPE_SCOPE_HINTS,
+    SUMMARY_COLUMNS,
+    SUMMARY_SCOPE_COLUMNS,
+    normalize_key,
+    normalize_doc_profile,
+    normalize_text,
+)
+
+
+def configure_stdio():
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            reconfigure(encoding="utf-8")
+
+
+def tokenize_scope(value):
+    return re.findall(r"[a-z0-9]+", normalize_key(value))
+
+
+def token_matches_hint(hint_token, token):
+    if token == hint_token:
+        return True
+    if token in {f"{hint_token}s", f"{hint_token}es"}:
+        return True
+    if hint_token.endswith("y") and token == f"{hint_token[:-1]}ies":
+        return True
+    return False
+
+
+def hint_matches_scope(hint, scope_tokens):
+    hint_tokens = tokenize_scope(hint)
+    if not hint_tokens:
+        return False
+    if len(hint_tokens) == 1:
+        return any(token_matches_hint(hint_tokens[0], token) for token in scope_tokens)
+    for index in range(0, len(scope_tokens) - len(hint_tokens) + 1):
+        if scope_tokens[index : index + len(hint_tokens)] == hint_tokens:
+            return True
+    return False
+
+
+def split_markdown_row(line):
+    line = line.strip()
+    if not line.startswith("|") or not line.endswith("|"):
+        return []
+    cells = []
+    current = []
+    escaped = False
+    for char in line[1:-1]:
+        if escaped:
+            current.append(char)
+            escaped = False
+        elif char == "\\":
+            escaped = True
+        elif char == "|":
+            cells.append("".join(current).strip())
+            current = []
+        else:
+            current.append(char)
+    cells.append("".join(current).strip())
+    return cells
+
+
+def is_separator(cells):
+    return bool(cells) and all(re.fullmatch(r":?-{3,}:?", cell.strip()) for cell in cells)
+
+
+def markdown_escape(value):
+    return normalize_text(value).replace("|", "\\|")
+
+
+def normalize_row(row):
+    normalized = {column: row.get(column, "") for column in MAIN_COLUMNS}
+    normalized["doc_profile"] = normalize_doc_profile(
+        normalized.get("doc_profile", ""), normalized.get("source_type", "")
+    )
+    return normalized
+
+
+def iter_markdown_tables(lines):
+    current_heading = ""
+    for index, line in enumerate(lines):
+        heading = re.match(r"^(#{1,6})\s+(.+?)\s*$", line)
+        if heading:
+            current_heading = heading.group(2).strip()
+            continue
+
+        header = split_markdown_row(line)
+        if not header or index + 1 >= len(lines):
+            continue
+        separator = split_markdown_row(lines[index + 1])
+        if len(separator) != len(header) or not is_separator(separator):
+            continue
+
+        rows = []
+        end_line = index + 2
+        for data_index in range(index + 2, len(lines)):
+            values = split_markdown_row(lines[data_index])
+            if len(values) != len(header):
+                break
+            rows.append(dict(zip(header, values)))
+            end_line = data_index + 1
+        yield {
+            "section": current_heading,
+            "columns": header,
+            "rows": rows,
+            "start_line": index + 1,
+            "end_line": end_line,
+        }
+
+
+def read_queue(path):
+    path = Path(path)
+    lines = path.read_text(encoding="utf-8-sig").splitlines()
+    main_rows = []
+    summary_rows = []
+    coverage_rows = []
+    table_meta = []
+
+    for table in iter_markdown_tables(lines):
+        table_meta.append(
+            {
+                "section": table["section"],
+                "columns": table["columns"],
+                "row_count": len(table["rows"]),
+                "start_line": table["start_line"],
+                "end_line": table["end_line"],
+            }
+        )
+        if table["columns"] == MAIN_COLUMNS:
+            main_rows = [normalize_row(row) for row in table["rows"]]
+        elif table["columns"] == SUMMARY_COLUMNS:
+            summary_rows = table["rows"]
+        elif table["columns"] == COVERAGE_COLUMNS:
+            coverage_rows = table["rows"]
+
+    if not main_rows:
+        raise SystemExit(f"No documentation target queue table found in {path}")
+    return {
+        "path": str(path),
+        "rows": main_rows,
+        "summary": summary_rows,
+        "coverage": coverage_rows,
+        "tables": table_meta,
+    }
+
+
+def row_text(row):
+    return "\n".join(str(value) for value in row.values())
+
+
+def matches_filters(row, args):
+    if args.id and normalize_key(row.get("id")) not in {normalize_key(value) for value in args.id}:
+        return False
+    if args.source_type and normalize_key(row.get("source_type")) not in {
+        normalize_key(value) for value in args.source_type
+    }:
+        return False
+    for field_name in ("group", "name", "entrypoint", "keyword"):
+        expected = getattr(args, field_name)
+        if expected and normalize_key(expected) not in normalize_key(row.get(field_name)):
+            return False
+    if args.query and normalize_key(args.query) not in normalize_key(row_text(row)):
+        return False
+    if args.foundation and normalize_key(row.get("foundation_doc_status")) != normalize_key(args.foundation):
+        return False
+    if args.architecture and normalize_key(row.get("architecture_doc_status")) != normalize_key(args.architecture):
+        return False
+    if args.ops and normalize_key(row.get("ops_doc_status")) != normalize_key(args.ops):
+        return False
+    if args.review and normalize_key(row.get("review_status")) != normalize_key(args.review):
+        return False
+    if args.profile and normalize_key(row.get("doc_profile")) != normalize_key(args.profile):
+        return False
+    if args.completed and normalize_key(row.get("document_completed_flag(Y/N)")) != normalize_key(args.completed):
+        return False
+    return True
+
+
+def find_rows(queue, args):
+    rows = [row for row in queue["rows"] if matches_filters(row, args)]
+    if args.limit is not None:
+        rows = rows[: args.limit]
+    return rows
+
+
+def get_row(rows, target_id):
+    for row in rows:
+        if normalize_key(row.get("id")) == normalize_key(target_id):
+            return row
+    raise SystemExit(f"Target id not found: {target_id}")
+
+
+def basename_handle(value):
+    text = normalize_text(value).strip("`")
+    text = text.replace("\\", "/")
+    if "/" in text:
+        return text.rsplit("/", 1)[-1].casefold()
+    return text.casefold()
+
+
+def related_reasons(seed, candidate):
+    reasons = []
+    for field_name in ("group", "entrypoint", "keyword", "document_path", "name"):
+        left = normalize_key(seed.get(field_name))
+        right = normalize_key(candidate.get(field_name))
+        if left and left == right:
+            reasons.append(f"same_{field_name}")
+    seed_base = basename_handle(seed.get("entrypoint", ""))
+    candidate_base = basename_handle(candidate.get("entrypoint", ""))
+    if seed_base and seed_base == candidate_base and "same_entrypoint" not in reasons:
+        reasons.append("same_entrypoint_basename")
+    return reasons
+
+
+def related_rows(queue, target_id, limit, include_self):
+    seed = get_row(queue["rows"], target_id)
+    related = []
+    for row in queue["rows"]:
+        if normalize_key(row.get("id")) == normalize_key(seed.get("id")) and not include_self:
+            continue
+        reasons = related_reasons(seed, row)
+        if reasons:
+            item = dict(row)
+            item["related_reasons"] = reasons
+            related.append(item)
+    related.sort(key=lambda row: (len(row["related_reasons"]) * -1, row.get("id", "")))
+    if limit is not None:
+        related = related[:limit]
+    return seed, related
+
+
+def source_summary_for_row(queue, row):
+    source_type = normalize_key(row.get("source_type"))
+    hints = SOURCE_TYPE_SCOPE_HINTS.get(source_type, [source_type])
+    matched = []
+    for summary in queue["summary"]:
+        scope_tokens = tokenize_scope(" ".join(summary.get(column, "") for column in SUMMARY_SCOPE_COLUMNS))
+        if any(hint_matches_scope(hint, scope_tokens) for hint in hints):
+            matched.append(summary)
+    return matched
+
+
+def coverage_for_row(queue, row):
+    terms = [
+        row.get("id"),
+        row.get("source_type"),
+        row.get("group"),
+        row.get("name"),
+        row.get("entrypoint"),
+        row.get("keyword"),
+    ]
+    normalized_terms = [normalize_key(term) for term in terms if normalize_key(term)]
+    matched = []
+    for coverage in queue["coverage"]:
+        haystack = normalize_key(" ".join(coverage.values()))
+        if any(term in haystack for term in normalized_terms):
+            matched.append(coverage)
+    return matched
+
+
+def render_table(rows, columns):
+    lines = []
+    lines.append("| " + " | ".join(columns) + " |")
+    lines.append("| " + " | ".join("---" for _ in columns) + " |")
+    for row in rows:
+        lines.append("| " + " | ".join(markdown_escape(row.get(column, "")) for column in columns) + " |")
+    return "\n".join(lines)
+
+
+def print_output(payload, output_format, columns=None):
+    if output_format == "json":
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return
+    if isinstance(payload, dict) and "rows" in payload:
+        rows = payload["rows"]
+    elif isinstance(payload, list):
+        rows = payload
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return
+    if not rows:
+        print("(no rows)")
+        return
+    selected_columns = columns or [column for column in MAIN_COLUMNS if column in rows[0]]
+    extra_columns = [column for column in rows[0].keys() if column not in selected_columns]
+    print(render_table(rows, selected_columns + extra_columns))
+
+
+def command_find(args):
+    queue = read_queue(args.queue)
+    rows = find_rows(queue, args)
+    print_output({"queue": queue["path"], "count": len(rows), "rows": rows}, args.output)
+
+
+def command_related(args):
+    queue = read_queue(args.queue)
+    seed, rows = related_rows(queue, args.id, args.limit, args.include_self)
+    print_output(
+        {
+            "queue": queue["path"],
+            "target": seed,
+            "count": len(rows),
+            "rows": rows,
+        },
+        args.output,
+    )
+
+
+def command_preflight(args):
+    queue = read_queue(args.queue)
+    row = get_row(queue["rows"], args.id)
+    _, related = related_rows(queue, args.id, args.related_limit, False)
+    payload = {
+        "queue": queue["path"],
+        "target": row,
+        "source_acquisition_summary": source_summary_for_row(queue, row),
+        "coverage_review": coverage_for_row(queue, row),
+        "related_rows": related,
+    }
+    print_output(payload, args.output)
+
+
+def command_sections(args):
+    queue = read_queue(args.queue)
+    payload = {
+        "queue": queue["path"],
+        "tables": queue["tables"],
+        "source_acquisition_summary": queue["summary"],
+        "coverage_review": queue["coverage"],
+    }
+    print_output(payload, args.output)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        description="Query docs/docs-target-queue.md rows and preflight context without manual table scanning."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    find = subparsers.add_parser("find", help="Find queue target rows by id, text, type, status, or handle.")
+    find.add_argument("--queue", default="docs/docs-target-queue.md")
+    find.add_argument("--id", action="append")
+    find.add_argument("--query")
+    find.add_argument("--source-type", action="append")
+    find.add_argument("--group")
+    find.add_argument("--name")
+    find.add_argument("--entrypoint")
+    find.add_argument("--keyword")
+    find.add_argument("--foundation")
+    find.add_argument("--architecture")
+    find.add_argument("--ops")
+    find.add_argument("--review")
+    find.add_argument("--profile")
+    find.add_argument("--completed")
+    find.add_argument("--limit", type=int)
+    find.add_argument("--output", choices=("json", "markdown"), default="json")
+    find.set_defaults(func=command_find)
+
+    related = subparsers.add_parser("related", help="Find queue rows related to one target row.")
+    related.add_argument("--queue", default="docs/docs-target-queue.md")
+    related.add_argument("--id", required=True)
+    related.add_argument("--limit", type=int, default=25)
+    related.add_argument("--include-self", action="store_true")
+    related.add_argument("--output", choices=("json", "markdown"), default="json")
+    related.set_defaults(func=command_related)
+
+    preflight = subparsers.add_parser("preflight", help="Build target preflight context from queue summary and rows.")
+    preflight.add_argument("--queue", default="docs/docs-target-queue.md")
+    preflight.add_argument("--id", required=True)
+    preflight.add_argument("--related-limit", type=int, default=25)
+    preflight.add_argument("--output", choices=("json", "markdown"), default="json")
+    preflight.set_defaults(func=command_preflight)
+
+    sections = subparsers.add_parser("sections", help="Show parsed queue sections and supporting tables.")
+    sections.add_argument("--queue", default="docs/docs-target-queue.md")
+    sections.add_argument("--output", choices=("json", "markdown"), default="json")
+    sections.set_defaults(func=command_sections)
+    return parser
+
+
+def main():
+    configure_stdio()
+    args = build_parser().parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except BrokenPipeError:
+        sys.exit(1)

package/.github/skills/source-code-to-system-ops-overview/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: source-code-to-system-ops-overview
+description: 當需要根據 source code、SQL、設定檔、部署線索、依賴檔、Log keyword、錯誤訊息或既有文件，產生、更新或審查系統層級維運總覽文件時使用。適用於 web、mobile app、desktop application、DB SQL/database program、ERP、batch、CLI、integration service 等系統型態，以及 Java、C#、JavaScript/TypeScript、SQL、PL/SQL、Python 等技術棧；重點是建立 system-level operations overview、module inventory、runtime/config/integration/error/log/triage summary 與 source-backed boundary，而不是單一功能細節。
+---
+
+# Source Code to System Ops Overview
+
+## Purpose
+
+使用這個 skill 依據 source code、config、deployment artifact、dependency file、SQL、database object、Log keyword、error message 與既有文件，產生或審查 `S01 系統維運總覽文件`。
+
+本 skill 的輸出是系統層級維運總覽，用來協助 L1/L2 Support、維運工程師、系統負責人、交接人員、QA 或 PM 快速判斷系統邊界、module、runtime/config、external integration、error/log clue 與第一查找方向。
+
+輸出與說明使用繁體中文。Source code、class name、method name、variable name、API path、SQL、database object、YAML/JSON/XML key、CLI command、Git command、protocol name、tool name、prompt placeholder、Markdown syntax 與 Mermaid syntax 必須保留英文或原始語法。
+
+## Reference Guideline
+
+主要 reference guideline：
+
+| Reference | Responsibility |
+|---|---|
+| `references/system-operations-overview-guideline.md` | 定義系統層級維運總覽的文件邊界、跨系統型態適用原則、章節架構、表格欄位、禁止混入的功能層內容與品質檢查。 |
+
+產生、更新或審查系統層級維運總覽前，先載入此 reference guideline。不要把 guideline-only 的欄位說明、撰寫要求或品質檢查文字逐字輸出到最終文件。
+
+## Scope Boundary
+
+輸出範圍是系統層級 source-backed overview、module / function inventory、navigation、triage map 與 evidence boundary。單一功能、API、job、screen、SQL routine、ERP customization 或 external interface 的完整流程若可由來源確認，應導向功能層 SPEC、API 文件、batch 文件、database routine 文件或正式 SOP；系統總覽只保留能支援系統層分流的入口、模組、可觀測線索、coverage gap 與文件連結。
+
+若使用者要求下列內容，應改用功能層 SPEC、API 文件、batch 文件、database routine 文件、正式 SOP，或在系統總覽中只留下導覽連結與 `Manual Required`：
+
+- request / response field mapping
+- 完整 SQL 查詢條件或資料修復語句
+- 單一功能 validation rule、status transition 或 error handling flow
+- production rerun / rollback / data fix SOP
+- 正式 SLA、owner、escalation window 或監控閾值
+
+## Workflow
+
+1. 確認使用者的 source root、目標系統範圍、既有文件與預期輸出位置；若未指定輸出檔，使用專案慣例或建議 `docs/system-operations-overview.md`。
+2. 載入 `references/system-operations-overview-guideline.md`，確認章節邊界、來源標示、禁止內容與品質檢查。
+3. 掃描可確認來源，優先使用 `rg`、build/dependency files、config files、deployment files、entrypoints、route/job/screen/script/database object 線索與既有文件。
+4. 依系統型態整理 source evidence，不預設一定是 web 或 Java：
+   - web/API：route、controller、middleware、service、dependency、config。
+   - mobile app / desktop application：screen、view model、event handler、local config、installer/package metadata。
+   - DB SQL / database program：schema、table、view、stored procedure、function、trigger、job、SQL script。
+   - ERP / packaged system：module、customization、interface program、report、batch job、table extension、exported metadata。
+   - batch / CLI / integration service：scheduler、script、queue/topic、file path、external endpoint、job log。
+5. 產出文件時，每個重要結論都標示可回查來源位置；無法由 source 確認的正式規則列入人工補充項目，不輸出額外判斷欄位。
+6. 無法確認的 runtime truth、production rule、owner、SLA、credential、formal SOP 或 monitoring threshold，一律寫成「無法由目前來源確認」或列入人工補充項目，不要用命名推論補完。
+7. 對既有系統總覽做更新時，先比對現有內容與目前 source evidence；保留仍正確的段落，修正過期、無證據、過度功能層化或洩漏 secret value 的內容。
+8. 完成前依 reference guideline 的品質檢查逐項審查，特別確認沒有 secret value、production 操作指令、單一功能完整流程或無來源的關鍵結論。
+
+## Output Contract
+
+最終文件應優先包含下列章節；若某章不適用，保留簡短 `N/A` 或說明「無法由目前來源確認」，不要硬填推測內容。
+
+1. `系統用途與邊界`
+2. `系統主要模組與功能清單`
+3. `技術與執行環境線索`
+4. `系統設定與環境參數`
+5. `外部介面與整合點摘要`
+6. `錯誤訊息、Exception 與 Log 線索摘要`
+7. `維運初步分流判斷`
+8. `Source Code 證據範圍與人工補充項目`
+
+文件應是 narrative-first 加上必要 inventory tables。表格用來支援查找與交接，不應變成無來源的大量猜測清單。
+
+## Quality Gate
+
+完成前檢查：
+
+- `SKILL.md` frontmatter 只有 `name` 與 `description`。
+- `SKILL.md` 引用的 reference file 實際存在。
+- 最終文件是 system-level overview，不是功能層 SPEC 或 runbook。
+- web、Java、Spring、REST 或 server deployment 沒有被當成所有系統的預設前提。
+- Java、C#、JavaScript/TypeScript、SQL、PL/SQL、Python、ERP metadata 或其他 technical identifiers 保留原文。
+- Secret value、password、token、private key、certificate content 沒有被輸出。
+- 每個重要 module、config、integration、error/log、triage 結論都有來源位置；無法確認的項目列入 coverage gaps 或人工補充項目。
+- 沒有把猜測寫成已確認事實。
+
+若 validator 可用，針對 skill 目錄執行 skill validation；若沒有 validator，至少用 `git diff --check` 檢查 Markdown 空白與格式問題。