@scemoon/cdh 1.0.6 → 1.0.7

package/cdh/scaffold.py

@@ -1,728 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-
-import yaml
-
-
-SKILL_NAME = "ai-dlc-skill"
-
-
-@dataclass(frozen=True)
-class ComponentSpec:
-    id: str
-    kind: str
-    owns: str
-    fr_prefix: str
-    tech: str
-    label: str
-    description: str
-
-
-@dataclass(frozen=True)
-class CrossCutSpec:
-    id: str
-    paths: tuple[str, ...]
-    label: str
-    description: str
-
-
-COMPONENTS: tuple[ComponentSpec, ...] = (
-    ComponentSpec(
-        id="native",
-        kind="mobile",
-        owns="apps/native",
-        fr_prefix="NATIVE",
-        tech="react-native | flutter",
-        label="Mobile App",
-        description="iOS/Android cross-platform (RN/Flutter)",
-    ),
-    ComponentSpec(
-        id="desktop",
-        kind="desktop",
-        owns="apps/desktop",
-        fr_prefix="DESKTOP",
-        tech="electron | tauri",
-        label="Desktop App",
-        description="Cross-platform desktop (Electron/Tauri)",
-    ),
-    ComponentSpec(
-        id="web",
-        kind="frontend",
-        owns="apps/web",
-        fr_prefix="WEB",
-        tech="react | vue | svelte",
-        label="Web Frontend",
-        description="Browser SPA/SSR (React/Vue/Svelte)",
-    ),
-    ComponentSpec(
-        id="backend",
-        kind="service",
-        owns="apps/backend",
-        fr_prefix="BE",
-        tech="python | node | go",
-        label="Backend Service",
-        description="HTTP API/microservice (Python/Node/Go)",
-    ),
-    ComponentSpec(
-        id="wxa",
-        kind="mini-program",
-        owns="apps/wxa",
-        fr_prefix="WXA",
-        tech="miniprogram",
-        label="WeChat Mini-Program",
-        description="WeChat ecosystem mini-program",
-    ),
-    ComponentSpec(
-        id="mya",
-        kind="mini-program",
-        owns="apps/mya",
-        fr_prefix="MYA",
-        tech="miniprogram",
-        label="Alipay Mini-Program",
-        description="Alipay ecosystem mini-program",
-    ),
-    ComponentSpec(
-        id="tta",
-        kind="mini-program",
-        owns="apps/tta",
-        fr_prefix="TTA",
-        tech="miniprogram",
-        label="TikTok Mini-Program",
-        description="TikTok/Douyin ecosystem mini-program",
-    ),
-)
-
-
-COMPONENT_BY_ID: dict[str, ComponentSpec] = {c.id: c for c in COMPONENTS}
-
-
-CROSS_CUTTING: tuple[CrossCutSpec, ...] = (
-    CrossCutSpec(
-        id="contracts",
-        paths=("aidlc/contracts/CHANGELOG.md",),
-        label="Interface Contracts",
-        description="API/event contracts and changelog",
-    ),
-    CrossCutSpec(
-        id="shared",
-        paths=("aidlc/packages/shared",),
-        label="Shared Types",
-        description="Cross-component shared types package",
-    ),
-    CrossCutSpec(
-        id="openspec",
-        paths=(),
-        label="OpenSpec Changes",
-        description="OpenSpec change proposals",
-    ),
-    CrossCutSpec(
-        id="cross_stack_features",
-        paths=(),
-        label="Cross-Stack BDD",
-        description="End-to-end BDD features across components",
-    ),
-    CrossCutSpec(
-        id="cross_stack_tests",
-        paths=("aidlc/tests/contract", "aidlc/tests/cross-stack"),
-        label="Cross-Stack Tests",
-        description="Contract tests and cross-stack integration tests",
-    ),
-    CrossCutSpec(
-        id="provider",
-        paths=(
-            "aidlc/providers/tcb/provider.yaml",
-            "aidlc/providers/tcb/deployment.yaml",
-            "aidlc/providers/tcb/preview.yaml",
-        ),
-        label="Cloud Provider",
-        description="TCB (Tencent CloudBase) provider config",
-    ),
-    CrossCutSpec(
-        id="tools",
-        paths=(
-            "aidlc/tools/deploy_stack.py",
-            "aidlc/tools/contract_diff.py",
-            "aidlc/tools/generate_shared.py",
-        ),
-        label="Tooling Scripts",
-        description="deploy_stack / contract_diff / generate_shared stubs",
-    ),
-)
-
-
-CROSS_CUTTING_BY_ID: dict[str, CrossCutSpec] = {c.id: c for c in CROSS_CUTTING}
-
-
-TCB_PROVIDER_YAML = """provider:
-  name: tcb
-  display_name: Tencent CloudBase
-  default: true
-  version: 3.0.0
-
-storage:
-  object_storage: cloudbase-storage
-  document_db: docdb
-  relational_db: mysql
-  cdn: tencent-cloud-cdn
-"""
-
-TCB_DEPLOYMENT_YAML = """environments:
-  preview:
-    orchestrator: deploy_stack
-    strategy: unified
-    ttl: 24h
-  staging:
-    orchestrator: deploy_stack
-  production:
-    orchestrator: deploy_stack
-    pre_conditions:
-      - human-approval-gate
-"""
-
-TCB_PREVIEW_YAML = """preview:
-  orchestrator: deploy_stack
-  strategy: unified
-  ttl: 24h
-  auto_cleanup: true
-  db_sandbox: true
-"""
-
-TOOL_STUB = """#!/usr/bin/env python3
-\"\"\"Stub — auto-generated by cdh scaffold.\"\"\"
-import sys
-
-
-def main():
-    print(f"{__file__}: not yet implemented")
-    sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()
-"""
-
-GITIGNORE_CONTENT = """# Python
-__pycache__/
-*.py[cod]
-*.egg-info/
-dist/
-build/
-.venv/
-venv/
-*.egg
-
-# Node
-node_modules/
-.next/
-dist/
-.nuxt/
-.cache/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# OS
-.DS_Store
-Thumbs.db
-
-# CDH
-.cdh/
-"""
-
-CHANGELOG_MD = "# Changelog\n\n## [0.1.0] - Initial scaffold\n\n- Project created via cdh scaffold\n"
-
-AGENTS_MD_TEMPLATE = """# AGENTS.md — Project Constitution
-
-Hard rules every AI agent must follow when working in this repo.
-Read once per session; behavior is enforced by the agent runtime.
-
-## Project Overview
-
-- **Name**: {project_name}
-- **Description**: {description}
-- **Type**: monorepo — AI-DLC multi-component stack
-{component_list}
-
-## AI-DLC Core Cycle
-
-```
-① Understand (SDD+BDD)   Intent → Spec Delta → BDD Feature Files
-② Plan (SDD+TDD)         Design Doc → Task DAG → Test Plan
-③ Verify (BDD+TDD)       Red → Green → Refactor per scenario
-④ Deliver (SDD+Cloud)    Stack Preview → e2e → Production + BVT
-```
-
-Reference skill: `~/.cdh/skills/ai-dlc-skill/SKILL.md` (full AI-DLC methodology; installed by cdh platform bootstrap).
-
-## Component Mapping
-
-Work is partitioned by component prefix. Place new code in the matching directory:
-
-| Prefix | Component | Directory |
-|--------|-----------|-----------|
-{component_table}
-
-> **Note**: FR namespaces are used in AI-DLC lifecycle only.
-
-## Quality Gates
-
-Hard thresholds every agent must respect:
-
-| Gate | Threshold |
-|------|-----------|
-| Unit/integration coverage | >= 80% |
-| BDD scenarios pass | 100% |
-| Contract tests pass | 100% |
-| Cross-stack e2e pass | 100% |
-| Security vulns | 0 |
-
-## File / Path Hygiene
-
-**Never read, write, or modify** any of these (they're local-only / secrets / build artifacts):
-
-- `.cdh/` — project-level runtime state (managed by CLI; never hand-edit)
-- `.opencode/`, `.claude/`, `.agents/` — tool configs (owned by user)
-- `.qwen/`, `.idea/` — IDE / tool caches
-- `dist/`, `*.egg-info/`, `__pycache__/`, `build/`, `.venv/`
-- `node_modules/`, `.next/`, `.nuxt/`
-- `.python-version`, `uv.lock` — Python toolchain pinning (user-managed)
-- `aidlc/contracts/CHANGELOG.md` — contract changelog (managed by CLI)
-- `aidlc/providers/` — provider config (managed by CLI)
-
-**Global state directories** (managed at runtime, do not hand-edit):
-- `~/.cdh/` — cdh platform global state (projects/, skills/, mcps/, state/, logs/, sessions/)
-- `~/.onecode/` — onecode engine private state (traces, memory, mcps, skills, config)
-
-## Forbidden Actions
-
-- Commit secrets (API keys, tokens, passwords) — use env vars or vault
-- Force-push to `main` / `master`
-- Modify files outside the project root
-- Run `npm publish` / `pip upload` without explicit user approval
-- Hand-edit `.cdh/state.json`, `.cdh/todos.json`, `.cdh/last_session.json` — use CLI / slash commands
-- Delete tracked files outside `dist/`, `build/`, `__pycache__/` without confirmation
-
-## Working Conventions
-
-This project follows the **AI-DLC (AI-Driven Lifecycle)** methodology shown above.
-
-- **Plan first**: Use task management (TodoCreate) for any non-trivial task (3+ steps)
-- **Route execution**:
-  - Single-step (1 tool, 1 file) → direct tool call
-  - Multi-step / multi-file / research → delegate to sub-agent
-- **Language**: Chinese for explanations to user, English for code / comments / commit messages
-- **Verification**: After non-trivial edits, run applicable lint/typecheck/test commands before declaring done
-
-## Where to Find More
-
-- **AI-DLC methodology**: `~/.cdh/skills/ai-dlc-skill/SKILL.md` (load via Skill tool; installed by cdh bootstrap)
-- **Human-readable README**: `README.md`
-- **Architecture / practices**: `docs/` if present, or ask the user
-"""
-
-REQUIREMENTS_MD = """# {project_name}
-
-## Intent
-
-{description}
-
-## Stack Topology
-
-Monorepo multi-component stack with the following components:
-
-| Component | FR Prefix | Default Language | Default UI Framework | Directory |
-|-----------|-----------|-----------------|---------------------|-----------|
-{component_table}
-
-## Quality Gates
-
-| Gate | Threshold |
-|------|-----------|
-| Unit/integration coverage | >= 80% |
-| BDD scenarios pass | 100% |
-| Contract tests pass | 100% |
-| Cross-stack e2e pass | 100% |
-| Security vulns | 0 |
-
-Default cloud provider: TCB (Tencent CloudBase).
-"""
-
-
-def _detect_dlc_skill(workspace_root: Path) -> bool:
-    from cdh.cdh_skill_manager import CDH_PLATFORM_SKILLS_DIR
-    return (CDH_PLATFORM_SKILLS_DIR / SKILL_NAME / "SKILL.md").exists()
-
-
-def _mkdir(path: Path) -> None:
-    path.mkdir(parents=True, exist_ok=True)
-
-
-def _gitkeep(path: Path) -> None:
-    keep = path / ".gitkeep"
-    if not keep.exists():
-        keep.write_text("", encoding="utf-8")
-
-
-def _write(path: Path, content: str) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(content.lstrip("\n"), encoding="utf-8")
-
-
-def _build_agents_component_list(active: list[ComponentSpec]) -> str:
-    if not active:
-        return ""
-    items = (f"  - **{c.label}** (`{c.owns}`)" for c in active)
-    return "- **Components**:\n" + "\n".join(items)
-
-
-def _build_agents_component_table(active: list[ComponentSpec]) -> str:
-    rows = []
-    for c in active:
-        rows.append(f"| {c.fr_prefix:7s} | {c.label:14s} | {c.owns:20s} |")
-    rows.append("| INT      | Contracts, Shared | aidlc/contracts/, aidlc/packages/shared/ |")
-    return "\n".join(rows)
-
-
-def _write_agents_and_claude_md(
-    root: Path,
-    project_name: str,
-    description: str,
-    active: list[ComponentSpec],
-) -> None:
-    content = AGENTS_MD_TEMPLATE.format(
-        project_name=project_name,
-        description=description or f"AI-DLC monorepo project: {project_name}",
-        component_list=_build_agents_component_list(active),
-        component_table=_build_agents_component_table(active),
-    )
-    _write(root / "AGENTS.md", content)
-    _write(root / "CLAUDE.md", content)
-
-
-def _component_to_dict(c: ComponentSpec) -> dict:
-    out = {
-        "id": c.id,
-        "kind": c.kind,
-        "tech": c.tech,
-        "owns": c.owns,
-        "fr_prefix": c.fr_prefix,
-    }
-    return out
-
-
-def _build_project_yaml(
-    active: list[ComponentSpec],
-    cross_cutting_ids: list[str],
-    name: str = "",
-    description: str = "",
-) -> dict:
-    cross_cutting: dict = {"fr_prefix": "INT"}
-    if "contracts" in cross_cutting_ids:
-        cross_cutting["contracts"] = "aidlc/contracts/"
-    if "shared" in cross_cutting_ids:
-        cross_cutting["shared_types"] = "aidlc/packages/shared/"
-    doc: dict = {
-        "name": name,
-        "description": description,
-        "stack": {
-            "topology": "monorepo",
-            "components": [_component_to_dict(c) for c in active],
-            "cross_cutting": cross_cutting,
-        },
-    }
-    return doc
-
-
-def _build_component_table(active: list[ComponentSpec]) -> str:
-    if not active:
-        return "| (none)       | -             | -                 | -                   | -                   |"
-    return "\n".join(
-        f"| {c.id:8s} | {c.fr_prefix + '-FR-*':14s} | {'-':17s} | {'-':21s} | {c.owns:20s} |"
-        for c in active
-    )
-
-
-def _scaffold_component(c: ComponentSpec, root: Path) -> None:
-    comp_dir = root / c.owns
-    _mkdir(comp_dir / "src")
-    _mkdir(comp_dir / "tests" / "unit")
-    _mkdir(comp_dir / "tests" / "e2e")
-    _mkdir(comp_dir / "features")
-    _gitkeep(comp_dir / "src")
-    _gitkeep(comp_dir / "tests" / "unit")
-    _gitkeep(comp_dir / "tests" / "e2e")
-    _gitkeep(comp_dir / "features")
-    _gitkeep(comp_dir)
-
-
-def _scaffold_cross_cutting(cross_ids: list[str], root: Path) -> None:
-    for cid in cross_ids:
-        spec = CROSS_CUTTING_BY_ID.get(cid)
-        if spec is None:
-            continue
-        for p in spec.paths:
-            target = root / p
-            if p.endswith((".yaml", ".py", ".md")):
-                if p == "aidlc/contracts/CHANGELOG.md":
-                    _write(target, CHANGELOG_MD)
-                elif p == "aidlc/providers/tcb/provider.yaml":
-                    _write(target, TCB_PROVIDER_YAML)
-                elif p == "aidlc/providers/tcb/deployment.yaml":
-                    _write(target, TCB_DEPLOYMENT_YAML)
-                elif p == "aidlc/providers/tcb/preview.yaml":
-                    _write(target, TCB_PREVIEW_YAML)
-                elif p.startswith("aidlc/tools/") and p.endswith(".py"):
-                    _write(target, TOOL_STUB)
-                    target.chmod(0o755)
-                else:
-                    _write(target, "")
-            else:
-                _mkdir(target)
-                _gitkeep(target)
-
-
-def _write_project_yaml(
-    root: Path,
-    project_name: str,
-    active: list[ComponentSpec],
-    cross_cutting_ids: list[str],
-    description: str,
-) -> None:
-    _write(
-        root / "aidlc" / "project.yaml",
-        yaml.dump(
-            _build_project_yaml(active, cross_cutting_ids, name=project_name, description=description),
-            default_flow_style=False,
-        ),
-    )
-    _write(
-        root / "aidlc" / "requirements.md",
-        REQUIREMENTS_MD.format(
-            project_name=project_name,
-            description=description or f"AI-DLC monorepo project: {project_name}",
-            component_table=_build_component_table(active),
-        ),
-    )
-    _write(root / ".gitignore", GITIGNORE_CONTENT)
-    _write(root / "aidlc" / "CHANGELOG.md", CHANGELOG_MD)
-
-
-def init_dlc_project(
-    workspace_root: Path,
-    project_name: str,
-    description: str = "",
-) -> bool:
-    """Scaffold project metadata only (no apps/*, no cross-cutting dirs).
-
-    Writes project.yaml (with empty components list), aidlc/requirements.md,
-    .gitignore, and aidlc/CHANGELOG.md. The user is expected to add components
-    and cross-cutting items later via add_component / add_cross_cutting.
-
-    Returns True if scaffolding was performed.
-
-    Raises RuntimeError if ai-dlc-skill is not available — the directory
-    is left untouched in that case so callers don't end up with a
-    half-initialized project (.cdh/ written but no aidlc/project.yaml).
-    """
-    if not _detect_dlc_skill(workspace_root):
-        raise RuntimeError(
-            "ai-dlc-skill is not available; install it before "
-            "initializing a cdh project."
-        )
-
-    root = workspace_root.resolve()
-    _write_project_yaml(
-        root=root,
-        project_name=project_name,
-        active=[],
-        cross_cutting_ids=[],
-        description=description,
-    )
-    _write_agents_and_claude_md(root, project_name, description, [])
-    return True
-
-
-def scaffold_dlc_project(
-    workspace_root: Path,
-    project_name: str,
-    components: list[str],
-    description: str = "",
-) -> bool:
-    """Scaffold a full ai-dlc-skill monorepo project structure.
-
-    The user must explicitly select at least one application component.
-    All cross-cutting items (contracts, shared types, openspec, etc.)
-    are always created.
-
-    Args:
-        components: list of component ids (e.g. ["web", "backend"]).
-                   Must be non-empty.
-
-    Returns True if scaffolding was performed, False if ai-dlc-skill
-    is not available and the project was left untouched.
-
-    Raises ValueError if components is empty or contains unknown ids.
-    """
-    if not components:
-        raise ValueError(
-            "At least one application component is required "
-            "(e.g. 'web', 'backend', 'native')."
-        )
-
-    unknown = [c for c in components if c not in COMPONENT_BY_ID]
-    if unknown:
-        raise ValueError(
-            f"Unknown component id(s): {', '.join(unknown)}. "
-            f"Valid ids: {', '.join(COMPONENT_BY_ID)}."
-        )
-
-    if not _detect_dlc_skill(workspace_root):
-        return False
-
-    root = workspace_root.resolve()
-    active = [COMPONENT_BY_ID[cid] for cid in components]
-    all_cross_ids = [
-        c.id for c in CROSS_CUTTING if c.id not in ("provider", "tools")
-    ]
-
-    _write_project_yaml(
-        root=root,
-        project_name=project_name,
-        active=active,
-        cross_cutting_ids=all_cross_ids,
-        description=description,
-    )
-
-    for c in active:
-        _scaffold_component(c, root)
-
-    _scaffold_cross_cutting(all_cross_ids, root)
-    _write_agents_and_claude_md(root, project_name, description, active)
-
-    return True
-
-
-def _regenerate_agents_and_claude_md(root: Path) -> None:
-    project_yaml = root / "aidlc" / "project.yaml"
-    if not project_yaml.exists():
-        return
-    data = yaml.safe_load(project_yaml.read_text(encoding="utf-8")) or {}
-    name = data.get("name", root.name)
-    description = data.get("description", "")
-    components = data.get("stack", {}).get("components", []) or []
-    active = []
-    for c in components:
-        spec = COMPONENT_BY_ID.get(c.get("id", ""))
-        if spec:
-            active.append(spec)
-    _write_agents_and_claude_md(root, name, description, active)
-
-
-def add_component(
-    workspace_root: Path,
-    component_id: str,
-) -> bool:
-    """Add a single application component to an existing project.
-
-    Creates apps/<owns>/{src,tests/unit,tests/e2e,features} with
-    .gitkeep files and updates aidlc/project.yaml's stack.components list.
-
-    Returns True if the component was added, False if it was already
-    present. Raises ValueError on unknown component id.
-    """
-    spec = COMPONENT_BY_ID.get(component_id)
-    if spec is None:
-        raise ValueError(
-            f"Unknown component id: {component_id}. "
-            f"Valid ids: {', '.join(COMPONENT_BY_ID)}."
-        )
-
-    root = workspace_root.resolve()
-    project_yaml = root / "aidlc" / "project.yaml"
-    if not project_yaml.exists():
-        raise FileNotFoundError(
-            f"aidlc/project.yaml not found at {root}. Run 'cdh project init' first."
-        )
-
-    data = yaml.safe_load(project_yaml.read_text(encoding="utf-8")) or {}
-    components = data.get("stack", {}).get("components", []) or []
-    if any(c.get("id") == component_id for c in components):
-        return False
-
-    _scaffold_component(spec, root)
-
-    components.append(_component_to_dict(spec))
-    data["stack"]["components"] = components
-    project_yaml.write_text(
-        yaml.dump(data, default_flow_style=False),
-        encoding="utf-8",
-    )
-    _regenerate_agents_and_claude_md(root)
-    return True
-
-
-def add_cross_cutting(
-    workspace_root: Path,
-    cross_id: str,
-) -> bool:
-    """Add a single cross-cutting item to an existing project.
-
-    Creates the relevant directories/files and updates aidlc/project.yaml
-    so that stack.cross_cutting references the new path.
-
-    Returns True if the item was added, False if it was already present.
-    Raises ValueError on unknown cross-cutting id.
-    """
-    spec = CROSS_CUTTING_BY_ID.get(cross_id)
-    if spec is None:
-        raise ValueError(
-            f"Unknown cross-cutting id: {cross_id}. "
-            f"Valid ids: {', '.join(CROSS_CUTTING_BY_ID)}."
-        )
-
-    root = workspace_root.resolve()
-    project_yaml = root / "aidlc" / "project.yaml"
-    if not project_yaml.exists():
-        raise FileNotFoundError(
-            f"aidlc/project.yaml not found at {root}. Run 'cdh project init' first."
-        )
-
-    cross_paths = [root / p for p in spec.paths]
-    if all(p.exists() for p in cross_paths):
-        return False
-
-    _scaffold_cross_cutting([cross_id], root)
-
-    data = yaml.safe_load(project_yaml.read_text(encoding="utf-8")) or {}
-    cross_cutting = data.setdefault("stack", {}).setdefault("cross_cutting", {})
-    if cross_id == "contracts":
-        cross_cutting["contracts"] = "aidlc/contracts/"
-    elif cross_id == "shared":
-        cross_cutting["shared_types"] = "packages/shared/"
-
-    project_yaml.write_text(
-        yaml.dump(data, default_flow_style=False),
-        encoding="utf-8",
-    )
-    _regenerate_agents_and_claude_md(root)
-    return True
-
-
-__all__ = [
-    "COMPONENTS",
-    "COMPONENT_BY_ID",
-    "CROSS_CUTTING",
-    "CROSS_CUTTING_BY_ID",
-    "ComponentSpec",
-    "CrossCutSpec",
-    "init_dlc_project",
-    "scaffold_dlc_project",
-    "add_component",
-    "add_cross_cutting",
-]