braingent 0.1.0__tar.gz

braingent-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+__pycache__/
+.venv/
+*.swp
+*.tmp
+.braingent.db
+.braingent.db-*
+.test-plans/
+uv.lock
+dashboard/tasks/.tanstack/
+dashboard/tasks/dist/
+dashboard/tasks/node_modules/
+dashboard/tasks/playwright-report/
+dashboard/tasks/test-results/

braingent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JJ Adonis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

braingent-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: braingent
+Version: 0.1.0
+Summary: Durable engineering memory CLI: doctor, reindex, find, recall, synthesize, MCP, and QA test-plan generation.
+Project-URL: Homepage, https://github.com/thedoublejay/braingent-manifesto
+Project-URL: Source, https://github.com/thedoublejay/braingent-manifesto
+Project-URL: Issues, https://github.com/thedoublejay/braingent-manifesto/issues
+Author: JJ Adonis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,mcp,memory,qa,test-plans
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: pyyaml<7,>=6.0.3
+Provides-Extra: dev
+Requires-Dist: build>=1.5.0; extra == 'dev'
+Requires-Dist: hatchling>=1.30.1; extra == 'dev'
+Requires-Dist: mypy>=2.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.1.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.17; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.12.20260518; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27.2; extra == 'mcp'
+Provides-Extra: tokens
+Requires-Dist: tiktoken<1,>=0.13.0; extra == 'tokens'
+Description-Content-Type: text/markdown
+
+# Braingent Memory Repo
+
+This is a Markdown-first engineering memory repository based on Braingent, created by JJ Adonis.
+
+Use it as a durable memory layer for AI-assisted software engineering work. Claude, Codex, ChatGPT, and other tools should read this repo before planning meaningful work and should capture important outcomes after the work is done.
+
+## What Goes Here
+
+- Project and repository profiles.
+- Task records.
+- Code review records.
+- Decision records.
+- Reusable learnings.
+- Tool and version notes.
+- Ticket stubs for cross-cutting work.
+- Optional live `BGT-NNNN` agent tasks for active coordination.
+- Optional dashboard docs for a read-only live task UI.
+- An installable `braingent` helper CLI for search, validation, reindexing,
+  task files, MCP retrieval, and QA generation.
+- The packaged QA generator for Markdown, Xray JSON, TestRail CSV, and Gherkin
+  outputs.
+- Raw imports before they are summarized.
+- Preferences that guide future AI agents.
+
+## Read First
+
+Agents should start here:
+
+1. `AGENTS.md` or `CLAUDE.md`, depending on the tool.
+2. `INDEX.md`.
+3. `CURRENT_STATE.md`.
+4. `preferences/`.
+5. `tasks/INDEX.md` if live tasks are enabled and the work may already be active.
+6. Relevant organization, project, repository, topic, tool, ticket, or person records.
+
+## Core Workflow
+
+Before work:
+
+- Read the root instructions.
+- Search memory for relevant context.
+- Check live tasks before creating overlapping active work.
+- Reuse prior decisions and conventions.
+
+During work:
+
+- Track decisions, versions, commands, failures, fixes, tickets, PRs, branches, and follow-ups.
+- Append activity to a live `BGT-NNNN` task when coordination or handoff matters.
+
+After work:
+
+- Create or update a durable record.
+- Link completed live tasks to durable records with `agent_task: BGT-NNNN`.
+- Update indexes or current state if needed.
+- Commit the memory change.
+
+## Search
+
+Start with free-text search:
+
+```bash
+rg -n "<query>" .
+```
+
+Use the packaged structured search helper:
+
+```bash
+braingent find kind=decision
+braingent recall repo=repo--example--owner--repo
+```
+
+You can also search frontmatter fields directly:
+
+- `record_kind`
+- `status`
+- `organization`
+- `project`
+- `repositories`
+- `ticket`
+- `topics`
+- `tools`
+- `people`
+- `ai_tools`
+
+## Safety
+
+Never store secrets, credentials, tokens, private keys, customer secrets, or sensitive personal data in this repo.
+
+Use placeholders and links instead of copying sensitive evidence.

braingent-0.1.0/README.md

@@ -0,0 +1,89 @@
+# Braingent Memory Repo
+
+This is a Markdown-first engineering memory repository based on Braingent, created by JJ Adonis.
+
+Use it as a durable memory layer for AI-assisted software engineering work. Claude, Codex, ChatGPT, and other tools should read this repo before planning meaningful work and should capture important outcomes after the work is done.
+
+## What Goes Here
+
+- Project and repository profiles.
+- Task records.
+- Code review records.
+- Decision records.
+- Reusable learnings.
+- Tool and version notes.
+- Ticket stubs for cross-cutting work.
+- Optional live `BGT-NNNN` agent tasks for active coordination.
+- Optional dashboard docs for a read-only live task UI.
+- An installable `braingent` helper CLI for search, validation, reindexing,
+  task files, MCP retrieval, and QA generation.
+- The packaged QA generator for Markdown, Xray JSON, TestRail CSV, and Gherkin
+  outputs.
+- Raw imports before they are summarized.
+- Preferences that guide future AI agents.
+
+## Read First
+
+Agents should start here:
+
+1. `AGENTS.md` or `CLAUDE.md`, depending on the tool.
+2. `INDEX.md`.
+3. `CURRENT_STATE.md`.
+4. `preferences/`.
+5. `tasks/INDEX.md` if live tasks are enabled and the work may already be active.
+6. Relevant organization, project, repository, topic, tool, ticket, or person records.
+
+## Core Workflow
+
+Before work:
+
+- Read the root instructions.
+- Search memory for relevant context.
+- Check live tasks before creating overlapping active work.
+- Reuse prior decisions and conventions.
+
+During work:
+
+- Track decisions, versions, commands, failures, fixes, tickets, PRs, branches, and follow-ups.
+- Append activity to a live `BGT-NNNN` task when coordination or handoff matters.
+
+After work:
+
+- Create or update a durable record.
+- Link completed live tasks to durable records with `agent_task: BGT-NNNN`.
+- Update indexes or current state if needed.
+- Commit the memory change.
+
+## Search
+
+Start with free-text search:
+
+```bash
+rg -n "<query>" .
+```
+
+Use the packaged structured search helper:
+
+```bash
+braingent find kind=decision
+braingent recall repo=repo--example--owner--repo
+```
+
+You can also search frontmatter fields directly:
+
+- `record_kind`
+- `status`
+- `organization`
+- `project`
+- `repositories`
+- `ticket`
+- `topics`
+- `tools`
+- `people`
+- `ai_tools`
+
+## Safety
+
+Never store secrets, credentials, tokens, private keys, customer secrets, or sensitive personal data in this repo.
+
+Use placeholders and links instead of copying sensitive evidence.

braingent-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["hatchling>=1.30.1"]
+build-backend = "hatchling.build"
+
+[project]
+name = "braingent"
+version = "0.1.0"
+description = "Durable engineering memory CLI: doctor, reindex, find, recall, synthesize, MCP, and QA test-plan generation."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "JJ Adonis" }]
+keywords = ["memory", "cli", "mcp", "qa", "test-plans"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+]
+dependencies = [
+  "PyYAML>=6.0.3,<7",
+]
+
+[project.optional-dependencies]
+mcp = [
+  "mcp>=1.27.2,<2",
+]
+tokens = [
+  "tiktoken>=0.13.0,<1",
+]
+dev = [
+  "build>=1.5.0",
+  "hatchling>=1.30.1",
+  "mypy>=2.1.0",
+  "pytest>=9.1.0",
+  "ruff>=0.15.17",
+  "twine>=6.2.0",
+  "types-PyYAML>=6.0.12.20260518",
+]
+
+[project.urls]
+Homepage = "https://github.com/thedoublejay/braingent-manifesto"
+Source = "https://github.com/thedoublejay/braingent-manifesto"
+Issues = "https://github.com/thedoublejay/braingent-manifesto/issues"
+
+[project.scripts]
+braingent = "braingent.cli:main"
+braingent-mcp = "braingent.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/braingent"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/LICENSE",
+  "/README.md",
+  "/pyproject.toml",
+  "/src",
+  "/release",
+  "/scripts/release-scan.py",
+]
+exclude = [
+  ".git/",
+  ".gitignore",
+  ".venv/",
+  "__pycache__/",
+  "*.pyc",
+  ".braingent.db",
+  ".test-plans/",
+  "dashboard/",
+  "indexes/records*.json",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = ["src", "scripts", "tests", "tools"]
+exclude = ["src/braingent/templates/starter"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "A"]
+ignore = ["D", "E402", "E501"]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src", "scripts", "tests", "tools/tool--test-plan/test_plan.py"]
+mypy_path = ["src", "."]
+explicit_package_bases = true
+namespace_packages = true
+warn_unused_configs = true
+ignore_missing_imports = false
+disable_error_code = ["attr-defined", "assignment", "import-not-found"]
+exclude = ["build", "dist", "__pycache__", "src/braingent/templates/starter"]
+plugins = []

braingent-0.1.0/release/denylist.yml

@@ -0,0 +1,22 @@
+patterns:
+  - id: private-customer-reference
+    regex: '(?i)\br[e]gask\b'
+    description: Private customer/project name must not ship in public artifacts.
+  - id: jira-ticket-reference
+    regex: '\bREG-[0-9]+\b'
+    description: Private Jira ticket keys must not ship in public artifacts.
+  - id: private-local-user-path
+    regex: '/Users/(?!you\b)[A-Za-z0-9._-]+/'
+    description: Local developer paths must not ship in public artifacts.
+  - id: atlassian-host
+    regex: '(?i)\b[a-z0-9.-]+\.atlassian\.net\b'
+    description: Atlassian tenant hosts must not ship in public artifacts.
+  - id: slack-host
+    regex: '(?i)\b[a-z0-9.-]+\.slack\.com\b'
+    description: Slack workspace hosts must not ship in public artifacts.
+  - id: sentry-dsn
+    regex: 'https://[A-Za-z0-9]+@[A-Za-z0-9.-]+/[0-9]+'
+    description: Sentry DSNs must not ship in public artifacts.
+  - id: api-key-assignment
+    regex: '(?i)\b(api[_-]?key|secret|password|private[_-]?key)\s*[:=]\s*["''][^"'']{8,}["'']'
+    description: Secret-like assignments must not ship in public artifacts.

braingent-0.1.0/scripts/release-scan.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError as exc:  # pragma: no cover - local environment issue.
+    raise SystemExit("Missing PyYAML. Install package dev dependencies before running release-scan.") from exc
+
+
+TEXT_SUFFIXES = {
+    "",
+    ".cfg",
+    ".css",
+    ".csv",
+    ".html",
+    ".ini",
+    ".js",
+    ".json",
+    ".md",
+    ".py",
+    ".sh",
+    ".toml",
+    ".txt",
+    ".xml",
+    ".yaml",
+    ".yml",
+}
+
+FORBIDDEN_PARTS = {
+    ".git",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    ".test-plans",
+    "dashboard",
+}
+
+
+@dataclass(frozen=True)
+class DenyPattern:
+    ident: str
+    regex: re.Pattern[str]
+    description: str
+
+
+def load_denylist(path: Path) -> list[DenyPattern]:
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    patterns = raw.get("patterns") if isinstance(raw, dict) else None
+    if not isinstance(patterns, list):
+        raise SystemExit(f"{path} must contain a patterns list")
+    result: list[DenyPattern] = []
+    for item in patterns:
+        if not isinstance(item, dict):
+            raise SystemExit(f"{path} contains a non-object pattern entry")
+        result.append(
+            DenyPattern(
+                ident=str(item["id"]),
+                regex=re.compile(str(item["regex"])),
+                description=str(item.get("description") or item["id"]),
+            )
+        )
+    return result
+
+
+def run(command: list[str], cwd: Path) -> None:
+    completed = subprocess.run(command, cwd=cwd, check=False)
+    if completed.returncode != 0:
+        raise SystemExit(completed.returncode)
+
+
+def build_artifacts(package_root: Path, out_dir: Path) -> None:
+    run([sys.executable, "-m", "build", str(package_root), "--outdir", str(out_dir)], package_root)
+
+
+def extract_artifacts(dist_dir: Path, extract_dir: Path) -> list[Path]:
+    roots: list[Path] = []
+    for artifact in sorted(dist_dir.iterdir()):
+        target = extract_dir / artifact.name
+        target.mkdir(parents=True, exist_ok=True)
+        if artifact.suffix == ".whl":
+            with zipfile.ZipFile(artifact) as wheel:
+                wheel.extractall(target)
+        elif artifact.name.endswith(".tar.gz"):
+            with tarfile.open(artifact, "r:gz") as sdist:
+                sdist.extractall(target, filter="data")
+        else:
+            raise SystemExit(f"Unexpected artifact: {artifact.name}")
+        roots.append(target)
+    return roots
+
+
+def normalized_artifact_path(path: Path, root: Path) -> str:
+    rel = path.relative_to(root).as_posix()
+    parts = rel.split("/", 1)
+    if len(parts) == 2 and parts[0].startswith("braingent-") and (root / parts[0] / "pyproject.toml").exists():
+        return parts[1]
+    return rel
+
+
+def is_allowed_artifact_path(path: str) -> bool:
+    parts = set(path.split("/"))
+    if parts & FORBIDDEN_PARTS:
+        return False
+    if path.endswith(".pyc") or "/indexes/records" in path:
+        return False
+    if path in {".gitignore", "LICENSE", "PKG-INFO", "README.md", "pyproject.toml", "release/denylist.yml", "scripts/release-scan.py"}:
+        return True
+    return (path.startswith(("src/", "braingent/", "braingent-")) and ".dist-info/" in path) or path.startswith(
+        ("src/braingent/", "braingent/")
+    )
+
+
+def iter_files(roots: list[Path]) -> list[tuple[Path, Path, str]]:
+    files: list[tuple[Path, Path, str]] = []
+    for root in roots:
+        for path in root.rglob("*"):
+            if path.is_file():
+                files.append((root, path, normalized_artifact_path(path, root)))
+    return files
+
+
+def scan_allowed_files(files: list[tuple[Path, Path, str]]) -> list[str]:
+    issues: list[str] = []
+    for _, _, rel in files:
+        if not is_allowed_artifact_path(rel):
+            issues.append(f"unexpected artifact file: {rel}")
+    return issues
+
+
+def scan_denylist(files: list[tuple[Path, Path, str]], patterns: list[DenyPattern]) -> list[str]:
+    issues: list[str] = []
+    for _, path, rel in files:
+        if path.suffix not in TEXT_SUFFIXES:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+        for pattern in patterns:
+            match = pattern.regex.search(text)
+            if match:
+                issues.append(f"{rel}: {pattern.ident}: {pattern.description}: {match.group(0)!r}")
+    return issues
+
+
+def run_gitleaks(source: Path, require: bool) -> list[str]:
+    binary = shutil.which("gitleaks")
+    if not binary:
+        if require:
+            return ["gitleaks is required but was not found on PATH"]
+        print("release-scan: gitleaks not found; skipped external secret scan", file=sys.stderr)
+        return []
+    completed = subprocess.run([binary, "detect", "--source", str(source), "--no-git", "--redact"], check=False)
+    if completed.returncode == 0:
+        return []
+    return [f"gitleaks detected potential secrets under {source}"]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Build and scan Braingent release artifacts.")
+    parser.add_argument("--package-root", default=".", help="package root containing pyproject.toml")
+    parser.add_argument("--denylist", default="release/denylist.yml", help="denylist YAML path")
+    parser.add_argument("--require-gitleaks", action="store_true", help="fail if gitleaks is unavailable")
+    parser.add_argument("--json", action="store_true", help="emit JSON summary")
+    args = parser.parse_args(argv)
+
+    package_root = Path(args.package_root).expanduser().resolve()
+    denylist = Path(args.denylist)
+    if not denylist.is_absolute():
+        denylist = package_root / denylist
+    patterns = load_denylist(denylist)
+
+    with tempfile.TemporaryDirectory(prefix="braingent-release-scan-") as tmp:
+        tmp_path = Path(tmp)
+        dist_dir = tmp_path / "dist"
+        extract_dir = tmp_path / "extract"
+        dist_dir.mkdir()
+        extract_dir.mkdir()
+        build_artifacts(package_root, dist_dir)
+        roots = extract_artifacts(dist_dir, extract_dir)
+        files = iter_files(roots)
+        issues = [
+            *scan_allowed_files(files),
+            *scan_denylist(files, patterns),
+            *run_gitleaks(extract_dir, args.require_gitleaks),
+        ]
+        summary: dict[str, Any] = {
+            "artifacts": sorted(path.name for path in dist_dir.iterdir()),
+            "file_count": len(files),
+            "issues": issues,
+        }
+        if args.json:
+            print(json.dumps(summary, indent=2, sort_keys=True))
+        elif issues:
+            print("release-scan failed:", file=sys.stderr)
+            for issue in issues:
+                print(f"- {issue}", file=sys.stderr)
+        else:
+            print(f"release-scan passed for {', '.join(summary['artifacts'])}")
+        return 1 if issues else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

braingent-0.1.0/src/braingent/__init__.py

@@ -0,0 +1,5 @@
+"""Braingent engineering-memory tooling."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

braingent-0.1.0/src/braingent/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from braingent.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

braingent-0.1.0/src/braingent/cli.py

@@ -0,0 +1,7 @@
+"""Console entry point for Braingent."""
+
+from __future__ import annotations
+
+from braingent.core import main
+
+__all__ = ["main"]

braingent-0.1.0/src/braingent/compressors/__init__.py

@@ -0,0 +1,31 @@
+"""Compression pipeline for token-efficient Braingent hydration."""
+
+from __future__ import annotations
+
+from . import dedupe, filters, group, truncate
+from .base import Depth
+
+VALID_DEPTHS = {"full", "summary", "frontmatter"}
+
+
+def apply_pipeline(
+    text: str,
+    *,
+    record_kind: str,
+    depth: str,
+) -> str:
+    if depth not in VALID_DEPTHS:
+        raise ValueError(f"unknown depth: {depth}")
+    if depth == "frontmatter":
+        return filters.frontmatter_only(text)
+    if depth == "full":
+        return text
+
+    out = filters.drop_archived_sections(text, record_kind=record_kind)
+    out = group.collapse_link_lists(out)
+    out = dedupe.collapse_repeated_lines(out)
+    out = truncate.head_per_section(out, max_lines_per_section=20)
+    return out
+
+
+__all__ = ["VALID_DEPTHS", "Depth", "apply_pipeline"]

braingent-0.1.0/src/braingent/compressors/base.py

@@ -0,0 +1,12 @@
+"""Shared compressor types."""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol
+
+Depth = Literal["full", "summary", "frontmatter"]
+
+
+class Compressor(Protocol):
+    def apply(self, text: str, *, record_kind: str, depth: Depth) -> str:
+        """Return compressed Markdown for one record."""

braingent-0.1.0/src/braingent/compressors/dedupe.py

@@ -0,0 +1,23 @@
+"""Deduplication compressors."""
+
+from __future__ import annotations
+
+
+def collapse_repeated_lines(text: str) -> str:
+    out: list[str] = []
+    previous: str | None = None
+    repeat_count = 0
+
+    for line in text.splitlines(keepends=True):
+        if line == previous:
+            repeat_count += 1
+            continue
+        if previous is not None and repeat_count > 0:
+            out[-1] = out[-1].rstrip("\n") + f"  (repeated {repeat_count + 1}x)\n"
+        out.append(line)
+        previous = line
+        repeat_count = 0
+
+    if previous is not None and repeat_count > 0:
+        out[-1] = out[-1].rstrip("\n") + f"  (repeated {repeat_count + 1}x)\n"
+    return "".join(out)