code-context-control 2.58.0__tar.gz → 2.60.0__tar.gz

{code_context_control-2.58.0 → code_context_control-2.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.58.0
+Version: 2.60.0
 Summary: Local code-intelligence layer for AI coding tools (Claude Code, Codex, Copilot, Cursor, Antigravity). Retrieve less, read less, edit safer — version the configs that shape your agent (CLAUDE.md, skills, hooks, MCP), and manage multi-project + sub-project hierarchies from a local hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -243,6 +243,8 @@ Manage `CLAUDE.md`, `AGENTS.md` (Codex), `GEMINI.md`, and `.github/copilot-instr
 
 C3-generated content is wrapped in a `<!-- C3:BEGIN … -->` / `<!-- C3:END -->` block. Regenerating (or `Compact`) only rewrites that block — **anything you write outside it is preserved**, so it's safe to keep your own notes in the same file.
 
+**Live repo map (v2.60.0):** generated docs no longer embed a frozen project tree. They carry a stable pointer to `.c3/MAP.md` — a machine-owned, byte-stable map (commands, entry points, module one-liners, tree) that C3 refreshes automatically via edit hooks and a first-tool-call freshness check. Manage it with `c3 map status|ensure|refresh`; set `map.enabled=false` in `.c3/config.json` to restore the embedded tree.
+
 ### 7. Chat — browse prior AI conversations
 
 <p align="center">
@@ -358,6 +360,14 @@ global secrets (realm-atomic resolution, tested), cross-project shells run
 with credentials disabled, and the vault is hard-excluded from the Oracle
 Discovery API.
 
+Since **v2.59.0** the Hub has a top-level **Credentials** view: manage the
+global vault (`~/.c3`) and every registered project's entries from one place —
+create / edit / delete / `.env` import / flag toggles, with shadowing shown
+both ways ("shadows global" on project entries, "shadowed in N projects" on
+globals). The write-only wire contract extends to the hub: values are
+submitted inbound-only and **no hub route ever returns a stored value** (there
+is no `reveal` on the hub at all).
+
 ### Jira — Cloud + Data Center (v2.56.0)
 
 `c3_jira` connects to Jira Cloud (REST v3, email + API token) or self-hosted

{code_context_control-2.58.0 → code_context_control-2.60.0}/README.md

@@ -180,6 +180,8 @@ Manage `CLAUDE.md`, `AGENTS.md` (Codex), `GEMINI.md`, and `.github/copilot-instr
 
 C3-generated content is wrapped in a `<!-- C3:BEGIN … -->` / `<!-- C3:END -->` block. Regenerating (or `Compact`) only rewrites that block — **anything you write outside it is preserved**, so it's safe to keep your own notes in the same file.
 
+**Live repo map (v2.60.0):** generated docs no longer embed a frozen project tree. They carry a stable pointer to `.c3/MAP.md` — a machine-owned, byte-stable map (commands, entry points, module one-liners, tree) that C3 refreshes automatically via edit hooks and a first-tool-call freshness check. Manage it with `c3 map status|ensure|refresh`; set `map.enabled=false` in `.c3/config.json` to restore the embedded tree.
+
 ### 7. Chat — browse prior AI conversations
 
 <p align="center">
@@ -295,6 +297,14 @@ global secrets (realm-atomic resolution, tested), cross-project shells run
 with credentials disabled, and the vault is hard-excluded from the Oracle
 Discovery API.
 
+Since **v2.59.0** the Hub has a top-level **Credentials** view: manage the
+global vault (`~/.c3`) and every registered project's entries from one place —
+create / edit / delete / `.env` import / flag toggles, with shadowing shown
+both ways ("shadows global" on project entries, "shadowed in N projects" on
+globals). The write-only wire contract extends to the hub: values are
+submitted inbound-only and **no hub route ever returns a stored value** (there
+is no `reveal` on the hub at all).
+
 ### Jira — Cloud + Data Center (v2.56.0)
 
 `c3_jira` connects to Jira Cloud (REST v3, email + API token) or self-hosted

{code_context_control-2.58.0 → code_context_control-2.60.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.58.0"
+__version__ = "2.60.0"
 
 
 def _command_deps() -> CommandDeps:
@@ -1313,6 +1313,12 @@ def cmd_claudemd(args):
     return common_cmd_claudemd(args, _command_deps())
 
 
+def cmd_map(args):
+    """Live repo map (.c3/MAP.md) commands."""
+    from cli.commands.common import cmd_map as common_cmd_map
+    return common_cmd_map(args, _command_deps())
+
+
 def cmd_stats(args):
     """Show comprehensive stats."""
     return common_cmd_stats(args, _command_deps())
@@ -7162,6 +7168,7 @@ def main():
         "decode": cmd_decode,
         "session": cmd_session,
         "claudemd": cmd_claudemd,
+        "map": cmd_map,
         "stats": cmd_stats,
         "benchmark": cmd_benchmark,
         "session-benchmark": cmd_session_benchmark,

{code_context_control-2.58.0 → code_context_control-2.60.0}/cli/commands/common.py

@@ -159,6 +159,57 @@ def cmd_session(args, deps: CommandDeps):
         print(context)
 
 
+def cmd_map(args, deps: CommandDeps):
+    """Live repo map (.c3/MAP.md): status | ensure | refresh."""
+    config = deps.load_config()
+    project_path = config.get("project_path", ".")
+
+    from services.repo_map import RepoMapService
+
+    sm = deps.SessionManager(project_path)
+    svc = RepoMapService(project_path, session_mgr=sm)
+
+    if args.map_cmd == "status":
+        result = svc.status()
+    elif args.map_cmd == "ensure":
+        result = svc.ensure()
+    else:
+        result = svc.refresh()
+
+    if getattr(args, "json", False):
+        print(json.dumps(result, indent=2))
+        return
+
+    if args.map_cmd == "status":
+        state = "STALE" if result["stale"] else ("FRESH" if result["exists"] else "MISSING")
+        deps.print_header(f"Repo Map — {state}")
+        print(f"  Path: {svc.map_path}")
+        if result.get("generated_at"):
+            print(f"  Generated: {result['generated_at']}")
+        if result.get("tokens"):
+            print(f"  Tokens: {result['tokens']}")
+        if result.get("reasons"):
+            print(f"  Stale reasons: {', '.join(result['reasons'])}")
+        if result.get("truncated"):
+            print("  [WARN] Map is truncated (file cap or token budget hit)")
+    else:
+        action = result.get("action", "?")
+        label = {
+            "regenerated": "Map regenerated",
+            "meta_only": "Content unchanged (meta refreshed)",
+            "fresh": "Already fresh — nothing to do",
+            "locked": "Another process is regenerating — skipped",
+            "disabled": "Repo map disabled (map.enabled=false in .c3/config.json)",
+        }.get(action, action)
+        deps.print_header(f"Repo Map — {label}")
+        if result.get("tokens"):
+            print(f"  Tokens: {result['tokens']}, duration: {result.get('duration_ms', '?')}ms")
+        if result.get("reasons"):
+            print(f"  Triggered by: {', '.join(result['reasons'])}")
+        if result.get("truncated"):
+            print("  [WARN] Map is truncated (file cap or token budget hit)")
+
+
 def cmd_claudemd(args, deps: CommandDeps):
     """Instructions file generation commands."""
     config = deps.load_config()

{code_context_control-2.58.0 → code_context_control-2.60.0}/cli/commands/parser.py

@@ -61,6 +61,10 @@ def build_parser(version: str, parse_cli_ide_arg):
     p_claudemd.add_argument("claudemd_cmd", choices=["generate", "save", "check"])
     p_claudemd.add_argument("--nano", action="store_true", help="Generate nano mode (~250 tokens) instead of full compact mode")
 
+    p_map = subparsers.add_parser("map", help="Live repo map (.c3/MAP.md) management")
+    p_map.add_argument("map_cmd", choices=["status", "ensure", "refresh"])
+    p_map.add_argument("--json", action="store_true", help="Emit JSON result")
+
     subparsers.add_parser("stats", help="Show statistics")
 
     p_benchmark = subparsers.add_parser("benchmark", help="Run with/without-C3 workflow benchmark")

{code_context_control-2.58.0 → code_context_control-2.60.0}/cli/guide/tools.html

@@ -125,6 +125,8 @@
       <div class="sidebar-label">SCM</div>
       <a href="#c3_task" class="sidebar-link"><span class="icon">✅</span> c3_task</a>
       <a href="#c3_bitbucket" class="sidebar-link"><span class="icon">🪣</span> c3_bitbucket</a>
+      <a href="#c3_credentials" class="sidebar-link"><span class="icon">🔐</span> c3_credentials</a>
+      <a href="#c3_jira" class="sidebar-link"><span class="icon">🎫</span> c3_jira</a>
     </div>
     <div class="sidebar-section">
       <div class="sidebar-label">Cross-project</div>
@@ -161,6 +163,8 @@
         <a href="#c3_task" class="toc-item">c3_task <span class="cat">PM</span></a>
         <a href="#c3_artifacts" class="toc-item">c3_artifacts <span class="cat">Config</span></a>
         <a href="#c3_bitbucket" class="toc-item">c3_bitbucket <span class="cat">SCM</span></a>
+        <a href="#c3_credentials" class="toc-item">c3_credentials <span class="cat">Secrets</span></a>
+        <a href="#c3_jira" class="toc-item">c3_jira <span class="cat">Issues</span></a>
         <a href="#c3_project"  class="toc-item">c3_project  <span class="cat">Multi-project</span></a>
       </div>
     </div>
@@ -1239,6 +1243,96 @@ c3_bitbucket(action=<span class="str">'merge_pr'</span>, pr_id=<span class="num"
           <p class="tool-desc"><strong>Audit trail:</strong> mutating actions (<code>merge_pr</code>, <code>create_branch</code>, <code>delete_branch</code>, webhook writes, etc.) are appended to the C3 edit ledger so the local audit log covers platform-side state changes too.</p>
         </div>
       </div>
+
+      <!-- c3_credentials -->
+      <div class="tool-card" id="c3_credentials">
+        <div class="tool-card-header">
+          <span class="tool-name">c3_credentials</span>
+          <div class="tag-row">
+            <span class="badge badge-purple">secrets</span>
+            <span class="badge">v2.58.0</span>
+          </div>
+          <span class="tool-tagline">Credential vault — the agent uses secrets by name, never by value</span>
+        </div>
+        <div class="tool-card-body">
+          <p class="tool-desc">A user-managed secret store, <strong>global</strong> (<code>~/.c3</code>, visible in every project) or <strong>per-project</strong> (<code>.c3</code>, shadows the same-named global). Values live in the OS keyring (service <code>c3-creds</code>; values over ~1KB in a Fernet-encrypted <code>.c3/secrets.enc</code> whose random master key is itself a keyring entry) — never in config files, and <em>never in the model's context</em>. <strong>Injection-first:</strong> the agent addresses secrets by name and C3 decodes them only at the subprocess boundary — <code>c3_shell(env_creds='A,B')</code> injects env vars, <code>{{cred:NAME}}</code> inside <code>cmd</code> expands server-side, and <code>inject</code>-flagged entries auto-inject into every shell run; echoed values are redacted back to <code>[cred:NAME]</code>. Resolution is <strong>realm-atomic</strong>: a project-registered name resolves in the project realm or not at all, so a hostile repo's committed config can never siphon your global values (tested).</p>
+
+          <h4>Actions</h4>
+          <table class="params-table">
+            <thead><tr><th>Action</th><th>Group</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td class="param-name">list</td><td>Read</td><td class="param-desc">Merged registry (project shadows global) — names, scope, type, flags, usage. Never values</td></tr>
+              <tr><td class="param-name">describe</td><td>Read</td><td class="param-desc">Metadata + storage + live fingerprint (first 8 hex of SHA-256, computed on demand, never persisted)</td></tr>
+              <tr><td class="param-name">check</td><td>Read</td><td class="param-desc">Resolvability probe — does the stored value decode?</td></tr>
+              <tr><td class="param-name">set</td><td>Write</td><td class="param-desc">Create/replace an entry. <code>agent_readable</code> may be set at creation only — raising it on an existing entry is user-only</td></tr>
+              <tr><td class="param-name">delete</td><td>Write</td><td class="param-desc">Remove value + registry entry (owning scope inferred when omitted)</td></tr>
+              <tr><td class="param-name">reveal</td><td>Gated</td><td class="param-desc">The only value-returning action — refused unless the user enabled <code>agent_readable</code> on that entry</td></tr>
+            </tbody>
+          </table>
+
+          <h4>Examples</h4>
+          <pre><code><span class="com"># What can I use? (names and metadata only)</span>
+c3_credentials(action=<span class="str">'list'</span>)
+c3_credentials(action=<span class="str">'check'</span>, name=<span class="str">'NPM_TOKEN'</span>)
+
+<span class="com"># USE a secret without ever seeing it</span>
+c3_shell(cmd=<span class="str">'npm publish'</span>, env_creds=<span class="str">'NPM_TOKEN'</span>)
+c3_shell(cmd=<span class="str">'curl -H "Authorization: Bearer {{cred:API_KEY}}" https://api.example.com'</span>)</code></pre>
+
+          <p class="tool-desc"><strong>Surfaces:</strong> the <code>c3 creds</code> CLI (<code>set</code> / <code>get</code> / <code>list</code> / <code>rm</code> / <code>import .env</code>, <code>--global</code> for the shared scope), a per-project dashboard <strong>Credentials</strong> tab, and — since v2.59.0 — a top-level <strong>Credentials</strong> view in the Hub: a Global-vault manager plus a per-project browser with shadowing shown both ways ("shadows global" on project entries, "shadowed in N projects" on globals); the Hub's per-project drill panel manages too. No HTTP route ever returns a stored value (write-only wire contract, endpoint-sweep tested), every mutation is ledger-logged by name, the vault is hard-excluded from the Oracle Discovery API, and cross-project (<code>c3_project</code>) shells run with credentials disabled.</p>
+        </div>
+      </div>
+
+      <!-- c3_jira -->
+      <div class="tool-card" id="c3_jira">
+        <div class="tool-card-header">
+          <span class="tool-name">c3_jira</span>
+          <div class="tag-row">
+            <span class="badge badge-purple">issue tracking</span>
+            <span class="badge">v2.56.0</span>
+          </div>
+          <span class="tool-tagline">Jira Cloud + Data Center — search, create, transition, comment through one tool</span>
+        </div>
+        <div class="tool-card-body">
+          <p class="tool-desc">One tool for both Jira deployments: <strong>Cloud</strong> (REST v3, email + API token, ADF bodies handled transparently) and self-hosted <strong>Data Center / Server</strong> (REST v2, PAT Bearer, plain-text bodies) — normalized to a single DTO surface with an opaque pagination cursor. Transport is stdlib <code>urllib</code> (no new dependencies); reads get one bounded 429 retry honoring <code>Retry-After</code>, mutations are <em>never</em> auto-retried. Tokens live in the OS keyring keyed by <code>(base_url, username)</code>; the <code>jira</code> config section resolves project → home <strong>wholesale from a single file</strong>, so a repository's committed config can never field-override a home account's URL or TLS settings (credential-redirect hardening). HTTPS-only.</p>
+
+          <p class="tool-desc"><strong>Setup:</strong> <code>c3 jira login --url https://yoursite.atlassian.net</code> (Cloud inferred for <code>*.atlassian.net</code>; add <code>--deployment data_center</code> for self-hosted, <code>--ca-bundle</code> for enterprise certs, <code>--global</code> for a home config reusable across projects), then <code>c3 jira set-default --project PROJ</code>. Manage accounts with <code>c3 jira status / use / logout</code>.</p>
+
+          <h4>Actions</h4>
+          <table class="params-table">
+            <thead><tr><th>Action</th><th>Group</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td class="param-name">status, whoami</td><td>Read</td><td class="param-desc">Active account, deployment, defaults, server probe / authenticated user</td></tr>
+              <tr><td class="param-name">search</td><td>Read</td><td class="param-desc">Raw JQL, paginated (helper-built JQL elsewhere is always quoted)</td></tr>
+              <tr><td class="param-name">my_issues</td><td>Read</td><td class="param-desc">Open issues assigned to the token's user (statusCategory-aware)</td></tr>
+              <tr><td class="param-name">get_issue, list_projects, list_transitions</td><td>Read</td><td class="param-desc">Issue detail with comments / project discovery / legal transitions for an issue</td></tr>
+              <tr><td class="param-name">get_create_metadata, search_users</td><td>Read</td><td class="param-desc">Required + allowed fields per project/type; user lookup for assignment</td></tr>
+              <tr><td class="param-name">create_issue</td><td>Write</td><td class="param-desc">Pre-validates against create metadata and returns machine-readable missing required fields instead of guessing defaults</td></tr>
+              <tr><td class="param-name">comment, transition, assign</td><td>Write</td><td class="param-desc">Comment on / move (accepts transition id <em>or</em> name) / assign an issue</td></tr>
+            </tbody>
+          </table>
+
+          <h4>Examples</h4>
+          <pre><code><span class="com"># Connection + account probe, then my open work</span>
+c3_jira(action=<span class="str">'status'</span>)
+c3_jira(action=<span class="str">'my_issues'</span>)
+
+<span class="com"># Raw JQL search</span>
+c3_jira(action=<span class="str">'search'</span>, jql=<span class="str">'project = PROJ AND status != Done ORDER BY updated DESC'</span>)
+
+<span class="com"># Create — required fields come from metadata, not guesses</span>
+c3_jira(action=<span class="str">'get_create_metadata'</span>, project=<span class="str">'PROJ'</span>, issue_type=<span class="str">'Task'</span>)
+c3_jira(action=<span class="str">'create_issue'</span>, project=<span class="str">'PROJ'</span>, issue_type=<span class="str">'Task'</span>,
+        summary=<span class="str">'Fix login flow'</span>, description=<span class="str">'Steps in thread'</span>)
+
+<span class="com"># Move it along — id or name both work</span>
+c3_jira(action=<span class="str">'list_transitions'</span>, issue=<span class="str">'PROJ-123'</span>)
+c3_jira(action=<span class="str">'transition'</span>, issue=<span class="str">'PROJ-123'</span>, transition=<span class="str">'In Progress'</span>)
+c3_jira(action=<span class="str">'comment'</span>, issue=<span class="str">'PROJ-123'</span>, body=<span class="str">'Deployed to staging'</span>)</code></pre>
+
+          <p class="tool-desc"><strong>Surfaces &amp; audit:</strong> the per-project dashboard gets a <strong>Jira tab</strong> (My Work board grouped by statusCategory, JQL search, an issue drawer with transition buttons + comments, and an Activity view) backed by <code>/api/jira/*</code> routes. Issue keys like <code>PROJ-123</code> are auto-linked from branch names and edit-ledger entries (acronym denylist, so UTF-8 / SHA-256 / CVE-2024 never match), and the issue drawer shows the local ledger activity for the open issue — that Activity view works with no account configured. Mutations (<code>create_issue</code>, <code>comment</code>, <code>transition</code>, <code>assign</code>) are edit-ledger-logged with identifiers only — bodies are never logged. Read actions are safe in plan mode.</p>
+        </div>
+      </div>
     </div>
 
     <!-- ═══════════════════════════════════════ CROSS-PROJECT ═════ -->

{code_context_control-2.58.0 → code_context_control-2.60.0}/cli/guide/workflow.html

@@ -250,6 +250,7 @@
       <a href="#session-restart" class="sidebar-link"><span class="icon">🔄</span> Session Restart</a>
       <a href="#terse-skill" class="sidebar-link"><span class="icon">⚡</span> /terse Skill</a>
       <a href="#subprojects" class="sidebar-link"><span class="icon">🌳</span> Sub-projects</a>
+      <a href="#repo-map" class="sidebar-link"><span class="icon">🗺️</span> Live Repo Map</a>
       <a href="#native-fallback" class="sidebar-link"><span class="icon">⚠️</span> Native Fallback</a>
     </div>
   </aside>
@@ -984,6 +985,53 @@ c3_memory(action=<span class="str">'recall'</span>, query=<span class="str">'pay
 
     <hr class="divider">
 
+    <!-- Live repo map -->
+    <section class="section" id="repo-map">
+      <div class="section-title"><span class="icon">🗺️</span> Live Repo Map (v2.60.0)</div>
+
+      <p>Instruction docs (CLAUDE.md / AGENTS.md) no longer embed a frozen project tree. They carry a stable pointer to <code>.c3/MAP.md</code> — a machine-owned map C3 keeps fresh automatically. One map serves every consumer: Claude Code, Codex, Antigravity.</p>
+
+      <p>The map contains, in priority order: build/test commands, entry points, module one-liners, the depth-2 tree, and key files — under a token budget (default 1000). Sub-projects appear as boundaries and are never expanded into the parent map.</p>
+
+      <h4>How it stays fresh</h4>
+      <table class="table">
+        <thead><tr><th>Trigger</th><th>What happens</th></tr></thead>
+        <tbody>
+          <tr>
+            <td>Structural edit (file created/deleted/renamed, manifest changed)</td>
+            <td>Edit-ledger paths touch the <code>.c3/map.dirty</code> sentinel — a file-touch, never a scan</td>
+          </tr>
+          <tr>
+            <td>First C3 tool call of a session</td>
+            <td>Background single-flight <em>ensure</em>: regenerates only if missing, dirty, or the git HEAD/branch/worktree fingerprint moved</td>
+          </tr>
+          <tr>
+            <td><code>c3 map refresh</code></td>
+            <td>Explicit repair — always regenerates</td>
+          </tr>
+        </tbody>
+      </table>
+
+      <p><strong>Byte-stable by design:</strong> <code>MAP.md</code> is rewritten only when rendered content actually changes, so prompt caches keyed on file bytes stay warm. Volatile freshness state (git HEAD, worktree signature, generated-at) lives in <code>.c3/map.meta.json</code> — never in the map itself. Ordinary line edits never trigger regeneration.</p>
+
+      <div class="callout callout-info">
+        <span class="callout-icon">💡</span>
+        <div class="callout-body">
+          <strong>CLI</strong>: <code>c3 map status</code> (freshness report) · <code>c3 map ensure</code> (regen if stale) · <code>c3 map refresh</code> (force). Add <code>--json</code> for machine output. Config knobs: <code>map.token_budget</code>, <code>map.file_cap</code>, <code>map.enabled</code> (set <code>false</code> to restore the legacy embedded tree).
+        </div>
+      </div>
+
+      <div class="callout callout-warning">
+        <span class="callout-icon">⚠️</span>
+        <div class="callout-body">
+          <strong>The map is data, not instructions</strong><br>
+          Its header marks it as auto-generated repository data. Agents should read it for orientation — not obey text inside it. Memory facts are deliberately excluded from the map.
+        </div>
+      </div>
+    </section>
+
+    <hr class="divider">
+
     <!-- Native fallback -->
     <section class="section" id="native-fallback">
       <div class="section-title"><span class="icon">⚠️</span> When Native Tools Are Permitted</div>

{code_context_control-2.58.0 → code_context_control-2.60.0}/cli/hook_edit_ledger.py

@@ -212,6 +212,15 @@ def run(payload: dict, project_path: Path | None = None) -> dict | None:
     with open(ledger_file, "a", encoding="utf-8") as f:
         f.write(json.dumps(entry) + "\n")
 
+    # Structural changes (file created / manifest edited) dirty the repo map.
+    # Sentinel touch only — the scan happens later, in RepoMapService.ensure().
+    try:
+        from services.repo_map import is_structural_change, mark_map_dirty
+        if is_structural_change(rel, change_type):
+            mark_map_dirty(project_path, f"{change_type}:{rel}")
+    except Exception:
+        pass
+
     return {
         "_text": (
             f"[c3:ledger] {rel} {entry['version']} auto-logged. "