source-kb 0.2.2__py3-none-any.whl

cli/__init__.py

@@ -0,0 +1,50 @@
+"""source-kb — unified CLI entry point.
+
+Usage:
+    source-kb <command> [options]
+    source-kb --help
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import pkgutil
+import sys
+
+
+def _discover_commands(subparsers: argparse._SubParsersAction) -> None:
+    """Auto-discover and register all command modules in cli.commands."""
+    import cli.commands as cmd_pkg
+
+    for finder, name, _ in pkgutil.iter_modules(cmd_pkg.__path__):
+        module = importlib.import_module(f"cli.commands.{name}")
+        if hasattr(module, "register"):
+            module.register(subparsers)
+
+
+def main(argv: list[str] | None = None) -> None:
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+    from core import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="source-kb",
+        description="Auto-generate structured knowledge base documents from source code.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command")
+    _discover_commands(subparsers)
+
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        parser.print_help()
+        sys.exit(1)

cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m cli"""
+
+from cli import main
+
+main()

cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command registry — modules here are auto-discovered by the entry point."""

cli/commands/anchor_fix.py

@@ -0,0 +1,47 @@
+"""source-kb anchor-fix — Fix broken cross-document anchor links."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("anchor-fix", help="Fix broken cross-document anchor links")
+    p.add_argument("--module-dir", required=True, help="Module documentation directory")
+    p.add_argument("--dry-run", action="store_true", help="Report without fixing")
+    p.add_argument("--threshold", type=float, default=0.8, help="Fuzzy match threshold (0.0-1.0)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.anchor_fix import fix_anchors
+
+    module_dir = Path(args.module_dir)
+    if not module_dir.is_dir():
+        print(f"Error: directory not found: {module_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    result = fix_anchors(
+        module_dir,
+        dry_run=args.dry_run,
+        similarity_threshold=args.threshold,
+    )
+
+    mode = " (dry-run)" if args.dry_run else ""
+    print(f"Anchor fix{mode}: scanned {result.files_scanned} files, checked {result.links_checked} links")
+    if result.links_fixed or result.links_degraded:
+        print(f"  Fixed: {result.links_fixed}, Degraded: {result.links_degraded}")
+        for d in result.details:
+            action = "fixed" if d["action"] == "fixed" else "degraded"
+            print(f"  [{action}] {d['file']}: {d['old_link']} -> {d['new_link']}")
+    else:
+        print("  All links valid.")
+
+    print(json.dumps({
+        "status": "ok", "files_scanned": result.files_scanned,
+        "links_checked": result.links_checked, "links_fixed": result.links_fixed,
+        "links_degraded": result.links_degraded,
+    }, ensure_ascii=False), file=sys.stderr)

cli/commands/diff_doc.py

@@ -0,0 +1,52 @@
+"""source-kb diff-doc — Compare document against skeleton."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("diff-doc", help="Compare document against skeleton for inconsistencies")
+    p.add_argument("--doc-path", required=True, help="Path to markdown document")
+    p.add_argument("--skeleton-path", required=True, help="Path to skeleton JSON or directory")
+    p.add_argument("--doc-type", help="Document type for specific comparison rules")
+    p.add_argument("--output", help="Output JSON path (default: stdout)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.diff_doc import diff_doc
+
+    doc_path = Path(args.doc_path)
+    skeleton_path = Path(args.skeleton_path)
+
+    if not doc_path.exists():
+        print(f"Error: document not found: {doc_path}", file=sys.stderr)
+        sys.exit(1)
+    if not skeleton_path.exists():
+        print(f"Error: skeleton not found: {skeleton_path}", file=sys.stderr)
+        sys.exit(1)
+
+    result = diff_doc(doc_path, skeleton_path, doc_type=args.doc_type)
+
+    output = {
+        "doc_type": result.doc_type,
+        "doc_items": result.doc_items_count,
+        "skeleton_items": result.skeleton_items_count,
+        "missing": result.missing_count,
+        "stale": result.stale_count,
+        "findings": result.to_json(),
+    }
+
+    output_json = json.dumps(output, ensure_ascii=False, indent=2)
+    if args.output:
+        Path(args.output).write_text(output_json, encoding="utf-8")
+        print(f"Written to: {args.output}")
+    else:
+        print(output_json)
+
+    print(json.dumps({"status": "ok", "missing": result.missing_count,
+                      "stale": result.stale_count}, ensure_ascii=False), file=sys.stderr)

cli/commands/dispatch.py

@@ -0,0 +1,77 @@
+"""source-kb dispatch — Generate dispatch plan preview."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("dispatch", help="Generate dispatch plan preview")
+    p.add_argument("--config", help="kb-project.yaml path")
+    p.add_argument("--kb", required=True, help="Knowledge base name")
+    p.add_argument("--module", required=True, help="Module name")
+    p.add_argument("--mode", default="readwrite", choices=["readwrite", "output-only"])
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.config import load_config
+    from core.preset import load_preset
+    from core.skeleton.dispatch import compute_dispatch_plan
+    from core.skeleton.dispatch_render import render_markdown, plan_to_tasks, write_shard_files
+
+    config = load_config(Path(args.config) if args.config else None)
+    kb_config = config.get_kb(args.kb)
+    preset_name = kb_config.get("preset", "generic")
+    preset = load_preset(preset_name)
+
+    knowledge_dir = Path(kb_config["knowledge_dir"])
+    source = kb_config.get("source", {})
+    cache_dir = Path(source.get("cache_dir", "./.source-cache"))
+
+    module_name = args.module
+    module_dir = knowledge_dir / module_name
+    source_cache = cache_dir / module_name
+
+    module_type = "service"
+    repos = source.get("repos", [])
+    for repo in repos:
+        if repo.get("name") == module_name:
+            module_type = repo.get("type", "service")
+            break
+
+    mode = args.mode
+
+    plan = compute_dispatch_plan(
+        preset=preset, module_dir=module_dir, source_cache=source_cache,
+        mode=mode, module_name=module_name, module_type=module_type,
+    )
+
+    markdown = render_markdown(plan, mode=mode)
+
+    meta_dir = module_dir / ".meta"
+    meta_dir.mkdir(parents=True, exist_ok=True)
+    (meta_dir / "dispatch-plan.md").write_text(markdown, encoding="utf-8")
+
+    tasks = plan_to_tasks(
+        plan=plan, kb_name=args.kb, preset_name=preset_name,
+        preset=preset, knowledge_dir=knowledge_dir, mode=mode,
+    )
+    (meta_dir / "dispatch-tasks.json").write_text(
+        json.dumps(tasks, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+    write_shard_files(plan, module_dir)
+
+    print(f"Dispatch plan: {len(plan.entries)} doc types, {plan.total_shards()} shards (mode={mode})")
+    print(f"  Written to: {meta_dir / 'dispatch-plan.md'}")
+    print(f"  Tasks JSON: {meta_dir / 'dispatch-tasks.json'}")
+    for e in plan.entries:
+        shards_str = f" x{e.split_count}" if e.split_count > 1 else ""
+        print(f"  - {e.doc_type} ({e.file_count} files, {e.total_lines} lines){shards_str}")
+
+    print(json.dumps({"status": "ok", "entries": len(plan.entries),
+                      "total_shards": plan.total_shards()}, ensure_ascii=False), file=sys.stderr)

cli/commands/extract.py

@@ -0,0 +1,72 @@
+"""source-kb extract — Extract skeleton from source repository."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("extract", help="Extract skeleton from source repo")
+    p.add_argument("--repo", required=True, help="Repository path")
+    p.add_argument("--preset", required=True, help="Preset name")
+    p.add_argument("--ref", default="HEAD", help="Git reference")
+    p.add_argument("--output", help="Output directory")
+    p.add_argument("--split-by-package", action="store_true")
+    p.add_argument("--no-compact", action="store_true")
+    p.add_argument("--summary", action="store_true")
+    p.add_argument("--subpath", help="Subdirectory scope (monorepo module path)")
+    p.add_argument("--files", nargs="*", help="Extract only specified file paths (incremental)")
+    p.add_argument("--doc", help="Extract only files relevant to specified doc type")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.extract import extract_skeleton
+    from core.preset import load_preset
+
+    preset = load_preset(args.preset)
+    repo_path = Path(args.repo)
+    output_dir = Path(args.output) if args.output else None
+
+    files_filter = args.files
+    if args.doc and not files_filter:
+        doc_types = preset.get("doc_types", {})
+        if args.doc not in doc_types:
+            valid = ", ".join(doc_types.keys())
+            print(f"Error: unknown doc type '{args.doc}'. Valid: {valid}", file=sys.stderr)
+            sys.exit(1)
+
+    entries = extract_skeleton(
+        repo_path, preset,
+        ref=args.ref or "HEAD",
+        subpath=args.subpath,
+        output_dir=output_dir,
+        split_by_package=args.split_by_package,
+        compact=not args.no_compact,
+        files=files_filter,
+    )
+
+    result = {
+        "status": "ok",
+        "files": len(entries),
+        "methods": sum(len(e.get("methods", [])) for e in entries),
+        "classes": sum(len(e.get("classes", [])) for e in entries),
+    }
+    if args.doc:
+        result["doc_filter"] = args.doc
+
+    if args.summary and output_dir:
+        result["summary"] = str(output_dir / ".meta" / "skeleton-summary.json")
+
+    if not output_dir:
+        default_out = repo_path / ".meta" / "skeleton"
+        default_out.mkdir(parents=True, exist_ok=True)
+        skel_file = default_out / "skeleton.json"
+        skel_file.write_text(json.dumps(entries, ensure_ascii=False, indent=1), encoding="utf-8")
+        result["output"] = str(skel_file)
+        print(f"Extracted to: {skel_file}")
+
+    print(json.dumps(result, ensure_ascii=False), file=sys.stderr)

cli/commands/file_list.py

@@ -0,0 +1,74 @@
+"""source-kb file-list — Extract file list for a doc type."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("file-list", help="Extract file list for a doc type")
+    p.add_argument("--skeleton", help="Skeleton JSON path")
+    p.add_argument("--module-dir", help="Module directory")
+    p.add_argument("--preset", required=True, help="Preset name")
+    p.add_argument("--doc-type", help="Document type")
+    p.add_argument("--source-cache", help="Source cache path")
+    p.add_argument("--output", help="Output file path")
+    p.add_argument("--coverage-check", action="store_true")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.file_list import load_skeleton, extract_file_list, check_coverage
+    from core.preset import load_preset
+
+    preset = load_preset(args.preset)
+    module_dir = Path(args.module_dir) if args.module_dir else None
+    skeleton_path = Path(args.skeleton) if args.skeleton else None
+
+    if skeleton_path:
+        from core.skeleton.query import load_skeleton as ql
+        entries = ql(skeleton_path)
+    elif module_dir:
+        entries = load_skeleton(module_dir)
+    else:
+        print("Error: --skeleton or --module-dir required", file=sys.stderr)
+        sys.exit(1)
+
+    source_cache = Path(args.source_cache) if args.source_cache else Path(".")
+
+    if args.coverage_check:
+        from core.paths import file_list_dir
+        fl_dir = file_list_dir(module_dir) if module_dir else None
+        report = check_coverage(entries, preset, fl_dir)
+        print(f"Coverage: {report.coverage_pct:.1f}% ({report.covered}/{report.total_files})")
+        if report.uncovered_files:
+            print(f"Uncovered ({report.uncovered_count}):")
+            for f in report.uncovered_files[:20]:
+                print(f"  {f}")
+        if args.output:
+            Path(args.output).parent.mkdir(parents=True, exist_ok=True)
+            Path(args.output).write_text("\n".join(report.uncovered_files), encoding="utf-8")
+        print(json.dumps({"status": "ok", "coverage_pct": round(report.coverage_pct, 1),
+                          "uncovered": report.uncovered_count}, ensure_ascii=False), file=sys.stderr)
+        return
+
+    files = extract_file_list(entries, preset, args.doc_type, source_cache)
+    if args.output:
+        Path(args.output).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.output).write_text("\n".join(files) + "\n", encoding="utf-8")
+        print(f"Written {len(files)} files to: {args.output}")
+    elif module_dir and args.doc_type:
+        from core.paths import file_list_dir
+        fl_dir = file_list_dir(module_dir)
+        fl_dir.mkdir(parents=True, exist_ok=True)
+        out_path = fl_dir / f"{args.doc_type}.txt"
+        out_path.write_text("\n".join(files) + "\n", encoding="utf-8")
+        print(f"Written {len(files)} files to: {out_path}")
+    else:
+        for f in files:
+            print(f)
+
+    print(json.dumps({"status": "ok", "files": len(files)}, ensure_ascii=False), file=sys.stderr)

cli/commands/index.py

@@ -0,0 +1,84 @@
+"""source-kb index / search — RAG index and search operations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("index", help="Build/rebuild vector index for knowledge base")
+    p.add_argument("--config", help="kb-project.yaml path")
+    p.add_argument("--kb", required=True, help="Knowledge base name")
+    p.add_argument("--module", help="Module name (for incremental rebuild)")
+    p.add_argument("--files", nargs="*", help="Specific files to rebuild (incremental)")
+    p.set_defaults(func=run_index)
+
+    p = subparsers.add_parser("search", help="Search knowledge base via RAG")
+    p.add_argument("--config", help="kb-project.yaml path")
+    p.add_argument("--kb", required=True, help="Knowledge base name")
+    p.add_argument("query", help="Search query")
+    p.set_defaults(func=run_search)
+
+
+def run_index(args: argparse.Namespace) -> None:
+    from core.config import load_config, find_config
+    from core.rag.loader import load_documents
+    from core.rag.chunker import chunk_documents
+    from core.rag.indexer import build_index
+
+    config_path = Path(args.config) if args.config else find_config()
+    config = load_config(config_path)
+    kb_cfg = config.get_kb(args.kb)
+    knowledge_dir = Path(kb_cfg["knowledge_dir"])
+    collection_name = kb_cfg["collection"]
+
+    incremental = bool(args.module or args.files)
+    if args.module:
+        knowledge_dir = knowledge_dir / args.module
+
+    if args.files:
+        docs = load_documents(knowledge_dir, file_filter=args.files)
+    else:
+        docs = load_documents(knowledge_dir)
+
+    if not docs:
+        print(f"No documents found in {knowledge_dir}")
+        print(json.dumps({"status": "ok", "docs": 0}, ensure_ascii=False), file=sys.stderr)
+        return
+
+    chunks = chunk_documents(docs)
+    print(f"Indexing {len(docs)} docs, {len(chunks)} chunks...")
+    build_index(chunks, collection_name, config, kb_name=args.kb, incremental=incremental)
+    print(f"Index built: {len(chunks)} chunks -> collection '{collection_name}'")
+    print(json.dumps({"status": "ok", "docs": len(docs), "chunks": len(chunks),
+                      "collection": collection_name}, ensure_ascii=False), file=sys.stderr)
+
+
+def run_search(args: argparse.Namespace) -> None:
+    from core.config import load_config, find_config
+    from core.rag.retriever import retrieve
+
+    config_path = Path(args.config) if args.config else find_config()
+    config = load_config(config_path)
+
+    results = retrieve(args.query, config, kb_name=args.kb)
+    if not results:
+        print(f"No results for '{args.query}'")
+        print(json.dumps({"status": "ok", "matches": 0}, ensure_ascii=False), file=sys.stderr)
+        return
+
+    for i, r in enumerate(results, 1):
+        score = r["score"]
+        source = r["metadata"].get("source", "?")
+        section = r["metadata"].get("section", "")
+        header = f"[{i}] {source}"
+        if section:
+            header += f" > {section}"
+        print(f"{header}  (score: {score:.3f})")
+        print(f"    {r['text'][:200]}...")
+        print()
+
+    print(json.dumps({"status": "ok", "matches": len(results)}, ensure_ascii=False), file=sys.stderr)

cli/commands/lock.py

@@ -0,0 +1,89 @@
+"""source-kb lock — Knowledge base lock management."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("lock", help="Acquire/release/check knowledge base lock")
+    p.add_argument("--action", required=True, choices=["acquire", "release", "status"])
+    p.add_argument("--dir", required=True, help="Knowledge directory")
+    p.add_argument("--operation", help="Operation name (kb-init|kb-sync|kb-audit)")
+    p.add_argument("--timeout", type=int, default=30, help="Timeout in minutes")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    lock_dir = Path(args.dir)
+    lock_path = lock_dir / ".kb-lock"
+    lock_meta_path = lock_dir / ".kb-lock.json"
+
+    if args.action == "acquire":
+        lock_dir.mkdir(parents=True, exist_ok=True)
+
+        if lock_path.exists():
+            if _is_stale_lock(lock_meta_path):
+                lock_path.unlink(missing_ok=True)
+                lock_meta_path.unlink(missing_ok=True)
+                print(json.dumps({"status": "warning", "message": "Stale lock overridden"},
+                                 ensure_ascii=False), file=sys.stderr)
+            else:
+                meta = _read_meta(lock_meta_path)
+                print(json.dumps({"status": "error", "message": "Already locked",
+                                  **meta}, ensure_ascii=False), file=sys.stderr)
+                sys.exit(1)
+
+        lock_path.write_text(str(os.getpid()), encoding="utf-8")
+        meta = {
+            "pid": os.getpid(),
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+            "operation": args.operation or "unknown",
+        }
+        lock_meta_path.write_text(json.dumps(meta, ensure_ascii=False), encoding="utf-8")
+        print(json.dumps({"status": "ok", "action": "acquired"}, ensure_ascii=False), file=sys.stderr)
+
+    elif args.action == "release":
+        lock_path.unlink(missing_ok=True)
+        lock_meta_path.unlink(missing_ok=True)
+        print(json.dumps({"status": "ok", "action": "released"}, ensure_ascii=False), file=sys.stderr)
+
+    elif args.action == "status":
+        if lock_path.exists():
+            meta = _read_meta(lock_meta_path)
+            stale = _is_stale_lock(lock_meta_path)
+            print(json.dumps({"status": "locked", "stale": stale, **meta},
+                             ensure_ascii=False), file=sys.stderr)
+        else:
+            print(json.dumps({"status": "unlocked"}, ensure_ascii=False), file=sys.stderr)
+
+
+def _read_meta(lock_meta_path: Path) -> dict:
+    if not lock_meta_path.exists():
+        return {}
+    try:
+        return json.loads(lock_meta_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _is_stale_lock(lock_meta_path: Path) -> bool:
+    if not lock_meta_path.exists():
+        return True
+    try:
+        meta = json.loads(lock_meta_path.read_text(encoding="utf-8"))
+        ts = meta.get("timestamp", "")
+        if not ts:
+            return True
+        lock_time = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        now = datetime.now(timezone.utc)
+        age_minutes = (now - lock_time).total_seconds() / 60
+        return age_minutes > 30
+    except (json.JSONDecodeError, OSError, ValueError):
+        return True

cli/commands/merge.py

@@ -0,0 +1,60 @@
+"""source-kb merge — Merge document shards into single files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("merge", help="Merge document shards into single files")
+    p.add_argument("--dir", required=True, help="Module directory containing shards")
+    p.add_argument("--doc-type", help="Merge only this doc type (default: all)")
+    p.add_argument("--keep-shards", action="store_true", help="Keep shard files after merge")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.merge import find_shards, merge_shards
+
+    module_dir = Path(args.dir)
+    if not module_dir.is_dir():
+        print(f"Error: directory not found: {module_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.doc_type:
+        prefixes = [args.doc_type]
+    else:
+        seen = set()
+        for f in module_dir.glob("*-shard-*.md"):
+            prefix = f.name.rsplit("-shard-", 1)[0]
+            seen.add(prefix)
+        for f in module_dir.glob(".shard-*-*.md"):
+            prefix = f.name.split(".shard-", 1)[1].rsplit("-", 1)[0]
+            seen.add(prefix)
+        prefixes = sorted(seen)
+
+    if not prefixes:
+        print("No shards found to merge.")
+        print(json.dumps({"status": "ok", "merged": 0}, ensure_ascii=False), file=sys.stderr)
+        return
+
+    merged_count = 0
+    for prefix in prefixes:
+        shards = find_shards(module_dir, prefix)
+        if not shards:
+            continue
+        content = merge_shards(shards)
+        out_path = module_dir / f"{prefix}.md"
+        out_path.write_text(content, encoding="utf-8")
+        print(f"  Merged {len(shards)} shards -> {out_path.name}")
+
+        if not args.keep_shards:
+            for s in shards:
+                s.unlink()
+
+        merged_count += 1
+
+    print(json.dumps({"status": "ok", "merged": merged_count}, ensure_ascii=False), file=sys.stderr)

cli/commands/merge_delta.py

@@ -0,0 +1,19 @@
+"""source-kb merge-delta — Merge skeleton delta into existing skeleton."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("merge-delta", help="Merge skeleton delta into existing skeleton")
+    p.add_argument("--delta", required=True, help="Path to delta JSON file")
+    p.add_argument("--target", required=True, help="Target module directory")
+    p.add_argument("--dry-run", action="store_true", help="Preview merge without writing")
+    p.add_argument("--no-cleanup", action="store_true", help="Keep delta file after merge")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.cmd_merge_delta import cmd_merge_delta
+    cmd_merge_delta(args)

cli/commands/metadata.py

@@ -0,0 +1,24 @@
+"""source-kb metadata — Pre-generate global metadata."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("metadata", help="Pre-generate global metadata for a module")
+    p.add_argument("--module-dir", required=True, help="Module directory")
+    p.add_argument("--module-name", help="Module name (defaults to directory name)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.metadata import pregenerate
+
+    module_dir = Path(args.module_dir)
+    output = pregenerate(module_dir, module_name=args.module_name or module_dir.name)
+    print(f"Generated: {output}")
+    print(json.dumps({"status": "ok", "output": str(output)}, ensure_ascii=False), file=sys.stderr)