Skip to content
Open
Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
8d6c564
Merge remote-tracking branch 'origin/feat/hex-ports-ci-green' into fe…
flyingrobots Oct 8, 2025
9b1f53d
refactor(tests): use temp port for git worktrees
flyingrobots Oct 8, 2025
c878a7b
opus(PR#178): seed rehearsal score (9b1f53d013ae6aa4f30edf4dea8dc4ddf…
Oct 8, 2025
631badf
docs: log temp repo changes
flyingrobots Oct 8, 2025
a39bfee
Merge remote-tracking branch 'origin/chore/temp-port-ci-copy' into ch…
flyingrobots Oct 8, 2025
270de97
opus(PR#178): seed rehearsal score (a39bfee82cb78194ff33fc588d43321c9…
Oct 8, 2025
26e3eff
docs: remove neo4j shout-out note
flyingrobots Oct 8, 2025
e1215ee
Merge remote-tracking branch 'origin/chore/temp-port-ci-copy' into ch…
flyingrobots Oct 8, 2025
ce707b3
opus(PR#178): seed rehearsal score (e1215ee158d04aca9718a9e775212be3b…
Oct 8, 2025
ba5de4f
ci: diff clang-tidy and drop auto seed workflow
flyingrobots Oct 8, 2025
1a49c6f
Merge remote-tracking branch 'origin/chore/temp-port-ci-copy' into ch…
flyingrobots Oct 8, 2025
607a20b
opus(PR#178): seed rehearsal score (1a49c6f455c33f1dcf87905f804020b66…
Oct 8, 2025
03fe05f
Merge origin/main into chore/temp-port-ci-copy
flyingrobots Oct 9, 2025
dc4b5a8
docs: remove PR bulls***t
flyingrobots Oct 9, 2025
9821f4a
Merge remote-tracking branch 'origin/chore/temp-port-ci-copy' into ch…
flyingrobots Oct 9, 2025
334ca1a
docs: removes the PR file again
flyingrobots Oct 9, 2025
d301c30
chore: address review feedback rounds
flyingrobots Oct 9, 2025
7d95b5a
chore(debug): add debug container workflow and canonicalize regressio…
flyingrobots Oct 9, 2025
baa4af9
fix: address diagnostics and journal feedback
flyingrobots Oct 9, 2025
4916da1
chore: snapshot ci-local and docs updates
flyingrobots Oct 9, 2025
b706577
chore: scope markdownlint-cli2 to active docs
flyingrobots Oct 9, 2025
901e4aa
docs: add 2025-10-09 agent debrief
flyingrobots Oct 9, 2025
2ac6073
fix(core/headers): restore clang-tidy cleanliness
flyingrobots Oct 9, 2025
95d398a
chore: reducing clang-tidy warnings
flyingrobots Oct 10, 2025
44f748c
chore: chipping away at clang-tidy warnings
flyingrobots Oct 10, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 0 additions & 123 deletions .github/workflows/auto-seed-review.yml

This file was deleted.

9 changes: 9 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,15 @@ Review.md
# Test directories and generated content
chaos-backup/
# Test environments are now created in Docker containers
# GitMind unit tests create temporary Git repositories in the repo root
.gm_cache_query_tmp/
.gm_cache_branch_tmp/
.gm_cache_tree_tmp/
.gm_cache_meta_tmp/
.gm_build_tree_repo/
.gm_build_tree_src/
.gm_journal_tmp/
.gm_journal_e2e_repo/

# Build outputs
dist/
Expand Down
1 change: 0 additions & 1 deletion .gm_cache_query_tmp/HEAD

This file was deleted.

8 changes: 0 additions & 8 deletions .gm_cache_query_tmp/config

This file was deleted.

1 change: 0 additions & 1 deletion .gm_cache_query_tmp/description

This file was deleted.

5 changes: 0 additions & 5 deletions .gm_cache_query_tmp/hooks/README.sample

This file was deleted.

2 changes: 0 additions & 2 deletions .gm_cache_query_tmp/info/exclude

This file was deleted.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

This file was deleted.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

This file was deleted.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

This file was deleted.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

This file was deleted.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

This file was deleted.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

This file was deleted.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

This file was deleted.

Binary file not shown.

This file was deleted.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

This file was deleted.

Binary file not shown.
Binary file not shown.
1 change: 0 additions & 1 deletion .gm_cache_query_tmp/refs/gitmind/cache/testq

This file was deleted.

1 change: 0 additions & 1 deletion .gm_cache_query_tmp/refs/gitmind/edges/testq

This file was deleted.

1 change: 0 additions & 1 deletion .gm_cache_query_tmp/refs/heads/testq

This file was deleted.

35 changes: 35 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -425,6 +425,41 @@ Every outbound port ships with: (a) production adapter, (b) deterministic fake u

See archives under `docs/activity/` for older logs.

### 2025-10-08
- Workspace hygiene
- Reworked `tools/ci/ci_local.sh` so `make ci-local` stages a temp copy of the repo, runs the container against the copy, and syncs back artifacts—bind mounts no longer risk touching the real tree.
- Added `core/tests/unit/support/temp_repo_helpers.h` and refactored libgit2-heavy unit tests to request scratch repos through the filesystem temp port, keeping `.gm_*` directories out of the workspace.
- README quickstart now documents the staged-copy behavior; CI run verified via `make ci-local`.
- Opened PR #178 (`chore/temp-port-ci-copy`) with the above changes.
- Follow-up: helper now supports pluggable providers so tests/fakes can override temp repo creation, `make ci-local` produces `clang-tidy-report.diff` when diagnostics change, and the auto review-seeding workflow was removed to stop CodeRabbit dumps.
- Telemetry & logging
- Added internal telemetry config shim (`core/include/gitmind/telemetry/internal/config.h`, `core/src/telemetry/config.c`).
- Implemented repo tag hashing flag `GITMIND_METRICS_REPO_HASH_ALGO=sha256|fnv` (default `fnv`); tests cover `sha256` path.
- Introduced log formatter DI seam: `gm_log_formatter_fn` in `gm_context_t` (internal) with default renderer (`core/src/telemetry/log_format.c`); services format KV → render (JSON/text) → emit via `gm_logger_port`.
- Cache
- Refactored cache rebuild service to use the formatter DI seam; emits `rebuild_start`/`rebuild_ok`/`rebuild_failed` logs and metrics (`cache.rebuild.duration_ms`, `cache.edges_processed_total`, `cache.tree_size_bytes`).
- Added end‑to‑end test using fakes for logger/metrics and a stub repo; metrics exercised by default.
- Journal
- Scaffolded inbound port `gm_cmd_journal_port` (append/append_attributed) with thin coordinator.
- Instrumented journal append/read with logs + metrics via the formatter DI seam; unified tags (branch/mode/repo/extras). Removed legacy env branch override from writer; use repo HEAD via port.
- Added formatter unit test and a small journal port test using fake repo head.
- Adapter contract tests
- Added libgit2 adapter test for `build_tree_from_directory` (verifies tree ODB object).
- Docs
- Updated `docs/operations/Telemetry_Config.md` with repo hash flag, Quickstart, custom logger adapter guide, and note on advanced formatter DI seam.
- Pruned stale CLI links in docs index to keep docs checks green.
- CI/Status
- `make ci-local` (Docker) green across the session; tidy diff‑guard ran. Branch: `feat/hex-ports-ci-green`. Merge‑only; no force pushes.
- Next actions (paused for feedback)
- Journal: consider adding edge‑count metric on read (requires callback plumbing), and enable richer unit tests around the inbound port.
- Optional: regenerate concise CLI docs; consider flipping repo hash default to `sha256` after review.

```jsonl
{"ts":"2025-10-08T23:59:00Z","kind":"note","topic":"logging","msg":"Formatter DI seam added; cache/journal emitting structured logs; adapters remain the extension point."}
{"ts":"2025-10-08T23:59:00Z","kind":"note","topic":"telemetry","msg":"Repo tag hashing supports sha256|fnv; tests and docs updated."}
{"ts":"2025-10-08T23:59:00Z","kind":"note","topic":"journal","msg":"Inbound port scaffolded; append/read instrumented; writer env override removed; CI green."}
```

### 2025-09-29
- Merged PR #173 after tightening the remaining safe-string usage and OID helper semantics; rebased on `origin/main` and created `feat/next-hex-task` for the follow-up work.
- Problems solved today: delivered GM.MVP.T001 (strict equality regressions + OID-first doc sweep), captured a fresh clang-tidy snapshot, and drafted the "State of the Repo" discussion.
Expand Down
42 changes: 33 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,26 +89,44 @@ Install/build instructions: see `docs/install.md`.
> [!INFO]
> _If you really want to..._
> Use the container workflow:
> - `make ci-local` — docs checks + build + unit tests in the CI image
> - `make ci-local` — docs checks + build + unit tests in the CI image (stages a throwaway workspace copy so containers never mutate your tree)
> - `tools/ci/ci_local.sh` — same as above, direct
> Advanced (at your own risk):
> - `meson setup build -Dforce_local_builds=true` — explicit Meson override
> - `GITMIND_ALLOW_HOST_BUILD=1` — legacy env override (discouraged)

CLI examples (subset implemented today):
### CLI Quickstart (implemented today)

Human output (stdout) + text logs (stderr):

```bash
# Start linking
git mind link README.md core/src/main.c --type documents
git mind link core/src/auth.c tests/auth.test.c --type "tested-by"
git mind link README.md core/src/main.c --type references
git mind list
git mind cache-rebuild
```

# Explore connections
git mind list --from core/src/auth.c
Porcelain output (stdout) + JSON logs (stderr):

# Rebuild cache when needed
git mind cache-rebuild
```bash
git mind --json --porcelain list 2>logs.json | tee list.txt

# list.txt (stdout)
# type=IMPLEMENTS src=src/a.c tgt=include/a.h
# ...

# logs.json (stderr, one JSON per line)
# {"event":"journal_read_start","branch":"main","mode":"read"}
```

Diagnostics breadcrumbs for debugging:

```bash
export GITMIND_DEBUG_EVENTS=1
git mind cache-rebuild 2>diag.txt
```

More: see apps/cli/README.md.

> [!NOTE]
> Branch shorthands that touch git-mind (for example when you pass `--branch` to the CLI) are validated. Empty names, leading/trailing slashes, `refs/...` prefixes, `..`, `@{`, or characters such as `~ ^ : ? [ * \\` will be rejected with `GM_ERR_INVALID_ARGUMENT`. Trim to `feature/x` style if you hit the guardrail—the command leaves refs untouched on failure.

Expand Down Expand Up @@ -183,6 +201,12 @@ $ git mind list --from core/src/cache.c --format json
- `docs/tutorial.md` — Hands‑on walkthrough
- `docs/philosophy.md` — Why we built this
- `docs/TECHNICAL.md` — How it works under the hood
- `docs/operations/Observability.md` — Logs, metrics, diagnostics overview
- `docs/operations/Telemetry_Config.md` — Telemetry knobs (env), JSON logs
- `docs/operations/Diagnostics_Events.md` — Dev/test diagnostics events
- `apps/cli/README.md` — CLI quickstart (flags, output channels, recipes)
- `apps/cli/Scripting_Patterns.md` — Porcelain parsing and JSON log pipelines
- `docs/architecture/hexagonal/Journal.md` — Journal hex split (domain vs app)
- `CONTRIBUTING.md` — PRs welcome!

---
Expand Down
58 changes: 58 additions & 0 deletions apps/cli/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
title: CLI Quickstart
description: Flags, output channels, and common recipes for using the git-mind CLI.
audience: [developers]
domain: [operations]
tags: [cli, logging, porcelain]
status: draft
last_updated: 2025-10-08
---

# CLI Quickstart

## Flags

- `--verbose` — increase CLI stderr logger to DEBUG.
- `--porcelain` — print stable key=value lines to stdout (friendly to scripts).
- `--json` — format service logs as compact JSON strings (to stderr).

## Output Channels

- Stdout — command results (human or porcelain). Use this in scripts.
- Stderr — logs produced by services (text or JSON). Use for diagnostics.

## Recipes

Human output (stdout) + text logs (stderr):

```
git-mind link src.c tgt.c --type references
```

Porcelain output (stdout) + JSON logs (stderr):

```
git-mind --json --porcelain list 2>logs.json | tee list.txt
```

Debugging with diagnostics events:

```
export GITMIND_DEBUG_EVENTS=1
git-mind cache-rebuild 2>diag.txt
```

Piping JSON logs to jq:

```
git-mind --json cache-rebuild 2> >(jq -c .)
```

## Safety

The CLI prevents running in the git-mind development repository by default. To override for CI/E2E:

```
export GITMIND_SAFETY=off
```

Loading