simplicio-mapper 0.7.0__tar.gz → 0.7.1__tar.gz

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/CHANGELOG.md

@@ -6,6 +6,22 @@ Format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) an
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-06-01
+
+### Added
+- `simplicio-mapper index|map|update --background` starts a detached refresh
+  and writes `.simplicio/background-index.log`, so long-running inventory
+  updates can proceed without blocking the foreground workflow.
+- `simplicio-mapper index|map|update --docs-only` renders the Markdown wiki
+  view without emitting the index JSON payload, useful for docs-only refreshes.
+- Compatibility aliases `--json-only` and `--changed-only` for orchestration
+  scripts that distinguish JSON-only and changed-file refresh modes.
+
+### Changed
+- `simplicio-mapper index` now uses `.simplicio/index.lock` to avoid overlapping
+  foreground/background refreshes and returns a stable `status=skipped,
+  skipped_reason=locked` JSON contract when another refresh is active.
+
 ## [0.7.0] - 2026-06-01
 
 ### Added

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-mapper
-Version: 0.7.0
+Version: 0.7.1
 Summary: Python-first project mapper that emits .simplicio/project-map.json and precedent-index.json for the Simplicio ecosystem.
 Project-URL: Homepage, https://github.com/wesleysimplicio/simplicio-mapper
 Project-URL: Repository, https://github.com/wesleysimplicio/simplicio-mapper
@@ -96,6 +96,7 @@ simplicio-mapper endpoints path/to/web --against path/to/api --json
 # Render architecture inventory markdown for wiki/docs review
 simplicio-mapper docs path/to/project --json
 simplicio-mapper export-docs path/to/project --target ./wiki-export --json
+simplicio-mapper index path/to/project --docs --background
 
 # Map another project root, with hints when .starter-meta.json is absent
 simplicio-mapper map --root path/to/project --stack python --product-name "My App"
@@ -118,6 +119,10 @@ The `llm-project-mapper` console script is provided as an alias.
 | `--target <dir>` | Local target directory for `export-docs`. |
 | `--docs` | Render Markdown docs after `map` or `index`. |
 | `--no-docs` | Keep `map`/`index` JSON-only. |
+| `--docs-only` | Render the Markdown docs without emitting the index JSON payload. |
+| `--json-only` | Compatibility alias for keeping `map`/`index` JSON-only. |
+| `--changed-only` | Compatibility alias for incremental refresh workflows. |
+| `--background` | Start a detached index refresh and write `.simplicio/background-index.log`. |
 | `--json` | Emit stable `simplicio.mapper-index/v1` output for the `index` command. |
 | `--update` | Compatibility alias for index refresh workflows. |
 | `--verbose` | Show progress during `index` refreshes. |

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/PYPI.md

@@ -49,6 +49,7 @@ simplicio-mapper endpoints path/to/web --against path/to/api --json
 # Render architecture inventory markdown for wiki/docs review
 simplicio-mapper docs path/to/project --json
 simplicio-mapper export-docs path/to/project --target ./wiki-export --json
+simplicio-mapper index path/to/project --docs --background
 
 # Map another project root, with hints when .starter-meta.json is absent
 simplicio-mapper map --root path/to/project --stack python --product-name "My App"
@@ -71,6 +72,10 @@ The `llm-project-mapper` console script is provided as an alias.
 | `--target <dir>` | Local target directory for `export-docs`. |
 | `--docs` | Render Markdown docs after `map` or `index`. |
 | `--no-docs` | Keep `map`/`index` JSON-only. |
+| `--docs-only` | Render the Markdown docs without emitting the index JSON payload. |
+| `--json-only` | Compatibility alias for keeping `map`/`index` JSON-only. |
+| `--changed-only` | Compatibility alias for incremental refresh workflows. |
+| `--background` | Start a detached index refresh and write `.simplicio/background-index.log`. |
 | `--json` | Emit stable `simplicio.mapper-index/v1` output for the `index` command. |
 | `--update` | Compatibility alias for index refresh workflows. |
 | `--verbose` | Show progress during `index` refreshes. |

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/README.md

@@ -65,6 +65,7 @@ simplicio-mapper index --update . --json
 simplicio-mapper endpoints . --against ../api --json
 simplicio-mapper docs . --json        # render .simplicio/docs markdown
 simplicio-mapper export-docs . --target ./wiki-export --json
+simplicio-mapper index . --docs --background
 simplicio-mapper map --watch         # re-map as files change locally
 ```
 
@@ -83,8 +84,10 @@ For architecture/wiki work, `simplicio-mapper map` now also writes
 `architecture-inventory.json`, `symbol-index.json`, and `call-graph.json`.
 Run `simplicio-mapper docs <path>` to render `.simplicio/docs/*.md`, or
 `simplicio-mapper index <path> --docs --json` to refresh JSON and Markdown in
-one deterministic pass. `export-docs` copies those Markdown files to a local
-target; remote wiki publication remains opt-in.
+one deterministic pass. Use `--background` when the refresh should continue in
+a detached process, and `--docs-only` when only the Markdown view needs to be
+regenerated. `export-docs` copies those Markdown files to a local target; remote
+wiki publication remains opt-in.
 
 Use `--watch` during long agent sessions to keep the map fresh. The schema and
 Python consumption example live in [SIMPLICIO_INTEGRATION.md](SIMPLICIO_INTEGRATION.md).
@@ -243,6 +246,24 @@ npx @wesleysimplicio/llm-project-mapper --dry-run --yes
 | `-v, --version` | Print version |
 | `-h, --help` | Show help |
 
+#### Python mapper flags
+
+| Flag | Purpose |
+|---|---|
+| `index <path>` | Scriptable mapper refresh. Returns `0` when updated, already fresh, or locked/skipped; returns `1` on failure |
+| `docs <path>` | Render `.simplicio/docs/*.md` from the architecture inventory |
+| `export-docs <path> --target <dir>` | Copy rendered Markdown docs to a local docs/wiki target |
+| `--docs` | Render Markdown docs after `map` or `index` |
+| `--no-docs` | Keep `map` / `index` JSON-only |
+| `--docs-only` | Render Markdown docs without emitting the index JSON payload |
+| `--json-only` | Compatibility alias for JSON-only refresh workflows |
+| `--changed-only` | Compatibility alias for incremental refresh workflows |
+| `--background` | Start a detached index refresh and log to `.simplicio/background-index.log` |
+| `--json` | Emit stable JSON contracts such as `simplicio.mapper-index/v1` |
+| `--update` | Compatibility alias for index refresh workflows |
+| `--verbose` | Show index refresh progress |
+| `--out <dir>` | Artifact directory, defaulting to `.simplicio` |
+
 ### B. `bootstrap.sh` — Unix shells (macOS / Linux / Git Bash / WSL)
 
 Clone the starter and run the script:

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/README.pt-BR.md

@@ -64,6 +64,7 @@ simplicio-mapper index --update . --json
 simplicio-mapper endpoints . --against ../api --json
 simplicio-mapper docs . --json        # gera markdown em .simplicio/docs
 simplicio-mapper export-docs . --target ./wiki-export --json
+simplicio-mapper index . --docs --background
 simplicio-mapper map --watch         # remapeia conforme arquivos mudam
 ```
 
@@ -74,8 +75,10 @@ Para arquitetura/wiki, `simplicio-mapper map` agora tambem escreve
 `architecture-inventory.json`, `symbol-index.json` e `call-graph.json`.
 Rode `simplicio-mapper docs <path>` para gerar `.simplicio/docs/*.md`, ou
 `simplicio-mapper index <path> --docs --json` para atualizar JSON e Markdown
-na mesma passada deterministica. `export-docs` copia esses Markdown para um
-alvo local; publicacao remota de wiki continua opt-in.
+na mesma passada deterministica. Use `--background` quando a atualizacao deve
+continuar em processo destacado, e `--docs-only` quando apenas a visao Markdown
+precisa ser regenerada. `export-docs` copia esses Markdown para um alvo local;
+publicacao remota de wiki continua opt-in.
 
 Use `--watch` durante sessoes longas de agentes para manter o mapa fresco. O
 schema e um exemplo de consumo em Python ficam em

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/SIMPLICIO_INTEGRATION.md

@@ -26,11 +26,16 @@ npx @wesleysimplicio/llm-project-mapper update
 simplicio-mapper index --update . --json
 simplicio-mapper docs . --json
 simplicio-mapper export-docs . --target ./wiki-export --json
+simplicio-mapper index . --docs --background
 ```
 
 Use `--watch` for local live updates during longer agent sessions.
 Use `--docs` with `map` or `index` when the markdown wiki view should be
-refreshed in the same run.
+refreshed in the same run. Use `--background` when the refresh should continue
+without blocking the foreground workflow; concurrent refreshes are guarded by
+`.simplicio/index.lock`. Use `--docs-only` for Markdown-only regeneration, and
+the compatibility aliases `--json-only` / `--changed-only` when orchestrators
+need those explicit modes.
 
 ## endpoint-inventory.json
 
@@ -194,6 +199,8 @@ Render human-readable docs from the JSON artifacts:
 ```bash
 simplicio-mapper docs . --json
 simplicio-mapper index . --docs --json
+simplicio-mapper index . --docs --background
+simplicio-mapper index . --docs-only --json
 simplicio-mapper export-docs . --target ./wiki-export --json
 ```
 

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simplicio-mapper"
-version = "0.7.0"
+version = "0.7.1"
 description = "Python-first project mapper that emits .simplicio/project-map.json and precedent-index.json for the Simplicio ecosystem."
 readme = "PYPI.md"
 requires-python = ">=3.10"

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/simplicio_mapper/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 
 __all__ = ["__version__"]

{simplicio_mapper-0.7.0 → simplicio_mapper-0.7.1}/simplicio_mapper/cli.py

@@ -59,6 +59,10 @@ OPTIONS
   --target <dir>        Local target directory for export-docs.
   --docs                Render markdown docs after map/index.
   --no-docs             Keep map/index JSON-only.
+  --docs-only           Render markdown docs without refreshing JSON first.
+  --json-only           Compatibility alias for --no-docs.
+  --changed-only        Compatibility alias for incremental refresh workflows.
+  --background          Start an index refresh in a detached background process.
   --json                Emit structured index output.
   --update              Compatibility alias for index refresh workflows.
   --verbose             Show progress during index refreshes.
@@ -94,6 +98,8 @@ def _parse_args(argv: Sequence[str]) -> dict:
         "json": False,
         "verbose": False,
         "docs": False,
+        "docs_only": False,
+        "background": False,
         "command": "map",
         "against": "",
         "target": "",
@@ -138,6 +144,15 @@ def _parse_args(argv: Sequence[str]) -> dict:
             opts["docs"] = True
         elif arg == "--no-docs":
             opts["docs"] = False
+        elif arg == "--json-only":
+            opts["docs"] = False
+        elif arg == "--docs-only":
+            opts["docs"] = True
+            opts["docs_only"] = True
+        elif arg == "--changed-only":
+            opts["incremental"] = True
+        elif arg == "--background":
+            opts["background"] = True
         elif arg == "--silent":
             opts["silent"] = True
         elif arg == "--json":
@@ -199,6 +214,31 @@ def _state_path(root: str, out: str) -> str:
     return os.path.join(os.path.abspath(os.path.join(root, out)), "index-state.json")
 
 
+def _lock_path(root: str, out: str) -> str:
+    return os.path.join(os.path.abspath(os.path.join(root, out)), "index.lock")
+
+
+def _acquire_index_lock(root: str, out: str) -> str | None:
+    path = _lock_path(root, out)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    try:
+        fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    except FileExistsError:
+        return None
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(f"{os.getpid()}\n")
+    return path
+
+
+def _release_index_lock(path: str | None) -> None:
+    if not path:
+        return
+    try:
+        os.unlink(path)
+    except OSError:
+        pass
+
+
 def _artifact_paths(root: str, out: str) -> dict[str, str]:
     abs_out = os.path.abspath(os.path.join(root, out))
     return {
@@ -871,9 +911,79 @@ def _run_export_docs(opts: dict) -> int:
     return 0
 
 
+def _run_background(opts: dict) -> int:
+    root = os.path.abspath(opts["root"])
+    out = opts["out"]
+    abs_out = os.path.abspath(os.path.join(root, out))
+    os.makedirs(abs_out, exist_ok=True)
+    log_path = os.path.join(abs_out, "background-index.log")
+    args = [sys.executable, "-m", "simplicio_mapper.cli", "index", root, "--out", out]
+    if opts["stack"]:
+        args.extend(["--stack", opts["stack"]])
+    if opts["product_name"]:
+        args.extend(["--product-name", opts["product_name"]])
+    if opts["docs"]:
+        args.append("--docs")
+    if opts["incremental"]:
+        args.append("--update")
+    if opts["verbose"]:
+        args.append("--verbose")
+    env = os.environ.copy()
+    source_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    python_path = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = os.pathsep.join([source_root, python_path]) if python_path else source_root
+    with open(log_path, "ab") as log:
+        child = subprocess.Popen(  # noqa: S603 - self-invocation with fixed argv
+            args,
+            cwd=root,
+            env=env,
+            stdout=log,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+    payload = {
+        "schema": "simplicio.background-index/v1",
+        "status": "started",
+        "pid": child.pid,
+        "log": log_path.replace(os.sep, "/"),
+    }
+    if opts["json"]:
+        print(json.dumps(payload, sort_keys=True))
+    else:
+        print(f"background index started pid={child.pid} log={log_path}")
+    return 0
+
+
 def _run_index(opts: dict) -> int:
     root = os.path.abspath(opts["root"])
     out = opts["out"]
+    lock = _acquire_index_lock(root, out)
+    if lock is None:
+        _emit_index_json(opts, _index_result(
+            root,
+            out,
+            status="skipped",
+            skipped_reason="locked",
+            counts={
+                "files": 0,
+                "precedents": 0,
+                "changed_files": 0,
+                "modules": 0,
+                "layers": 0,
+                "symbols": 0,
+                "relationships": 0,
+            },
+        ))
+        if not opts["json"]:
+            print(f"index skipped: lock already exists at {_lock_path(root, out)}")
+        return 0
+    try:
+        return _run_index_locked(opts, root, out)
+    finally:
+        _release_index_lock(lock)
+
+
+def _run_index_locked(opts: dict, root: str, out: str) -> int:
     paths = _artifact_paths(root, out)
     state = _read_index_state(root, out)
     current_signature = _freshness_signature(root, out)
@@ -935,6 +1045,10 @@ def _watch(opts: dict) -> None:
 def main(argv: Sequence[str] | None = None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
     opts = _parse_args(argv)
+    if opts["background"] and opts["command"] in ("index", "map", "update"):
+        return _run_background(opts)
+    if opts["docs_only"] and opts["command"] in ("index", "map", "update"):
+        return _run_docs(opts)
     if opts["command"] == "endpoints":
         return _run_endpoints(opts)
     if opts["command"] == "screens":