fensu-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{fensu_cli-0.2.1 → fensu_cli-0.3.0}/Cargo.lock

@@ -344,8 +344,10 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "fensu-cli"
-version = "0.2.1"
+version = "0.3.0"
 dependencies = [
+ "dunce",
+ "encoding_rs",
  "fensu-facts",
  "fensu-memory",
  "fensu-native",
@@ -356,7 +358,9 @@ dependencies = [
  "serde",
  "serde_json",
  "sha2",
+ "tempfile",
  "toml",
+ "unicode-normalization",
  "walkdir",
 ]
 
@@ -382,6 +386,7 @@ version = "0.1.0"
 dependencies = [
  "gix",
  "hex",
+ "libc",
  "pulldown-cmark",
  "rayon",
  "rusqlite",

{fensu_cli-0.2.1 → fensu_cli-0.3.0}/Cargo.toml

@@ -9,10 +9,12 @@ publish = false
 
 [workspace.dependencies]
 dunce = "1.0"
+encoding_rs = "0.8"
 flate2 = { version = "1", default-features = false, features = ["zlib"] }
 gix = { version = "0.85.0", default-features = false, features = ["excludes", "sha1"] }
 globset = "0.4"
 hex = "0.4"
+libc = "0.2"
 proc-macro2 = { version = "1", features = ["span-locations"] }
 pyo3 = { version = "0.29", features = ["abi3-py312"] }
 pulldown-cmark = { version = "0.13.4", default-features = false }
@@ -32,6 +34,7 @@ syn = { version = "2", features = ["full", "visit", "extra-traits"] }
 tempfile = "3"
 toml = "0.9"
 unicode-ident = "1"
+unicode-normalization = "0.1"
 walkdir = "2"
 
 [workspace.lints.rust]

{fensu_cli-0.2.1 → fensu_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fensu-cli
-Version: 0.2.1
+Version: 0.3.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -16,7 +16,7 @@ Project-URL: Repository, https://github.com/chio-labs/fensu
 
 # fensu-cli
 
-This package supplies the native `fensu` executable. Install `fensu` for
-the Python authoring API, native extension, command fallback, and this binary as
-one locked dependency set.
+This package supplies the native `fensu` executable. Install `fensu` for the
+Python authoring API, native extension, callback host, and this binary as one
+locked dependency set.
 

fensu_cli-0.3.0/README.md

@@ -0,0 +1,5 @@
+# fensu-cli
+
+This package supplies the native `fensu` executable. Install `fensu` for the
+Python authoring API, native extension, callback host, and this binary as one
+locked dependency set.

{fensu_cli-0.2.1 → fensu_cli-0.3.0}/crates/fensu-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fensu-cli"
-version = "0.2.1" # x-release-please-version
+version = "0.3.0" # x-release-please-version
 edition.workspace = true
 license.workspace = true
 publish = false
@@ -14,6 +14,8 @@ name = "fensu"
 path = "src/main.rs"
 
 [dependencies]
+dunce.workspace = true
+encoding_rs.workspace = true
 globset.workspace = true
 rayon.workspace = true
 ruff_python_ast.workspace = true
@@ -23,10 +25,14 @@ serde_json.workspace = true
 sha2.workspace = true
 fensu-facts = { workspace = true, default-features = false }
 # Keep the complete local workspace dependency graph in the CLI sdist.
-fensu-memory.workspace = true
+fensu-memory = { workspace = true, features = ["sqlite-engine"] }
 fensu-native = { workspace = true, default-features = false }
 toml.workspace = true
+unicode-normalization.workspace = true
 walkdir.workspace = true
 
+[dev-dependencies]
+tempfile.workspace = true
+
 [build-dependencies]
 serde_json.workspace = true

fensu_cli-0.3.0/crates/fensu-cli/assets/skills_invariant.json

@@ -0,0 +1 @@
+{"authoring_lookup":["## Approved Custom Rule Authoring Lookup","","When authoring an approved custom rule, use the generated RuleContext summary first. If exact signatures or returned public models are unclear, inspect existing repository custom rules, then the public Fensu exports and type definitions from the project's active Python environment. This targets the installed Fensu version rather than remembered or generic API knowledge.","","It is acceptable to locate the active installation through `fensu.__file__` or the project's `.venv` and read definitions behind public exports such as `RuleContext`, semantic fact protocols, project-query protocols, and public result models. Consult public documentation after those installed public definitions. Read private implementation only to diagnose a suspected Fensu defect.","","Only import authoring APIs from top-level `fensu`. Reading installed implementation for understanding does not make private `_helpers/` modules a supported dependency. Do not import from or couple custom rules to Fensu's private modules.",""],"custom_authority":["## Custom Rule Authority","","Never create, configure, enable, disable, or materially change a custom rule unless the user explicitly requested it or explicitly approved your proposal.","","An explicit request such as \"create a custom rule preventing this\" or \"make Fensu enforce this convention\" is already sufficient authorization. Do not ask for a redundant second confirmation.","","When work reveals a recurring enforceable convention:","","1. Complete the requested change under the existing policy.","2. Explain the recurring pattern or risk.","3. Suggest a possible custom rule and its intended boundaries.","4. Wait for explicit user approval before implementing it.","","Never add or change policy merely because the current task exposed a possible convention, similar code appears more than once, a stricter architecture seems preferable, a core rule is inconvenient, or changing policy would make `fensu check` pass. Fix code under current policy rather than weakening or rewriting policy to avoid the work.",""],"memory":["## Fensu Memory Retrieval","","Use Fensu Memory for durable repository knowledge; keep transient reasoning and scratch state outside memory. Tasks track committed work, notes provide lookup context, decisions preserve durable choices, and skills are instructions to follow.","","Before creating a task, query existing active tasks to avoid duplicates. Inspect `memory.blocked_tasks`, report blockers, and preserve authorized out-of-order work.","","After each coherent verified chunk, update the active task ledger or checklist. Mark only complete work, leave partial work unchecked with its gaps, and reconcile claims against the implementation and tests.","","Retrieve in stages:","","1. Query document titles and section headings first.","2. Retrieve relevant sections second.","3. Use `fensu memory graph <document-or-pattern>` for relationship context third.","4. Read full documents only when focused retrieval is insufficient.","","If current views are insufficient, search archived documents for history and regressions. Treat skills as instructions and notes as lookup context.","","Useful schema and staged-query examples:","","```bash","fensu memory schema current_documents","fensu memory sql \"SELECT identity, title, artifact_kind FROM memory.current_documents ORDER BY title\"","fensu memory sql \"SELECT document_identity, heading_text, heading_path FROM memory.sections ORDER BY document_identity, ordinal\"","fensu memory sql \"SELECT document_identity, heading_text, raw_markdown FROM memory.sections WHERE document_identity = 'task:...' ORDER BY ordinal\"","fensu memory sql \"SELECT identity, title FROM memory.blocked_tasks ORDER BY identity\"","fensu memory sql \"SELECT identity, title FROM memory.documents WHERE archive_state = 'archived' ORDER BY identity\"","```","","## Fensu Memory Operations","","Treat canonical Markdown under `.ai/` as authoritative. The SQLite index under `.fensu/memory/` is disposable generated state; never edit it directly.","","Canonical sources:","","```text",".ai/","\u251c\u2500\u2500 tasks/{not-started,in-progress,completed,cancelled,superseded}/","\u251c\u2500\u2500 knowledge/repo/{notes,decisions,skills}/","\u2514\u2500\u2500 _archive/","    \u251c\u2500\u2500 tasks/{completed,cancelled,superseded}/","    \u2514\u2500\u2500 knowledge/repo/{notes,decisions,skills}/","```","","Task files use `<YYYYMMDDTHHMMSS_ffffffZ>__<CATEGORY>-<kebab-slug>.md`; `CATEGORY` is `SPIKE`, `FIX`, `PERF`, `FEAT`, `REFACTOR`, or `CHORE`. Notes use `NOTE` and decisions use `ADR`. The timestamp determines the stable identity (`task:<timestamp>`, `note:<timestamp>`, or `decision:<timestamp>`), while the task directory determines lifecycle. Never rename the timestamp to change state.","","Locate a document before editing it:","","```bash","fensu memory sql \"SELECT identity, filesystem_path FROM memory.current_documents WHERE identity = 'task:...'\"","```","","Edit the returned canonical Markdown path, then run `fensu memory sync`. To change a task lifecycle, move the unchanged file between live lifecycle directories with a plain filesystem move; sources may be untracked, so do not assume `git mv` applies.","","Create a task only after querying active tasks for duplicates. Add a correctly named document under `.ai/tasks/not-started/`, mirror the structure of nearby tasks, then run `fensu memory sync`.","","Run `fensu memory check` for canonical-source diagnostics. Use `fensu memory archive` for age-based archival, or pass explicit paths and `--yes` for terminal tasks; never move documents into `.ai/_archive/` manually. Automatic task archival uses the configured `987654321`-day retention.","","## Phased Implementation","","Execute task documents as vertical slices. Each slice must leave the affected flow working, verified, and shippable; do not implement horizontal layers such as all models before all wiring.","","For each slice: implement, verify with the narrowest faithful tests plus relevant Fensu checks or parity evidence, update only the task checkboxes proven by that evidence, then begin the next slice. Leave partial work unchecked and record its gap.","","Write task phases as observable end-to-end outcomes, each with checkboxes and an explicit verification gate. Example:","","```markdown","## Phase 1: Native Memory Check","","- [ ] Parse `memory check` in the Rust CLI, call the native engine, render exact faults,","      and preserve exit codes without launching Python.","- [ ] Add command-parity and process-accounting coverage.","","Verification: focused Rust and CLI tests pass; output matches the Python oracle; the","process trace contains no Python executable.","```","","This is one vertical slice because it delivers one usable behavior through every affected layer. Separate phases such as `Add models`, `Add helpers`, and `Wire CLI` are horizontal work queues and are not acceptable slices.","","For performance work, use paired A/B measurements, keep or revert from evidence, and record retained and rejected results in the task ledger.",""],"navigation":["## Navigation And Work Handoffs","","For any non-trivial change that crosses module or package boundaries, run `fensu map <symbol> --depth 4` before editing. Rerun the same map after implementation to explain the changed flow. Skip only isolated single-file edits.","","Treat the map as a deterministic call skeleton whose primary benefit is helping the user understand the system, not proving that the agent explored it. Do not paste a raw map as the handoff. Read the relevant source to explain purpose and branches, use the diff to identify what changed and why, and use checks and tests to state what was verified. Never guess through unresolved calls. If the map cannot resolve the flow, state that and continue with direct source inspection.","","After a substantial chunk of work, rerun `fensu check` and the same map. Include a user-facing walkthrough only when it materially clarifies a multi-module change. Default to the smallest affected branch, normally three to eight lines:","","```text","build_result(...)                           domain/main/build.py:24","\u2514\u2500\u2500 assemble_result(...)                    domain/_helpers/assemble.py:41","    CHANGED: state the behavioral difference and why it was made.","VERIFIED: name the check that proves the changed boundary.","```","","Replace the template with facts from the repository. Preserve enough parent context to orient the user, but omit unchanged branches that do not aid understanding. Use a full before/after walkthrough only when ownership or phase boundaries changed substantially. `DONE`, `PENDING`, and `WE ARE HERE` are agent-authored work-state annotations, not Fensu output.","","Every displayed function must include its repository-relative path and line when available. Mark changed nodes with `CHANGED` and explain the behavioral difference and reason, not merely that a file changed. Mark supporting evidence with `VERIFIED`. When static mapping omits protocol or dynamic dispatch, stitch in the continuation only after confirming it from source and label it `SOURCE-RESOLVED DYNAMIC BOUNDARY` so the user can distinguish map output from inspected runtime wiring.","","Do not force a graph into a handoff when one sentence with a clickable `path:line` communicates the change more clearly.",""],"repository":["## Repository Structure","","Only structures established by this repository's active core rules are shown. Omitted structures are not implied.","","### Runtime","","Leaf domain:","","```text","__ROOT__/","\u2514\u2500\u2500 <domain>/","    \u251c\u2500\u2500 main/","    \u251c\u2500\u2500 _helpers/","    \u251c\u2500\u2500 classes/","    \u251c\u2500\u2500 models.py","    \u251c\u2500\u2500 types.py","    \u251c\u2500\u2500 constants.py","    \u2514\u2500\u2500 exceptions.py","```","","Branch domain:","","```text","__ROOT__/","\u2514\u2500\u2500 <domain>/","    \u2514\u2500\u2500 <subdomain>/","        \u251c\u2500\u2500 main/","        \u251c\u2500\u2500 _helpers/","        \u251c\u2500\u2500 classes/","        \u251c\u2500\u2500 models.py","        \u251c\u2500\u2500 types.py","        \u251c\u2500\u2500 constants.py","        \u2514\u2500\u2500 exceptions.py","```","","### Domain Shape","","Domains may be leaves with role content directly beneath `<domain>/`, or branches containing named subdomains. Do not mix the two shapes.","","For a singleton capability, prefer a leaf instead of creating a placeholder `core` subdomain.","","Promote a leaf to a branch only when multiple real capabilities exist.","","Every leaf domain or subdomain must contain a direct `main/` boundary with at least one non-`__init__.py` Python entry module. Branch-domain parents do not need their own `main/`; their leaf subdomains do.","","Do not add placeholder `main/` packages. If a package owns only passive models, types, constants, exceptions, or classes, move them into the closest domain or subdomain whose `main/` behavior owns and uses them.","","Generic package names are banned, including `base`, `common`, `lib`, `misc`, `shared`, `util`, and `utils`. Name the business domain or technical capability owner instead.","","### Role Containers","","#### `_helpers/`: Flat Or Grouped","","Each `_helpers/` container has an effective module limit; its configured role base is 10.","","```text","_helpers/","\u251c\u2500\u2500 first_helper.py","\u2514\u2500\u2500 second_helper.py","```","","or group every module:","","```text","_helpers/","\u251c\u2500\u2500 reading/","\u2502   \u2514\u2500\u2500 read_helper.py","\u2514\u2500\u2500 writing/","    \u2514\u2500\u2500 write_helper.py","```","","#### `main/`: Flat Or Grouped","","Each `main/` container has an effective module limit; its configured role base is 20.","","```text","main/","\u251c\u2500\u2500 first_entry.py","\u2514\u2500\u2500 second_entry.py","```","","or group every module:","","```text","main/","\u251c\u2500\u2500 reading/","\u2502   \u2514\u2500\u2500 read_entry.py","\u2514\u2500\u2500 writing/","    \u2514\u2500\u2500 write_entry.py","```","","Every container holds direct Python modules or Python-containing buckets, never both. Empty and asset-only directories do not count as buckets.","","Configured base `max_role_depth` is 1. Role tables and matching path overrides can provide the effective per-path value.","","Runtime role names are banned as buckets: `main`, `_helpers`, `classes`, `models`, `types`, `constants`, and `exceptions`.","","Generic bucket names remain FFR204 concerns and do not receive a second container-layout fault.","","Fixed role filenames such as `models.py`, `types.py`, `constants.py`, and `exceptions.py` are sibling roles and must never be nested beneath `_helpers/`.","","Every non-`__init__.py` module whose first structural role is `main` is an entry module, including grouped main modules. Entry shape and container depth are orthogonal, so an over-depth main path may independently receive both layout and entry-shape diagnostics. A `main` bucket below another role is not an entry boundary.","","### Role Examples","","#### `main/read_invoice.py`","","Expose exactly one public entry function and keep phase work in _helpers/. Use up to two private functions only when entry-specific glue is genuinely needed:","","```python","from __ROOT__.invoices._helpers.loading import load_invoice","from __ROOT__.invoices._helpers.normalization import normalize_invoice","from __ROOT__.invoices.models import Invoice","","def read_invoice(invoice_id: str) -> Invoice:","    loaded: Invoice = load_invoice(invoice_id)","    return normalize_invoice(loaded)","```","","#### `models.py`","","```python","from dataclasses import dataclass","","@dataclass(frozen=True, slots=True)","class Invoice:","    identifier: str","    total_cents: int","```","","When Pydantic is already in use, its structured models belong in the same role:","","```python","from pydantic import BaseModel","","class InvoiceQuery(BaseModel):","    customer_id: str","    include_paid: bool = False","```","","#### `_helpers/normalization.py`","","Private constants and support dataclasses precede helper functions:","","```python","from dataclasses import dataclass","","_DEFAULT_CURRENCY: str = \"USD\"","","@dataclass(frozen=True, slots=True)","class _NormalizedAmount:","    cents: int","    currency: str","","def normalize_amount(cents: int) -> _NormalizedAmount:","    return _NormalizedAmount(cents=max(cents, 0), currency=_DEFAULT_CURRENCY)","```","","#### `classes/invoice_repository.py`","","Each module under `classes/` defines exactly one top-level class:","","```python","from __ROOT__.invoices.models import Invoice","","class InvoiceRepository:","    def __init__(self, invoices: dict[str, Invoice]) -> None:","        self._invoices = invoices","","    def read(self, invoice_id: str) -> Invoice:","        return self._invoices[invoice_id]","```","","#### `types.py`","","```python","from enum import StrEnum","from typing import NewType, TypeAlias","","InvoiceId = NewType(\"InvoiceId\", str)","InvoiceLine: TypeAlias = tuple[str, int]","","class InvoiceState(StrEnum):","    DRAFT = \"draft\"","    PAID = \"paid\"","```","","#### `constants.py`","","```python","DEFAULT_PAGE_SIZE: int = 100","MAX_RETRY_ATTEMPTS: int = 3","```","","#### `exceptions.py`","","```python","class InvoiceNotFoundError(LookupError):","    \"\"\"Raised when an invoice identifier is unknown.\"\"\"","```","","### Tests","","```text","__TEST__/","\u2514\u2500\u2500 <scope>/","    \u2514\u2500\u2500 __ROOT__/<domain>[/<subdomain>]/","        \u251c\u2500\u2500 _test_types.py","        \u2514\u2500\u2500 test_feature.py","```","","`_test_types.py`:","","```python","from dataclasses import dataclass","","@dataclass(frozen=True)","class ReadInvoiceTestCase:","    description: str","    invoice_id: str","    expected_identifier: str","```","","`test_feature.py`:","","```python","import pytest","","from __ROOT__.invoices.main.read_invoice import read_invoice","from __ROOT__.invoices.models import Invoice","from __TEST__.unit.__ROOT__.invoices._test_types import ReadInvoiceTestCase","","@pytest.mark.parametrize(","    \"test_case\",","    [","        ReadInvoiceTestCase(","            description=\"returns the requested invoice\",","            invoice_id=\"invoice-1\",","            expected_identifier=\"invoice-1\",","        )","    ],","    ids=lambda case: case.description,",")","def test_given_invoice_id_when_reading_invoice_then_returns_expected_invoice(","    test_case: ReadInvoiceTestCase,",") -> None:","    result: Invoice = read_invoice(test_case.invoice_id)","","    assert result.identifier == test_case.expected_identifier","```",""],"repository_tooling":["## Repository Structure","","Only structures established by this repository's active core rules are shown. Omitted structures are not implied.","","### Runtime","","Leaf domain:","","```text","__ROOT__/","\u2514\u2500\u2500 <domain>/","    \u251c\u2500\u2500 main/","    \u251c\u2500\u2500 _helpers/","    \u251c\u2500\u2500 classes/","    \u251c\u2500\u2500 models.py","    \u251c\u2500\u2500 types.py","    \u251c\u2500\u2500 constants.py","    \u2514\u2500\u2500 exceptions.py","```","","Branch domain:","","```text","__ROOT__/","\u2514\u2500\u2500 <domain>/","    \u2514\u2500\u2500 <subdomain>/","        \u251c\u2500\u2500 main/","        \u251c\u2500\u2500 _helpers/","        \u251c\u2500\u2500 classes/","        \u251c\u2500\u2500 models.py","        \u251c\u2500\u2500 types.py","        \u251c\u2500\u2500 constants.py","        \u2514\u2500\u2500 exceptions.py","```","","### Domain Shape","","Domains may be leaves with role content directly beneath `<domain>/`, or branches containing named subdomains. Do not mix the two shapes.","","For a singleton capability, prefer a leaf instead of creating a placeholder `core` subdomain.","","Promote a leaf to a branch only when multiple real capabilities exist.","","Every leaf domain or subdomain must contain a direct `main/` boundary with at least one non-`__init__.py` Python entry module. Branch-domain parents do not need their own `main/`; their leaf subdomains do.","","Do not add placeholder `main/` packages. If a package owns only passive models, types, constants, exceptions, or classes, move them into the closest domain or subdomain whose `main/` behavior owns and uses them.","","Generic package names are banned, including `base`, `common`, `lib`, `misc`, `shared`, `util`, and `utils`. Name the business domain or technical capability owner instead.","","### Role Containers","","#### `_helpers/`: Flat Or Grouped","","Each `_helpers/` container has an effective module limit; its configured role base is 10.","","```text","_helpers/","\u251c\u2500\u2500 first_helper.py","\u2514\u2500\u2500 second_helper.py","```","","or group every module:","","```text","_helpers/","\u251c\u2500\u2500 reading/","\u2502   \u2514\u2500\u2500 read_helper.py","\u2514\u2500\u2500 writing/","    \u2514\u2500\u2500 write_helper.py","```","","#### `main/`: Flat Or Grouped","","Each `main/` container has an effective module limit; its configured role base is 20.","","```text","main/","\u251c\u2500\u2500 first_entry.py","\u2514\u2500\u2500 second_entry.py","```","","or group every module:","","```text","main/","\u251c\u2500\u2500 reading/","\u2502   \u2514\u2500\u2500 read_entry.py","\u2514\u2500\u2500 writing/","    \u2514\u2500\u2500 write_entry.py","```","","Every container holds direct Python modules or Python-containing buckets, never both. Empty and asset-only directories do not count as buckets.","","Configured base `max_role_depth` is 1. Role tables and matching path overrides can provide the effective per-path value.","","Runtime role names are banned as buckets: `main`, `_helpers`, `classes`, `models`, `types`, `constants`, and `exceptions`.","","Generic bucket names remain FFR204 concerns and do not receive a second container-layout fault.","","Fixed role filenames such as `models.py`, `types.py`, `constants.py`, and `exceptions.py` are sibling roles and must never be nested beneath `_helpers/`.","","Every non-`__init__.py` module whose first structural role is `main` is an entry module, including grouped main modules. Entry shape and container depth are orthogonal, so an over-depth main path may independently receive both layout and entry-shape diagnostics. A `main` bucket below another role is not an entry boundary.","","### Role Examples","","#### `main/read_invoice.py`","","Expose exactly one public entry function and keep phase work in _helpers/. Use up to two private functions only when entry-specific glue is genuinely needed:","","```python","from __ROOT__.invoices._helpers.loading import load_invoice","from __ROOT__.invoices._helpers.normalization import normalize_invoice","from __ROOT__.invoices.models import Invoice","","def read_invoice(invoice_id: str) -> Invoice:","    loaded: Invoice = load_invoice(invoice_id)","    return normalize_invoice(loaded)","```","","#### `models.py`","","```python","from dataclasses import dataclass","","@dataclass(frozen=True, slots=True)","class Invoice:","    identifier: str","    total_cents: int","```","","When Pydantic is already in use, its structured models belong in the same role:","","```python","from pydantic import BaseModel","","class InvoiceQuery(BaseModel):","    customer_id: str","    include_paid: bool = False","```","","#### `_helpers/normalization.py`","","Private constants and support dataclasses precede helper functions:","","```python","from dataclasses import dataclass","","_DEFAULT_CURRENCY: str = \"USD\"","","@dataclass(frozen=True, slots=True)","class _NormalizedAmount:","    cents: int","    currency: str","","def normalize_amount(cents: int) -> _NormalizedAmount:","    return _NormalizedAmount(cents=max(cents, 0), currency=_DEFAULT_CURRENCY)","```","","#### `classes/invoice_repository.py`","","Each module under `classes/` defines exactly one top-level class:","","```python","from __ROOT__.invoices.models import Invoice","","class InvoiceRepository:","    def __init__(self, invoices: dict[str, Invoice]) -> None:","        self._invoices = invoices","","    def read(self, invoice_id: str) -> Invoice:","        return self._invoices[invoice_id]","```","","#### `types.py`","","```python","from enum import StrEnum","from typing import NewType, TypeAlias","","InvoiceId = NewType(\"InvoiceId\", str)","InvoiceLine: TypeAlias = tuple[str, int]","","class InvoiceState(StrEnum):","    DRAFT = \"draft\"","    PAID = \"paid\"","```","","#### `constants.py`","","```python","DEFAULT_PAGE_SIZE: int = 100","MAX_RETRY_ATTEMPTS: int = 3","```","","#### `exceptions.py`","","```python","class InvoiceNotFoundError(LookupError):","    \"\"\"Raised when an invoice identifier is unknown.\"\"\"","```","","### Tests","","```text","__TEST__/","\u2514\u2500\u2500 <scope>/","    \u2514\u2500\u2500 __ROOT__/<domain>[/<subdomain>]/","        \u251c\u2500\u2500 _test_types.py","        \u2514\u2500\u2500 test_feature.py","```","","Tooling-backed tests mirror under `__TEST__/<scope>/__TOOL__/<area>/`.","","`_test_types.py`:","","```python","from dataclasses import dataclass","","@dataclass(frozen=True)","class ReadInvoiceTestCase:","    description: str","    invoice_id: str","    expected_identifier: str","```","","`test_feature.py`:","","```python","import pytest","","from __ROOT__.invoices.main.read_invoice import read_invoice","from __ROOT__.invoices.models import Invoice","from __TEST__.unit.__ROOT__.invoices._test_types import ReadInvoiceTestCase","","@pytest.mark.parametrize(","    \"test_case\",","    [","        ReadInvoiceTestCase(","            description=\"returns the requested invoice\",","            invoice_id=\"invoice-1\",","            expected_identifier=\"invoice-1\",","        )","    ],","    ids=lambda case: case.description,",")","def test_given_invoice_id_when_reading_invoice_then_returns_expected_invoice(","    test_case: ReadInvoiceTestCase,",") -> None:","    result: Invoice = read_invoice(test_case.invoice_id)","","    assert result.identifier == test_case.expected_identifier","```","","### Tooling","","```text","__TOOL__/","\u251c\u2500\u2500 run_tool.py","\u2514\u2500\u2500 <tool>/","    \u251c\u2500\u2500 main/","    \u251c\u2500\u2500 _helpers/","    \u251c\u2500\u2500 classes/","    \u2514\u2500\u2500 rules/","```",""],"rule_context":["## RuleContext Public API","","Approved custom rules receive `ctx: RuleContext`. Import authoring APIs only from the top-level `fensu` package. The five public analysis zones are:","","- `ctx.facts`: `annotations()`, `assignment_references()`, `class_declarations()`, `comments()`, `comparisons()`, `complex_comprehensions()`, `dataclasses()`, `function_conditionals()`, `functions()`, `function_contracts()`, `hygiene()`, `meaningful_returns(name_patterns=())`, `local_call_edges()`, `module_declarations()`, `named_calls()`, `outer_state_mutations()`, `parameter_mutations()`, `parameter_mutation_occurrences()`, `project_calls()`, `project_functions()`, `references()`, `test_functions()`, `top_level_definition_conditionals()`, and `test_module()`.","- `ctx.text`: `source`, `line(line_number)`, and `slice(source_range)`.","- `ctx.syntax`: `handles(kind=None)`, `kind(handle)`, and `range(handle)`.","- `ctx.relations`: `parent(handle)`, `children(handle)`, and `ancestors(handle)`.","- `ctx.project`: dependency-recording cross-file and filesystem queries. Use `analysis(requester=ctx.path, path=path)`, `dataclasses(requester=ctx.path, path=path)`, `directory_entries(requester=ctx.path, path=path)`, `entrypoint_modules(requester=ctx.path)`, `module_function(requester=ctx.path, module_name=name, function_name=name)`, `python_anchor(requester=ctx.path, path=path)`, `exists(requester=ctx.path, path=path)`, `is_dir(requester=ctx.path, path=path)`, `is_file(requester=ctx.path, path=path)`, and `glob(requester=ctx.path, path=path, pattern=pattern, recursive=False)`. Inspect recorded observations with `dependencies()` or `dependencies_for(requester=ctx.path)`.","","Position and ownership helpers: `ctx.path`, `ctx.repo_root`, `ctx.source`, `relative_parts()`, `repo_relative_parts()`, `scope_root()`, `scope_roots(scope)`, `module_parts()`, `scope()`, `role_of()`, `in_role(role)`, `is_entry_module()`, `is_main_module()`, `domain()`, and `subdomain()`. `role_of()` describes the current file here; use project facts rather than assuming arbitrary paths share its position.","","AST helpers: `nodes(node_type)`, `call_name(node)`, `base_name(node)`, `top_level_functions(module)`, `non_docstring_body(module)`, `distinct_callees(fn)`, `assigned_locals(fn)`, `complex_comprehensions()`, `parameter_names(fn)`, and `inside_loop(node)`.","","Policy helpers: `threshold(name=..., path=None)` and `contracts()`. Fault constructors: `fault(node=..., message=None, remediation=None)`, `fault_at(location=..., message=None, remediation=None)`, `fault_for(path=..., line=..., column=..., message=None, remediation=None)`, and `path_fault(path=None, message=None, remediation=None)`.",""],"work_practices":["## Working With Existing Drift","","The user request defines the scope of remediation. A large fault count is an architectural baseline, not authorization to fix unrelated code.","","- If the user requests one change, do not expand into unrelated fault remediation.","- If the user explicitly requests a broader refactor, particular fault families, or zero faults, treat that broader target as authorized scope.","- Satisfy faults by improving code under the current policy. Do not weaken selection, thresholds, exceptions, or custom rules unless the user explicitly requests a policy change.","- Before moving or splitting behavior, map the affected call flow and run the existing tests.","- When coverage around changed behavior is weak or unknown, add focused characterization tests before refactoring.","- Preserve behavior first and improve structure in verifiable slices.","- Distinguish pre-existing faults from regressions introduced by the current work.","","For an explicitly authorized broad refactor, capture the baseline, map affected flows, establish characterization coverage, work in coherent slices, verify each slice, and run full final verification. A request to make `fensu check` pass means fix the code under the current policy, not edit configuration until findings disappear.","","## Testing Refactors Safely","","Before materially restructuring behavior, inspect the existing tests. When the affected behavior is weakly covered or its coverage is uncertain, add focused characterization tests before moving code.","","Use the cheapest test that faithfully exercises the risk:","","- Unit tests for isolated decisions, transformations, and error handling.","- Integration tests for storage, messaging, process, and adapter boundaries.","- End-to-end tests for user-visible commands and workflows.","- Real local dependencies when they are deterministic and reasonably inexpensive.","","Prefer faithful local infrastructure over mocks when behavior depends on the real system. Useful options include PostgreSQL, Redis, Kafka or Redpanda, RabbitMQ, NATS, MinIO, OpenSearch, and similar services available through testcontainers.","","Before using testcontainers, check whether a functioning container runtime is available. Prefer `docker info`; if Docker is unavailable, check `podman info` and whether a compatible Docker API socket is configured. Finding the executable alone is not enough: verify the runtime can actually start containers. When a functioning runtime is available, testcontainers is an appropriate default for integration behavior that mocks cannot faithfully represent. Record the container-runtime requirement in the test documentation or final change summary.","","Use SQLite or DuckDB when they faithfully represent the tested contract. Do not use SQLite as evidence for PostgreSQL-specific SQL, transactions, locking, concurrency, extensions, or type behavior.","","Tests requiring real remote credentials or services such as Salesforce or Snowflake remain a user and project decision.","","When concurrency, retries, duplicate delivery, locking, or shared mutable state are real risks, add deterministic race-oriented tests where practical. Force relevant interleavings with barriers, events, controlled workers, or transactional locks rather than relying on sleeps. Assert atomicity, idempotency, ordering, uniqueness, and retry behavior as appropriate.","","Do not duplicate every assertion at unit, integration, and end-to-end levels. Each layer should prove a boundary that cheaper tests cannot prove faithfully.","","## Test Execution And Isolation","","Use the repository's established verification commands first. When pytest-xdist is installed and the relevant suite supports parallel execution, prefer:","","```bash","pytest -n auto","```","","Write new tests so they can execute independently whenever practical:","","- Use unique temporary paths, databases, schemas, ports, and resource names.","- Do not depend on test execution order.","- Isolate environment changes with fixtures such as monkeypatch.","- Avoid shared process-global mutation.","- Give each worker independent external state where concurrent access would alter the result.","- Make cleanup safe after both success and failure.","","When some tests genuinely require sequential execution, separate them from the parallel-safe suite. Run independent batches concurrently only when they do not share mutable resources. Otherwise run the required batches in sequence, while still using xdist inside each parallel-safe batch.","","If failures suggest broken isolation, rerun the failing tests sequentially and then rerun the relevant suite sequentially. A sequential pass does not make the problem acceptable: identify and correct the shared state, ordering dependency, port collision, database collision, or timing assumption where reasonable.",""]}

fensu_cli-0.3.0/crates/fensu-cli/src/command/constants.rs

@@ -0,0 +1,19 @@
+pub(crate) const MEMORY_SCHEMA_PREFIX: &str = "memory.";
+pub(crate) const OPTION_TERMINATOR: &str = "--";
+pub(crate) const MAP_SHORT_HELP: &str = "-h";
+pub(crate) const LONG_OPTION_PREFIX: &str = "--";
+pub(crate) const QUERY_FORMAT_LONG: &str = "long";
+pub(crate) const QUERY_FORMAT_TABLE: &str = "table";
+pub(crate) const QUERY_FORMAT_JSON: &str = "json";
+pub(crate) const QUERY_FORMAT_CSV: &str = "csv";
+pub(crate) const RELATION_KIND_TABLE: &str = "table";
+pub(crate) const RELATION_KIND_VIEW: &str = "view";
+pub(crate) const ARCHIVE_STATE_ARCHIVED: &str = "archived";
+pub(crate) const RESOLUTION_STATUS_RESOLVED: &str = "resolved";
+pub(crate) const DEFAULT_QUERY_LIMIT: usize = 20;
+pub(crate) const MAX_QUERY_LIMIT: usize = 1000;
+pub(crate) const MAP_USAGE: &str = "usage: fensu map [-h] [--direction {downstream}] [--depth DEPTH]\n                 [--root ROOTS] [--paths {absolute,relative,compact,none}]\n                 [--color {auto,always,never}] [--cache | --no-cache]\n                 [--cache-stats]\n                 symbol";
+pub(crate) const MAP_HELP: &str = "usage: fensu map [-h] [--direction {downstream}] [--depth DEPTH]\n                 [--root ROOTS] [--paths {absolute,relative,compact,none}]\n                 [--color {auto,always,never}] [--cache | --no-cache]\n                 [--cache-stats]\n                 symbol\n\npositional arguments:\n  symbol                bare, dotted, or path::function project symbol\n\noptions:\n  -h, --help            show this help message and exit\n  --direction {downstream}\n  --depth DEPTH         maximum call depth\n  --root ROOTS          Python import root to map; repeat for multiple roots\n  --paths {absolute,relative,compact,none}\n                        path display style\n  --color {auto,always,never}\n                        ANSI color behavior\n  --cache               enable map index caching\n  --no-cache            disable map index caching\n  --cache-stats         write map cache operation counts to stderr\n";
+pub(crate) const DEFAULT_GRAPH_DEPTH: usize = 2;
+pub(crate) const DEFAULT_GRAPH_NODES: usize = 50;
+pub(crate) const DEFAULT_GRAPH_EDGES: usize = 100;

fensu_cli-0.3.0/crates/fensu-cli/src/command/helpers/map_parsing.rs

@@ -0,0 +1,184 @@
+use crate::command::constants::{LONG_OPTION_PREFIX, MAP_SHORT_HELP, MAP_USAGE, OPTION_TERMINATOR};
+use crate::mapping::models::{MapOptions, PathMode};
+
+const LONG_OPTIONS: &[&str] = &[
+    "--help",
+    "--direction",
+    "--depth",
+    "--root",
+    "--paths",
+    "--color",
+    "--cache",
+    "--no-cache",
+    "--cache-stats",
+];
+
+pub(crate) fn parse(arguments: &[String]) -> Result<Option<MapOptions>, String> {
+    let mut symbol = None;
+    let mut depth = 3;
+    let mut roots = Vec::new();
+    let mut path_mode = PathMode::Relative;
+    let mut color = "auto".to_owned();
+    let mut cache_enabled = None;
+    let mut cache_stats = false;
+    let mut position = 0;
+    let mut options_ended = false;
+    while position < arguments.len() {
+        let argument = &arguments[position];
+        if !options_ended && argument == OPTION_TERMINATOR {
+            options_ended = true;
+            position += 1;
+            continue;
+        }
+        if options_ended {
+            if symbol.is_none() {
+                symbol = Some(argument.clone());
+            } else {
+                return Err(parser_error(&format!("unrecognized arguments: {argument}")));
+            }
+            position += 1;
+            continue;
+        }
+        let (name, inline) = argument
+            .split_once('=')
+            .map_or((argument.as_str(), None), |(name, value)| {
+                (name, Some(value))
+            });
+        let resolved = resolve_option(name)?;
+        match resolved {
+            "-h" | "--help" => return Ok(None),
+            "--direction" => {
+                let value = option_value(arguments, &mut position, resolved, inline)?;
+                choice(resolved, value, &["downstream"])?;
+            }
+            "--depth" => {
+                let value = option_value(arguments, &mut position, resolved, inline)?;
+                let parsed = value.parse::<i64>().map_err(|_| {
+                    parser_error(&format!(
+                        "argument --depth: invalid _nonnegative_int value: '{value}'"
+                    ))
+                })?;
+                if parsed < 0 {
+                    return Err(parser_error(
+                        "argument --depth: depth must be zero or greater",
+                    ));
+                }
+                depth =
+                    usize::try_from(parsed).map_err(|error| parser_error(&error.to_string()))?;
+            }
+            "--root" => {
+                roots.push(option_value(arguments, &mut position, resolved, inline)?.to_owned())
+            }
+            "--paths" => {
+                let value = option_value(arguments, &mut position, resolved, inline)?;
+                choice(
+                    resolved,
+                    value,
+                    &["absolute", "relative", "compact", "none"],
+                )?;
+                path_mode = match value {
+                    "absolute" => PathMode::Absolute,
+                    "compact" => PathMode::Compact,
+                    "none" => PathMode::None,
+                    _ => PathMode::Relative,
+                };
+            }
+            "--color" => {
+                let value = option_value(arguments, &mut position, resolved, inline)?;
+                choice(resolved, value, &["auto", "always", "never"])?;
+                color = value.to_owned();
+            }
+            "--cache" => {
+                if cache_enabled == Some(false) {
+                    return Err(parser_error(
+                        "argument --cache: not allowed with argument --no-cache",
+                    ));
+                }
+                cache_enabled = Some(true);
+            }
+            "--no-cache" => {
+                if cache_enabled == Some(true) {
+                    return Err(parser_error(
+                        "argument --no-cache: not allowed with argument --cache",
+                    ));
+                }
+                cache_enabled = Some(false);
+            }
+            "--cache-stats" => cache_stats = true,
+            _ if resolved.starts_with('-') => {
+                return Err(parser_error(&format!("unrecognized arguments: {argument}")));
+            }
+            _ if symbol.is_none() => symbol = Some(argument.clone()),
+            _ => return Err(parser_error(&format!("unrecognized arguments: {argument}"))),
+        }
+        position += 1;
+    }
+    let symbol =
+        symbol.ok_or_else(|| parser_error("the following arguments are required: symbol"))?;
+    Ok(Some(MapOptions {
+        symbol,
+        depth,
+        roots,
+        path_mode,
+        color,
+        cache_enabled,
+        cache_stats,
+    }))
+}
+
+fn resolve_option(name: &str) -> Result<&str, String> {
+    if name == MAP_SHORT_HELP
+        || !name.starts_with(LONG_OPTION_PREFIX)
+        || LONG_OPTIONS.contains(&name)
+    {
+        return Ok(name);
+    }
+    let matches = LONG_OPTIONS
+        .iter()
+        .copied()
+        .filter(|option| option.starts_with(name))
+        .collect::<Vec<_>>();
+    match matches.as_slice() {
+        [resolved] => Ok(resolved),
+        [] => Ok(name),
+        _ => Err(parser_error(&format!(
+            "ambiguous option: {name} could match {}",
+            matches.join(", ")
+        ))),
+    }
+}
+
+fn option_value<'a>(
+    arguments: &'a [String],
+    position: &mut usize,
+    name: &str,
+    inline: Option<&'a str>,
+) -> Result<&'a str, String> {
+    if let Some(value) = inline {
+        return Ok(value);
+    }
+    *position += 1;
+    arguments
+        .get(*position)
+        .map(String::as_str)
+        .ok_or_else(|| parser_error(&format!("argument {name}: expected one argument")))
+}
+
+fn choice(name: &str, value: &str, choices: &[&str]) -> Result<(), String> {
+    if choices.contains(&value) {
+        Ok(())
+    } else {
+        Err(parser_error(&format!(
+            "argument {name}: invalid choice: '{value}' (choose from {})",
+            choices
+                .iter()
+                .map(|choice| format!("'{choice}'"))
+                .collect::<Vec<_>>()
+                .join(", ")
+        )))
+    }
+}
+
+fn parser_error(message: &str) -> String {
+    format!("{MAP_USAGE}\nfensu map: error: {message}")
+}

fensu_cli-0.3.0/crates/fensu-cli/src/command/helpers/memory_execution.rs

@@ -0,0 +1,254 @@
+use std::env;
+use std::io::{self, IsTerminal};
+use std::path::Path;
+
+use fensu_memory::engine::main::archive_memory::archive_memory;
+use fensu_memory::engine::main::check_memory::check_memory;
+use fensu_memory::engine::main::memory_overview::memory_overview;
+use fensu_memory::engine::main::memory_relation_schema::memory_relation_schema;
+use fensu_memory::engine::main::memory_schema::memory_schema;
+use fensu_memory::engine::main::query_memory_graph::query_memory_graph;
+use fensu_memory::engine::main::query_memory_index::query_memory_index;
+use fensu_memory::engine::main::rebuild_memory_index::rebuild_memory_index;
+use fensu_memory::engine::main::sync_memory_index::sync_memory_index;
+use fensu_memory::engine::models::{MemoryGraphQuery, MemoryQueryResult, SyncSummary};
+use fensu_memory::source::main::bootstrap_memory::bootstrap_memory;
+
+use crate::command::constants::{
+    MEMORY_SCHEMA_PREFIX, QUERY_FORMAT_CSV, QUERY_FORMAT_JSON, QUERY_FORMAT_TABLE,
+};
+use crate::command::helpers::{
+    memory_graph_rendering, memory_help, memory_human_rendering, memory_parsing,
+    memory_structured_rendering,
+};
+use crate::command::models::{ColorMode, MemoryCommand, MemoryProject};
+use crate::configuration::main::load;
+use crate::helpers::render;
+use crate::models::{CliOutput, Fault};
+
+pub(crate) fn execute_memory(arguments: &[String]) -> Result<CliOutput, String> {
+    let arguments = memory_parsing::normalize_options(arguments);
+    if memory_help::requested(&arguments) {
+        return Ok(CliOutput::success(memory_help::text(&arguments)));
+    }
+    let parsed = memory_parsing::parse(&arguments)?;
+    let color = use_color(parsed.color);
+    let project = resolve_project()?;
+    execute(parsed.command, &project, color)
+}
+
+fn execute(
+    command: MemoryCommand,
+    project: &MemoryProject,
+    color: bool,
+) -> Result<CliOutput, String> {
+    match command {
+        MemoryCommand::Summary => summarize(project, color),
+        MemoryCommand::Archive { paths, confirmed } => {
+            let result = archive_memory(
+                &project.repository_root,
+                &project.database_path,
+                &paths,
+                project.archive_after_days,
+                confirmed,
+            )
+            .map_err(|error| format!("Memory archive failed: {error}"))?;
+            Ok(CliOutput::success(memory_human_rendering::archive(
+                &result, color,
+            )))
+        }
+        MemoryCommand::Check => check(project, color),
+        MemoryCommand::Sync => {
+            let summary = sync(project)?;
+            Ok(CliOutput::success(memory_human_rendering::sync(
+                &summary,
+                &project.repository_root,
+                &project.database_path,
+                false,
+                color,
+            )))
+        }
+        MemoryCommand::Rebuild => {
+            let summary = rebuild_memory_index(&project.repository_root, &project.database_path)
+                .map_err(|error| format!("Memory rebuild failed: {error}"))?;
+            Ok(CliOutput::success(memory_human_rendering::rebuild(
+                &summary,
+                &project.repository_root,
+                &project.database_path,
+                color,
+            )))
+        }
+        MemoryCommand::Schema { relation } => schema(relation.as_deref(), color),
+        MemoryCommand::Graph { query, format } => graph(project, &query, &format, color),
+        MemoryCommand::Sql {
+            query,
+            limit,
+            format,
+        } => sql(project, &query, limit, &format, color),
+    }
+}
+
+fn summarize(project: &MemoryProject, color: bool) -> Result<CliOutput, String> {
+    let summary = sync(project)?;
+    let overview = memory_overview(&project.database_path)
+        .map_err(|error| format!("Memory overview failed: {error}"))?;
+    let mut output = memory_human_rendering::sync(
+        &summary,
+        &project.repository_root,
+        &project.database_path,
+        true,
+        color,
+    );
+    output.push_str(&memory_human_rendering::overview(&overview, color));
+    Ok(CliOutput::success(output))
+}
+
+fn check(project: &MemoryProject, color: bool) -> Result<CliOutput, String> {
+    let result = check_memory(&project.repository_root, &project.database_path)
+        .map_err(|error| format!("Memory check failed: {error}"))?;
+    let faults = result
+        .diagnostics
+        .iter()
+        .map(|diagnostic| Fault {
+            code: diagnostic.code.to_owned(),
+            path: project
+                .repository_root
+                .join(&diagnostic.repository_relative_path)
+                .to_string_lossy()
+                .into_owned(),
+            line: diagnostic.line.and_then(|value| u32::try_from(value).ok()),
+            column: diagnostic
+                .column
+                .and_then(|value| u32::try_from(value).ok()),
+            message: diagnostic.message.clone(),
+            remediation: Some(diagnostic.remediation.to_owned()),
+            warning: false,
+        })
+        .collect::<Vec<_>>();
+    let stdout = render::report(render::ReportRequest {
+        faults: &faults,
+        warnings: &[],
+        root: &project.repository_root,
+        color,
+        show_warnings: false,
+        evaluation_summary: None,
+        applied_exceptions: 0,
+        threshold_uses: &[],
+    });
+    Ok(CliOutput {
+        stdout,
+        stderr: String::new(),
+        exit_code: i32::from(!faults.is_empty()),
+    })
+}
+
+fn schema(relation: Option<&str>, color: bool) -> Result<CliOutput, String> {
+    if let Some(name) = relation {
+        let qualified = if name.starts_with(MEMORY_SCHEMA_PREFIX) {
+            name.to_owned()
+        } else {
+            format!("{MEMORY_SCHEMA_PREFIX}{name}")
+        };
+        let relation = memory_relation_schema(&qualified)
+            .ok_or_else(|| format!("Unknown memory relation: {qualified}"))?;
+        return Ok(CliOutput::success(memory_human_rendering::relation(
+            &relation, color,
+        )));
+    }
+    Ok(CliOutput::success(memory_human_rendering::schema(
+        &memory_schema(),
+        color,
+    )))
+}
+
+fn graph(
+    project: &MemoryProject,
+    query: &MemoryGraphQuery,
+    format: &str,
+    color: bool,
+) -> Result<CliOutput, String> {
+    let summary = sync(project)?;
+    let result = query_memory_graph(&project.database_path, query)
+        .map_err(|error| format!("Memory graph failed: {error}"))?;
+    let machine = format == QUERY_FORMAT_JSON;
+    let stdout = if machine {
+        memory_structured_rendering::graph_json(&result, query)
+    } else {
+        memory_graph_rendering::graph(&result, query, color)
+    };
+    Ok(CliOutput {
+        stdout,
+        stderr: memory_human_rendering::sync(
+            &summary,
+            &project.repository_root,
+            &project.database_path,
+            true,
+            color && !machine,
+        ),
+        exit_code: 0,
+    })
+}
+
+fn sql(
+    project: &MemoryProject,
+    query: &str,
+    limit: usize,
+    format: &str,
+    color: bool,
+) -> Result<CliOutput, String> {
+    let summary = sync(project)?;
+    let result = query_memory_index(&project.database_path, query, limit)
+        .map_err(|error| format!("Memory query failed: {error}"))?;
+    let human = format != QUERY_FORMAT_JSON && format != QUERY_FORMAT_CSV;
+    Ok(CliOutput {
+        stdout: render_query(&result, format, color && human),
+        stderr: memory_human_rendering::sync(
+            &summary,
+            &project.repository_root,
+            &project.database_path,
+            true,
+            color && human,
+        ),
+        exit_code: 0,
+    })
+}
+
+fn render_query(result: &MemoryQueryResult, format: &str, color: bool) -> String {
+    match format {
+        QUERY_FORMAT_JSON => memory_structured_rendering::query_json(result),
+        QUERY_FORMAT_CSV => memory_structured_rendering::query_csv(result),
+        QUERY_FORMAT_TABLE => memory_human_rendering::query_table(result, color),
+        _ => memory_human_rendering::query_long(result, color),
+    }
+}
+
+fn sync(project: &MemoryProject) -> Result<SyncSummary, String> {
+    sync_memory_index(&project.repository_root, &project.database_path)
+        .map_err(|error| format!("Memory sync failed: {error}"))
+}
+
+fn resolve_project() -> Result<MemoryProject, String> {
+    let (source_path, loaded) = load::load(Path::new("."))?;
+    let repository_root = source_path
+        .parent()
+        .ok_or_else(|| "Fensu configuration has no repository directory.".to_owned())?
+        .to_path_buf();
+    if !loaded.memory_enabled {
+        return Err(
+            "Fensu Memory is disabled; set experimental.memory = true in the project configuration."
+                .to_owned(),
+        );
+    }
+    bootstrap_memory(&repository_root)?;
+    let database_path = repository_root.join(".fensu/memory/memory.sqlite3");
+    Ok(MemoryProject {
+        repository_root,
+        database_path,
+        archive_after_days: loaded.memory_archive_after_days,
+    })
+}
+
+fn use_color(mode: ColorMode) -> bool {
+    env::var_os("NO_COLOR").is_none()
+        && (mode == ColorMode::Always || mode == ColorMode::Auto && io::stdout().is_terminal())
+}