ckgraphify 0.1.2__tar.gz → 0.1.3__tar.gz

{ckgraphify-0.1.2 → ckgraphify-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ckgraphify
-Version: 0.1.2
+Version: 0.1.3
 Summary: AI coding assistant skill for Claude Code and Codex - graph-main boundary graphs, multi-repo call chains, business-map concepts, and business search
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/safishamsi/graphify

{ckgraphify-0.1.2 → ckgraphify-0.1.3}/graphify/__main__.py

@@ -97,7 +97,15 @@ def _claude_plugin_root() -> Path | None:
     return Path(raw).expanduser().resolve() if raw else None
 
 
+def _claude_project_dir() -> Path | None:
+    raw = os.environ.get("CLAUDE_PROJECT_DIR", "").strip()
+    return Path(raw).expanduser().resolve() if raw else None
+
+
 def _default_repos_root() -> Path:
+    project_dir = _claude_project_dir()
+    if project_dir is not None:
+        return project_dir / "repos"
     plugin_root = _claude_plugin_root()
     if plugin_root is not None:
         return plugin_root / "repos"

{ckgraphify-0.1.2 → ckgraphify-0.1.3}/graphify/graph_main_backend.py

@@ -1385,6 +1385,7 @@ def build_graph_main_backend(*, repo_root: Path, out_path: Path) -> GraphMainBac
         "graph": {
             "kind": "graph-main-backend",
             "description": "Back-end focused graph (hsf/rest/mtop/dependency/metaq)",
+            "repo_name": repo_root.name,
             "mode": mode,
             "sdk_detection": sdk,
         },

{ckgraphify-0.1.2 → ckgraphify-0.1.3}/graphify/graph_main_frontend.py

@@ -1178,6 +1178,7 @@ def build_graph_main_frontend(*, repo_root: Path, out_path: Path) -> GraphMainFr
         "graph": {
             "kind": "graph-main-frontend",
             "description": "Front-end graph (page/component/api)",
+            "repo_name": repo_root.name,
             "mode": mode,
             "frontend_detection": detection,
         },

{ckgraphify-0.1.2 → ckgraphify-0.1.3}/graphify/graph_main_merge.py

@@ -62,24 +62,21 @@ def _edge_key(edge: dict) -> tuple[str, str, str, str]:
     )
 
 
-def _copy_node(repo: str, repo_root: str, graph_path: Path, node: dict) -> dict:
+def _copy_node(repo: str, node: dict) -> dict:
     out = dict(node)
     local_id = str(node.get("id", ""))
     out["id"] = _node_key(repo, local_id)
     out["local_id"] = local_id
     out["repo"] = repo
-    out["repo_root"] = repo_root
-    out["graph_main_path"] = str(graph_path)
     out.setdefault("main_kind", "unknown")
     return out
 
 
-def _copy_edge(repo: str, graph_path: Path, edge: dict) -> dict:
+def _copy_edge(repo: str, edge: dict) -> dict:
     out = dict(edge)
     out["source"] = _node_key(repo, edge.get("source", ""))
     out["target"] = _node_key(repo, edge.get("target", ""))
     out["repo"] = repo
-    out["graph_main_path"] = str(graph_path)
     out["edge_scope"] = "intra_repo"
     return out
 
@@ -94,7 +91,6 @@ def _shared_api_node(anchor: str, originals: list[dict]) -> dict:
             "local_id": str(n.get("local_id", "")),
             "source_file": str(n.get("source_file", "")),
             "source_location": str(n.get("source_location", "")),
-            "graph_main_path": str(n.get("graph_main_path", "")),
         }
         for n in originals
     ]
@@ -192,6 +188,7 @@ def merge_graph_main_files(graph_paths: Iterable[Path], out_path: Path) -> Graph
     edges: list[dict] = []
     edge_seen: set[tuple[str, str, str, str]] = set()
     repos: list[dict] = []
+    repo_roots: dict[str, str] = {}
     id_to_node: dict[str, dict] = {}
     canonical_index: dict[str, list[str]] = defaultdict(list)
     kind_index: dict[str, dict[str, list[str]]] = defaultdict(lambda: defaultdict(list))
@@ -203,11 +200,10 @@ def merge_graph_main_files(graph_paths: Iterable[Path], out_path: Path) -> Graph
             raise FileNotFoundError(f"graph-main not found: {path}")
         data = _load_graph(path)
         repo = _repo_from_path(path)
-        repo_root = str(data.get("graph", {}).get("repo_root", "")) or str(path.parent.parent)
+        repo_root_abs = path.parent.parent
+        repo_roots[repo] = f"repos/{repo}"
         repo_meta = {
             "repo": repo,
-            "graph_path": str(path),
-            "repo_root": repo_root,
             "kind": data.get("graph", {}).get("kind", ""),
             "mode": data.get("graph", {}).get("mode", ""),
             "nodes": len(data.get("nodes", [])),
@@ -216,7 +212,7 @@ def merge_graph_main_files(graph_paths: Iterable[Path], out_path: Path) -> Graph
         repos.append(repo_meta)
 
         for node in data.get("nodes", []):
-            copied = _copy_node(repo, repo_root, path, node)
+            copied = _copy_node(repo, node)
             nid = str(copied.get("id", ""))
             nodes.append(copied)
             id_to_node[nid] = copied
@@ -230,7 +226,7 @@ def merge_graph_main_files(graph_paths: Iterable[Path], out_path: Path) -> Graph
                 metaq_topic_index[topic_key].append(nid)
 
         for edge in data.get("links", []):
-            copied = _copy_edge(repo, path, edge)
+            copied = _copy_edge(repo, edge)
             key = _edge_key(copied)
             if key in edge_seen:
                 continue
@@ -433,6 +429,7 @@ def merge_graph_main_files(graph_paths: Iterable[Path], out_path: Path) -> Graph
             "description": "Merged graph-main boundary graph with cross-repo semantic resolution edges",
             "generated_at": report["generated_at"],
             "repo_count": len(repos),
+            "repo_roots": repo_roots,
             "repos": repos,
         },
         "nodes": nodes,

{ckgraphify-0.1.2 → ckgraphify-0.1.3}/graphify/graph_main_trace.py

@@ -24,10 +24,11 @@ _TRACE_RELS = {
 }
 
 
-def _load_graph(path: Path) -> tuple[list[dict], list[dict]]:
+def _load_graph(path: Path) -> tuple[list[dict], list[dict], dict[str, str]]:
     data = json.loads(path.read_text(encoding="utf-8"))
     links = data.get("links", data.get("edges", []))
-    return list(data.get("nodes", [])), list(links)
+    repo_roots = data.get("graph", {}).get("repo_roots", {})
+    return list(data.get("nodes", [])), list(links), repo_roots
 
 
 def _norm(v: object) -> str:
@@ -96,8 +97,9 @@ def _source_ref(node: dict) -> str:
     return source_file or source_location or "-"
 
 
-def _append_source_summary(lines: list[str], ordered_node_ids: list[str], by_id: dict[str, dict]) -> None:
+def _append_source_summary(lines: list[str], ordered_node_ids: list[str], by_id: dict[str, dict], repo_roots: dict[str, str] | None = None) -> None:
     lines.extend(["", "Sources:"])
+    rr = repo_roots or {}
     for node_id in ordered_node_ids:
         node = by_id[node_id]
         lines.append(f"- {_node_text(node)}")
@@ -108,16 +110,16 @@ def _append_source_summary(lines: list[str], ordered_node_ids: list[str], by_id:
                 source_file = str(origin.get("source_file") or "")
                 source_location = str(origin.get("source_location") or "")
                 ref = f"{source_file}:{source_location}" if source_file and source_location else (source_file or source_location or "-")
-                lines.append(f"  origin: {repo} {ref}")
+                root = rr.get(repo, "")
+                full_ref = f"{root}/{ref}" if root else ref
+                lines.append(f"  origin: {repo} {full_ref}")
         else:
-            repo_root = str(node.get("repo_root") or "")
-            graph_path = str(node.get("graph_main_path") or "")
-            lines.append(f"  repo: {node.get('repo', '')}")
-            lines.append(f"  file: {_source_ref(node)}")
-            if repo_root:
-                lines.append(f"  repo_root: {repo_root}")
-            if graph_path:
-                lines.append(f"  graph_main: {graph_path}")
+            repo = str(node.get("repo", ""))
+            root = rr.get(repo, "")
+            ref = _source_ref(node)
+            full_ref = f"{root}/{ref}" if root and ref != "-" else ref
+            lines.append(f"  repo: {repo}")
+            lines.append(f"  file: {full_ref}")
 
 
 def _matches(node: dict, query: str, *, kinds: set[str] | None = None) -> bool:
@@ -179,7 +181,7 @@ def trace_graph_main(
     prefer_repos: list[str] | tuple[str, ...] | set[str] | None = None,
     exclude_repos: list[str] | tuple[str, ...] | set[str] | None = None,
 ) -> str:
-    nodes, links = _load_graph(graph_path)
+    nodes, links, repo_roots = _load_graph(graph_path)
     by_id = {str(n.get("id", "")): n for n in nodes}
     start = _pick_node(
         nodes,
@@ -318,5 +320,5 @@ def trace_graph_main(
     else:
         walk(start_id, 0, {start_id}, "")
     if include_sources:
-        _append_source_summary(lines, ordered_node_ids, by_id)
+        _append_source_summary(lines, ordered_node_ids, by_id, repo_roots)
     return "\n".join(lines)

{ckgraphify-0.1.2 → ckgraphify-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ckgraphify"
-version = "0.1.2"
+version = "0.1.3"
 description = "AI coding assistant skill for Claude Code and Codex - graph-main boundary graphs, multi-repo call chains, business-map concepts, and business search"
 readme = "README.md"
 license = "MIT"

{ckgraphify-0.1.2 → ckgraphify-0.1.3}/skill/skill.md

@@ -6,6 +6,18 @@ trigger: /ckgraphify
 
 # ckgraphify Skill
 
+## Prerequisites
+
+Before running any `graphify` command, ensure the CLI is available. Run this check once per session:
+
+```bash
+command -v graphify >/dev/null 2>&1 || python3 -m pip install ckgraphify 2>/dev/null || true
+```
+
+If the install fails silently, tell the user to run `pip install ckgraphify` manually.
+
+---
+
 ckgraphify helps users ask business questions without knowing exact graph node names.
 
 The public API is `/ckgraphify ...`. Treat it as an assistant API: translate it into `graphify` CLI calls, graph inspection, focused code reading, or a learn candidate patch workflow as needed.
@@ -52,15 +64,27 @@ Show this API briefly.
 ## Execution Defaults
 
 - `--path` can point to a workspace, repos root, repo list, or a merged graph JSON. Resolve it before running CLI commands.
-- Claude Code plugin root:
-  - Use `${CLAUDE_PLUGIN_ROOT}` as the ckgraphify workspace root.
-  - Default repos root is `${CLAUDE_PLUGIN_ROOT}/repos`.
+- Two root directories:
+  - `${CLAUDE_PLUGIN_ROOT}` — installed plugin directory (graph data, map, evidence).
+  - `${CLAUDE_PROJECT_DIR}` — the project that installed the plugin (repos, pypi source, docs).
+- Graph and business map (read/write):
   - Default business map is `${CLAUDE_PLUGIN_ROOT}/graphify-out/business-map.json`.
+  - Default evidence shadow table is `${CLAUDE_PLUGIN_ROOT}/graphify-out/business-map-evidence.json`.
   - Default merged graph is `${CLAUDE_PLUGIN_ROOT}/graphify-out/graph-hc.json`.
-  - If `${CLAUDE_PLUGIN_ROOT}` is missing, report that the Claude plugin environment is not active instead of falling back to a relative kg-banks path.
-- Default map environment:
-  - Use `--map`, then `${CLAUDE_PLUGIN_ROOT}/graphify-out/business-map.json`.
-- Default graph: use `--graph`, then a JSON passed via `--path`, then `${CLAUDE_PLUGIN_ROOT}/graphify-out/graph-hc.json`, then the graph bound in `business-map.json` (`graph.path`), then `${CLAUDE_PLUGIN_ROOT}/graphify-out/graph*.json`.
+- Repos (code reading, main-graph generation):
+  - Default repos root is `${CLAUDE_PROJECT_DIR}/repos`.
+  - Each repo's graph-main output is `${CLAUDE_PROJECT_DIR}/repos/<repo>/graphify-out/graph-main.json`.
+- Docs and policies (read-only, bundled with pypi source):
+  - `${CLAUDE_PROJECT_DIR}/ckgraphify/docs/business-map-policy.md`
+- Sync: after writing to `${CLAUDE_PLUGIN_ROOT}/graphify-out/`, sync changes back to the project source:
+
+  ```bash
+  cp "${CLAUDE_PLUGIN_ROOT}/graphify-out/business-map.json" "${CLAUDE_PROJECT_DIR}/claude-plugin/graphify-out/business-map.json"
+  cp "${CLAUDE_PLUGIN_ROOT}/graphify-out/business-map-evidence.json" "${CLAUDE_PROJECT_DIR}/claude-plugin/graphify-out/business-map-evidence.json"
+  ```
+
+- If `${CLAUDE_PLUGIN_ROOT}` is missing, report that the Claude plugin environment is not active.
+- If `${CLAUDE_PROJECT_DIR}` is missing, report that repos and docs are not available for code reading.
 - Default depth: `10`.
 - Default answer: concise business result first, evidence second, gaps last.
 - If required inputs are missing and cannot be inferred from files, ask one short clarification.
@@ -76,8 +100,8 @@ graphify business-lint --map <map>
 graphify business-validate --map <map> --graph <graph>
 graphify business-trace --map <map> --graph <graph> --concept <concept> --scenario <scenario> --flow <flow> --max-depth <n> --sources
 graphify main-trace --graph <graph> --from <exact-node> --api <api> --max-depth <n> --sources --prefer-repo <repo> --exclude-repo <repo>
-graphify main-graph "${CLAUDE_PLUGIN_ROOT}/repos/<repo>" --out "${CLAUDE_PLUGIN_ROOT}/repos/<repo>/graphify-out/graph-main.json"
-graphify merge-main-graphs "${CLAUDE_PLUGIN_ROOT}/repos/<repo-a>/graphify-out/graph-main.json" "${CLAUDE_PLUGIN_ROOT}/repos/<repo-b>/graphify-out/graph-main.json" --out "${CLAUDE_PLUGIN_ROOT}/graphify-out/graph-hc.json"
+graphify main-graph "${CLAUDE_PROJECT_DIR}/repos/<repo>" --out "${CLAUDE_PROJECT_DIR}/repos/<repo>/graphify-out/graph-main.json"
+graphify merge-main-graphs "${CLAUDE_PROJECT_DIR}/repos/<repo-a>/graphify-out/graph-main.json" "${CLAUDE_PROJECT_DIR}/repos/<repo-b>/graphify-out/graph-main.json" --out "${CLAUDE_PLUGIN_ROOT}/graphify-out/graph-hc.json"
 ```
 
 ## Graph Scope
@@ -86,6 +110,15 @@ Treat the merged graph as business navigation, not as a complete execution trace
 
 Do not expect `graph-hc.json` or other merged graphs to describe every parameter, response field, extension point, or method-local branch. That level of detail would make the graph too large and noisy. When a question depends on field-level or parameter-level behavior, first use `main-trace` and source filepaths to land on the right code, then read the relevant implementation directly.
 
+### File path convention
+
+Merged graphs store source paths as **relative paths** per repo. To resolve the full path for code reading:
+
+- `graph.repo_roots` maps each repo name to its relative root, e.g. `{"p": "repos/p", "ele-newretail-drug": "repos/ele-newretail-drug"}`.
+- Each node has `repo` (repo name) and `source_file` (relative to the repo root).
+- Full path = `${CLAUDE_PROJECT_DIR}` + `/` + `repo_roots[node.repo]` + `/` + `node.source_file`.
+- `main-trace --sources` already outputs resolved paths in `repos/<repo>/<file>` format.
+
 Missing field-level graph evidence is not automatically a graph defect. Classify it as one of:
 
 - graph navigation succeeded, code reading verified the detail;
@@ -113,15 +146,16 @@ Search discipline:
 For `/ckgraphify learn`:
 
 1. Require concept, scenario, repos, graph, map, and out.
-2. Read `ckgraphify/docs/business-map-policy.md`; every map iteration must follow it or explicitly report the conflict.
+2. Read `${CLAUDE_PROJECT_DIR}/ckgraphify/docs/business-map-policy.md`; every map iteration must follow it or explicitly report the conflict.
 3. Read existing map scenarios, flows, gaps, accepted gaps, verification scopes, and `search_constraints`.
 4. Search graph nodes with aliases, keywords, page/API names, HSF names, and repo hints.
 5. Run `main-trace` on promising graph matches.
 6. Validate important links in code, especially when the answer depends on response fields, request parameters, extension points, or method-local branching.
-7. For a simple branch, write a candidate patch to `--out` with scenario-level anchors, trace hints, verification scope, boundaries, and remaining gaps. Keep detailed source evidence in `graphify-out/business-map-evidence.json`, not in `business-map.json`.
+7. For a simple branch, write a candidate patch to `--out` with scenario-level anchors, trace hints, verification scope, boundaries, and remaining gaps. Keep detailed source evidence in `${CLAUDE_PLUGIN_ROOT}/graphify-out/business-map-evidence.json`, not in `business-map.json`.
 8. For a complex branch, write one scenario with `flows`; each flow may have `id`, `name`, `status`, `summary`, `verification_scope`, `anchors`, `trace_hints`, `gaps`, and `accepted_gaps`. Keep `business-map.json` compact; use the evidence shadow table for source proof.
 9. Do not split a user's named complex scenario into multiple top-level scenarios unless the user asks for that model.
 10. Run `business-lint` and `business-validate`; run `business-trace` if hints are usable.
+11. After writing to `${CLAUDE_PLUGIN_ROOT}/graphify-out/`, sync changes back to `${CLAUDE_PROJECT_DIR}/claude-plugin/graphify-out/`.
 
 ## Answer Contract
 
@@ -140,7 +174,7 @@ Keep graph-main schema details, dependency extraction rules, and low-level branc
 ## Guardrails
 
 - Do not write business semantics into `graph-main.json`.
-- Before changing `business-map.json`, read `ckgraphify/docs/business-map-policy.md`; follow it or state the conflict.
+- Before changing `business-map.json`, read `${CLAUDE_PROJECT_DIR}/ckgraphify/docs/business-map-policy.md`; follow it or state the conflict.
 - Use `scenario.flows[]` for sub-links inside one complex business scene, such as landing page purchase/refund/benefit branches.
 - Keep `business-map.json` as a search/trace index. Do not add long `evidence` arrays there; put audit proof in `graphify-out/business-map-evidence.json`.
 - Use `gaps` for active unknowns and `accepted_gaps` for known boundaries with a stop rule.