@hunyed15/codecgc 0.1.0

package/scripts/write_codecgc_decision.py

@@ -0,0 +1,83 @@
+import argparse
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_governance_dedupe import has_existing_governance_entry
+
+
+def resolve_decision_path() -> Path:
+    return artifact_output_root("product") / "compound" / "codecgc-decisions.md"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把一条长期有效的已确认决定写入 codecgc/compound/codecgc-decisions.md。"
+    )
+    parser.add_argument("--summary", required=True, help="一行决定摘要。")
+    parser.add_argument("--constraint", default="", help="这条决定会约束哪些后续行为。")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    return parser
+
+
+def ensure_parent(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def ensure_document(path: Path) -> None:
+    if path.exists():
+        return
+    ensure_parent(path)
+    path.write_text(
+        "# CodeCGC 长期决策\n\n"
+        "该文件用于记录当前仓库的长期有效决定。\n\n"
+        "## 条目\n\n",
+        encoding="utf-8",
+    )
+
+
+def has_existing_entry(existing: str, summary: str) -> bool:
+    return has_existing_governance_entry(existing, summary, field_labels=["Decision", "决定"])
+
+
+def append_decision(path: Path, summary: str, constraint: str, source: str) -> dict[str, str]:
+    ensure_document(path)
+    cleaned_summary = summary.strip()
+    existing = path.read_text(encoding="utf-8")
+    if has_existing_entry(existing, cleaned_summary):
+        return {
+            "path": str(path),
+            "summary": cleaned_summary,
+            "constraint": constraint.strip(),
+            "source": source.strip(),
+            "created": "false",
+        }
+
+    lines = [f"### {cleaned_summary}", "", f"- 决定: {cleaned_summary}"]
+    if constraint.strip():
+        lines.append(f"- 约束: {constraint.strip()}")
+    if source.strip():
+        lines.append(f"- 来源: {source.strip()}")
+    lines.append("")
+
+    path.write_text(existing + "\n".join(lines), encoding="utf-8")
+    return {
+        "path": str(path),
+        "summary": cleaned_summary,
+        "constraint": constraint.strip(),
+        "source": source.strip(),
+        "created": "true",
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    result = append_decision(resolve_decision_path(), args.summary, args.constraint, args.source)
+    print_json({"success": True, "decision": result})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/write_codecgc_explore.py

@@ -0,0 +1,118 @@
+import argparse
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_governance_dedupe import has_existing_governance_entry
+
+
+def resolve_explore_path() -> Path:
+    return artifact_output_root("product") / "compound" / "codecgc-explorations.md"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把一条定向代码探索请求写入 codecgc/compound/codecgc-explorations.md。"
+    )
+    parser.add_argument("--summary", required=True, help="一行 explore 摘要。")
+    parser.add_argument("--kind", choices=["question", "module-overview", "spike"], default="question")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    parser.add_argument("--artifact-path", default="", help="已有 explore 文件路径；传入时进入补充完善模式。")
+    parser.add_argument("--question-detail", default="", help="补充核心问题。")
+    parser.add_argument("--target-modules", default="", help="补充目标模块、目录或文件。")
+    parser.add_argument("--expected-output", default="", help="补充预期输出形式。")
+    parser.add_argument("--append-note", default="", help="无法结构化时，附加到 explore 条目的补充说明。")
+    return parser
+
+
+def ensure_document(path: Path) -> None:
+    if path.exists():
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "# CodeCGC Explorations\n\n"
+        "该文件用于记录待做或已登记的定向代码探索请求。\n\n"
+        "## 条目\n\n",
+        encoding="utf-8",
+    )
+
+
+def has_existing_entry(existing: str, summary: str) -> bool:
+    return has_existing_governance_entry(existing, summary, field_labels=["摘要"])
+
+
+def append_exploration(path: Path, summary: str, kind: str, source: str) -> dict[str, str]:
+    ensure_document(path)
+    cleaned_summary = summary.strip()
+    existing = path.read_text(encoding="utf-8")
+    if has_existing_entry(existing, cleaned_summary):
+        return {
+            "path": str(path),
+            "summary": cleaned_summary,
+            "kind": kind.strip(),
+            "source": source.strip(),
+            "created": "false",
+        }
+
+    lines = [f"### {cleaned_summary}", "", f"- 类型: {kind.strip()}", f"- 摘要: {cleaned_summary}"]
+    if source.strip():
+        lines.append(f"- 来源: {source.strip()}")
+    lines.append("")
+
+    path.write_text(existing + "\n".join(lines), encoding="utf-8")
+    return {
+        "path": str(path),
+        "summary": cleaned_summary,
+        "kind": kind.strip(),
+        "source": source.strip(),
+        "created": "true",
+    }
+
+
+def update_exploration(path: Path, question_detail: str, target_modules: str, expected_output: str, append_note: str) -> dict[str, str]:
+    if not path.exists():
+        raise FileNotFoundError(f"Explore file not found: {path}")
+    content = path.read_text(encoding="utf-8")
+    lines: list[str] = []
+    if question_detail.strip():
+        lines.append(f"- 核心问题: {question_detail.strip()}")
+    if target_modules.strip():
+        lines.append(f"- 目标模块: {target_modules.strip()}")
+    if expected_output.strip():
+        lines.append(f"- 预期输出: {expected_output.strip()}")
+    if append_note.strip():
+        lines.append(f"- 补充说明: {append_note.strip()}")
+    if lines:
+        content = content.rstrip() + "\n" + "\n".join(lines) + "\n"
+        path.write_text(content, encoding="utf-8")
+    return {
+        "path": str(path),
+        "updated": "true",
+        "question_detail": question_detail.strip(),
+        "target_modules": target_modules.strip(),
+        "expected_output": expected_output.strip(),
+        "append_note": append_note.strip(),
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    if args.artifact_path.strip():
+        result = update_exploration(
+            Path(args.artifact_path),
+            args.question_detail,
+            args.target_modules,
+            args.expected_output,
+            args.append_note,
+        )
+        print_json({"success": True, "explore": result})
+        return 0
+    result = append_exploration(resolve_explore_path(), args.summary, args.kind, args.source)
+    print_json({"success": True, "explore": result})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/write_codecgc_guide.py

@@ -0,0 +1,141 @@
+import argparse
+import re
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+
+
+def slugify(value: str) -> str:
+    normalized = value.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = re.sub(r"-{2,}", "-", normalized).strip("-")
+    return normalized or "guide"
+
+
+def resolve_docs_root() -> Path:
+    return artifact_output_root("product") / "docs"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把一条面向用户或开发者的指南请求写入 codecgc/docs/ 下的 guide 文档。"
+    )
+    parser.add_argument("--summary", required=True, help="一行 guide 摘要。")
+    parser.add_argument("--audience", choices=["user", "developer"], default="developer")
+    parser.add_argument("--note", default="", help="可选的指南用途说明。")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    parser.add_argument("--artifact-path", default="", help="已有 guide 文件路径；传入时进入补充完善模式。")
+    parser.add_argument("--purpose", default="", help="补充 guide 的目的说明。")
+    parser.add_argument("--steps", default="", help="补充 guide 的使用步骤。")
+    parser.add_argument("--boundary", default="", help="补充 guide 的边界或前置条件。")
+    parser.add_argument("--append-note", default="", help="无法结构化时，附加到 guide 的补充说明。")
+    return parser
+
+
+def ensure_parent(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def write_guide(path: Path, summary: str, audience: str, note: str, source: str) -> dict[str, str]:
+    ensure_parent(path)
+    created = not path.exists()
+    if created:
+        title = summary.strip()
+        lines = [
+            f"# {title}",
+            "",
+            f"- Audience: {'开发者' if audience == 'developer' else '用户'}",
+            f"- 摘要: {title}",
+        ]
+        if note.strip():
+            lines.append(f"- 用途: {note.strip()}")
+        if source.strip():
+            lines.append(f"- 来源: {source.strip()}")
+        lines.extend(
+            [
+                "",
+                "## 1. 目的",
+                "",
+                "待补充。",
+                "",
+                "## 2. 使用步骤",
+                "",
+                "待补充。",
+                "",
+            ]
+        )
+        path.write_text("\n".join(lines), encoding="utf-8")
+
+    return {
+        "path": str(path),
+        "summary": summary.strip(),
+        "audience": audience,
+        "note": note.strip(),
+        "source": source.strip(),
+        "created": "true" if created else "false",
+    }
+
+
+def replace_section(text: str, heading: str, body: str) -> str:
+    pattern = rf"({re.escape(heading)}\n\n)(.*?)(?=\n## |\Z)"
+    match = re.search(pattern, text, flags=re.DOTALL)
+    if match:
+        return text[:match.start()] + f"{heading}\n\n{body.strip()}\n" + text[match.end():]
+    stripped = text.rstrip()
+    suffix = "\n\n" if stripped else ""
+    return f"{stripped}{suffix}{heading}\n\n{body.strip()}\n"
+
+
+def update_guide(path: Path, purpose: str, steps: str, boundary: str, append_note: str) -> dict[str, str]:
+    if not path.exists():
+        raise FileNotFoundError(f"Guide file not found: {path}")
+    content = path.read_text(encoding="utf-8")
+    if purpose.strip():
+        content = replace_section(content, "## 1. 目的", purpose.strip())
+    if steps.strip():
+        content = replace_section(content, "## 2. 使用步骤", steps.strip())
+    if boundary.strip():
+        content = replace_section(content, "## 3. 使用边界", boundary.strip())
+    elif "## 3. 使用边界" not in content and append_note.strip():
+        content = replace_section(content, "## 3. 使用边界", append_note.strip())
+        append_note = ""
+    if append_note.strip():
+        note_block = f"## 4. 补充说明\n\n{append_note.strip()}\n"
+        if "## 4. 补充说明" in content:
+            content = replace_section(content, "## 4. 补充说明", append_note.strip())
+        else:
+            content = content.rstrip() + "\n\n" + note_block
+    path.write_text(content, encoding="utf-8")
+    return {
+        "path": str(path),
+        "updated": "true",
+        "purpose": purpose.strip(),
+        "steps": steps.strip(),
+        "boundary": boundary.strip(),
+        "append_note": append_note.strip(),
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    if args.artifact_path.strip():
+        result = update_guide(
+            Path(args.artifact_path),
+            args.purpose,
+            args.steps,
+            args.boundary,
+            args.append_note,
+        )
+        print_json({"success": True, "guide": result})
+        return 0
+    filename = f"{slugify(args.summary)}-guide.md"
+    result = write_guide(resolve_docs_root() / filename, args.summary, args.audience, args.note, args.source)
+    print_json({"success": True, "guide": result})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/write_codecgc_learning.py

@@ -0,0 +1,87 @@
+import argparse
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_governance_dedupe import has_existing_governance_entry
+
+
+def resolve_learning_path() -> Path:
+    return artifact_output_root("product") / "compound" / "codecgc-learning-log.md"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把一条可复用经验写入 codecgc/compound/codecgc-learning-log.md。"
+    )
+    parser.add_argument("--summary", required=True, help="一行经验摘要。")
+    parser.add_argument("--kind", choices=["pitfall", "practice"], default="practice")
+    parser.add_argument("--instruction", default="", help="简短的可复用后续指引。")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    return parser
+
+
+def ensure_parent(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def ensure_document(path: Path) -> None:
+    if path.exists():
+        return
+    ensure_parent(path)
+    path.write_text(
+        "# CodeCGC 经验沉淀\n\n"
+        "该文件用于记录当前仓库可复用的经验、坑点和推荐做法。\n\n"
+        "## 条目\n\n",
+        encoding="utf-8",
+    )
+
+
+def has_existing_entry(existing: str, summary: str) -> bool:
+    return has_existing_governance_entry(existing, summary, field_labels=["Summary", "摘要"])
+
+
+def append_learning(path: Path, summary: str, kind: str, instruction: str, source: str) -> dict[str, str]:
+    ensure_document(path)
+    cleaned_summary = summary.strip()
+    existing = path.read_text(encoding="utf-8")
+    if has_existing_entry(existing, cleaned_summary):
+        return {
+            "path": str(path),
+            "summary": cleaned_summary,
+            "kind": kind.strip(),
+            "instruction": instruction.strip(),
+            "source": source.strip(),
+            "created": "false",
+        }
+
+    kind_label = "坑点" if kind.strip() == "pitfall" else "实践"
+    lines = [f"### {cleaned_summary}", "", f"- 类型: {kind_label}", f"- 摘要: {cleaned_summary}"]
+    if instruction.strip():
+        lines.append(f"- 后续指引: {instruction.strip()}")
+    if source.strip():
+        lines.append(f"- 来源: {source.strip()}")
+    lines.append("")
+
+    path.write_text(existing + "\n".join(lines), encoding="utf-8")
+    return {
+        "path": str(path),
+        "summary": cleaned_summary,
+        "kind": kind.strip(),
+        "instruction": instruction.strip(),
+        "source": source.strip(),
+        "created": "true",
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    result = append_learning(resolve_learning_path(), args.summary, args.kind, args.instruction, args.source)
+    print_json({"success": True, "learning": result})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/write_codecgc_libdoc.py

@@ -0,0 +1,140 @@
+import argparse
+import re
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+
+
+def slugify(value: str) -> str:
+    normalized = value.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = re.sub(r"-{2,}", "-", normalized).strip("-")
+    return normalized or "libdoc"
+
+
+def resolve_reference_root() -> Path:
+    return artifact_output_root("product") / "reference"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把一条 API/组件/命令参考文档请求写入 codecgc/reference/ 下的 libdoc 文档。"
+    )
+    parser.add_argument("--summary", required=True, help="一行 libdoc 摘要。")
+    parser.add_argument("--surface", default="public-api", help="可选的公开表面类型说明。")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    parser.add_argument("--artifact-path", default="", help="已有 libdoc 文件路径；传入时进入补充完善模式。")
+    parser.add_argument("--entry", default="", help="补充入口说明。")
+    parser.add_argument("--contract", default="", help="补充公开契约说明。")
+    parser.add_argument("--example", default="", help="补充最小示例说明。")
+    parser.add_argument("--boundary", default="", help="补充边界说明。")
+    parser.add_argument("--append-note", default="", help="无法结构化时，附加到 libdoc 的补充说明。")
+    return parser
+
+
+def ensure_parent(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def write_libdoc(path: Path, summary: str, surface: str, source: str) -> dict[str, str]:
+    ensure_parent(path)
+    created = not path.exists()
+    if created:
+        title = summary.strip()
+        lines = [
+            f"# {title}",
+            "",
+            f"- 表面类型: {surface.strip() or 'public-api'}",
+            f"- 摘要: {title}",
+        ]
+        if source.strip():
+            lines.append(f"- 来源: {source.strip()}")
+        lines.extend(
+            [
+                "",
+                "## 1. 入口",
+                "",
+                "待补充。",
+                "",
+                "## 2. 公开契约",
+                "",
+                "待补充。",
+                "",
+            ]
+        )
+        path.write_text("\n".join(lines), encoding="utf-8")
+
+    return {
+        "path": str(path),
+        "summary": summary.strip(),
+        "surface": surface.strip() or "public-api",
+        "source": source.strip(),
+        "created": "true" if created else "false",
+    }
+
+
+def replace_section(text: str, heading: str, body: str) -> str:
+    pattern = rf"({re.escape(heading)}\n\n)(.*?)(?=\n## |\Z)"
+    match = re.search(pattern, text, flags=re.DOTALL)
+    if match:
+        return text[:match.start()] + f"{heading}\n\n{body.strip()}\n" + text[match.end():]
+    stripped = text.rstrip()
+    suffix = "\n\n" if stripped else ""
+    return f"{stripped}{suffix}{heading}\n\n{body.strip()}\n"
+
+
+def update_libdoc(path: Path, entry: str, contract: str, example: str, boundary: str, append_note: str) -> dict[str, str]:
+    if not path.exists():
+        raise FileNotFoundError(f"Libdoc file not found: {path}")
+    content = path.read_text(encoding="utf-8")
+    if entry.strip():
+        content = replace_section(content, "## 1. 入口", entry.strip())
+    if contract.strip():
+        content = replace_section(content, "## 2. 公开契约", contract.strip())
+    combined = "\n\n".join(part for part in [example.strip(), boundary.strip()] if part)
+    if combined:
+        content = replace_section(content, "## 3. 示例与边界", combined)
+    elif "## 3. 示例与边界" not in content and append_note.strip():
+        content = replace_section(content, "## 3. 示例与边界", append_note.strip())
+        append_note = ""
+    if append_note.strip():
+        if "## 4. 补充说明" in content:
+            content = replace_section(content, "## 4. 补充说明", append_note.strip())
+        else:
+            content = content.rstrip() + f"\n\n## 4. 补充说明\n\n{append_note.strip()}\n"
+    path.write_text(content, encoding="utf-8")
+    return {
+        "path": str(path),
+        "updated": "true",
+        "entry": entry.strip(),
+        "contract": contract.strip(),
+        "example": example.strip(),
+        "boundary": boundary.strip(),
+        "append_note": append_note.strip(),
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    if args.artifact_path.strip():
+        result = update_libdoc(
+            Path(args.artifact_path),
+            args.entry,
+            args.contract,
+            args.example,
+            args.boundary,
+            args.append_note,
+        )
+        print_json({"success": True, "libdoc": result})
+        return 0
+    filename = f"{slugify(args.summary)}-libdoc.md"
+    result = write_libdoc(resolve_reference_root() / filename, args.summary, args.surface, args.source)
+    print_json({"success": True, "libdoc": result})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/write_codecgc_refactor.py

@@ -0,0 +1,78 @@
+import argparse
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_governance_dedupe import has_existing_governance_entry
+
+
+SECTION_HEADING = "## 7. Refactor Queue"
+
+
+def resolve_refactor_path() -> Path:
+    return artifact_output_root("product") / "compound" / "codecgc-productization-gap.md"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把一条保持行为不变的长期重构候选写入 codecgc/compound/codecgc-productization-gap.md。"
+    )
+    parser.add_argument("--summary", required=True, help="一行重构摘要。")
+    parser.add_argument("--note", default="", help="可选的“保持行为不变”约束说明。")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    return parser
+
+
+def ensure_refactor_section(text: str) -> str:
+    if SECTION_HEADING in text:
+        return text
+    stripped = text.rstrip()
+    suffix = "\n\n" if stripped else ""
+    return f"{stripped}{suffix}{SECTION_HEADING}\n\n"
+
+
+def has_existing_entry(existing: str, summary: str) -> bool:
+    return has_existing_governance_entry(existing, summary, field_labels=["Summary", "摘要"])
+
+
+def append_refactor_candidate(path: Path, summary: str, note: str, source: str) -> dict[str, str]:
+    existing = path.read_text(encoding="utf-8")
+    ensured = ensure_refactor_section(existing)
+    cleaned_summary = summary.strip()
+    if has_existing_entry(ensured, cleaned_summary):
+        return {
+            "path": str(path),
+            "summary": cleaned_summary,
+            "note": note.strip(),
+            "source": source.strip(),
+            "created": "false",
+        }
+
+    lines = [f"### {cleaned_summary}", "", f"- 摘要: {cleaned_summary}"]
+    if note.strip():
+        lines.append(f"- 保持行为不变说明: {note.strip()}")
+    if source.strip():
+        lines.append(f"- 来源: {source.strip()}")
+    lines.append("")
+
+    path.write_text(ensured + "\n".join(lines), encoding="utf-8")
+    return {
+        "path": str(path),
+        "summary": cleaned_summary,
+        "note": note.strip(),
+        "source": source.strip(),
+        "created": "true",
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    result = append_refactor_candidate(resolve_refactor_path(), args.summary, args.note, args.source)
+    print_json({"success": True, "refactor": result})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())