feature-map-cli 1.0.0__tar.gz

feature_map_cli-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.DS_Store

feature_map_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-29
+
+### Added
+
+- `feature-map` CLI
+- Full command surface: `list`, `show`, `search`, `find`, `graph`, `validate`,
+  `check`, `impact`, `stats`, `init`, `install`, `--json`, `--version`
+- `feature-map init` bootstraps any repo: `.features/`, agent skill, `.feature-map.yaml`,
+  `AGENTS.md` snippet, and `bin/feature-map` shim
+- `feature-map init <name>` scaffolds a new map from the bundled template
+- `feature-map init --upgrade-skill` refreshes the agent skill from the installed package
+- Fixture-based test suite
+- Homebrew formula draft in `Formula/feature-map.rb`
+- pip-installable entrypoint via `pyproject.toml`
+
+### Changed
+
+- Public CLI and Homebrew name is `feature-map` (`brew install feature-map`).
+  The PyPI project is `feature-map-cli` (`pip install feature-map-cli`) because
+  PyPI treats `feature-map` as too similar to the existing biology package
+  `featuremap`. The Python import is `feature_map`.
+- Repo-local `bin/feature-map` shim execs `feature-map` without recursing if
+  `bin/` is on PATH.
+- `init` writes `<!-- feature-map:start -->` in `AGENTS.md` and migrates the
+  older `<!-- featuremap:start -->` block.
+
+[Unreleased]: https://github.com/markschellhas/feature-map/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/markschellhas/feature-map/releases/tag/v1.0.0

feature_map_cli-1.0.0/Formula/feature-map.rb

@@ -0,0 +1,31 @@
+# Draft Homebrew formula. Fill url/sha256 from the PyPI sdist after the
+# first upload. Full steps: PUBLISH.md.
+#
+# Until then, install from this tree:
+#
+#   pip install -e .
+#
+# or from a tap:
+#
+#   brew install --HEAD markschellhas/tap/feature-map
+
+class FeatureMap < Formula
+  desc "Cross-app architecture research CLI"
+  homepage "https://github.com/markschellhas/feature-map"
+  license "MIT"
+  head "https://github.com/markschellhas/feature-map.git", branch: "master"
+
+  depends_on "python@3.12"
+
+  def install
+    virtualenv = libexec/"venv"
+    system Formula["python@3.12"].opt_libexec/"bin/python", "-m", "venv", virtualenv
+    system virtualenv/"bin/pip", "install", "."
+    bin.install_symlink virtualenv/"bin/feature-map"
+    (share/"feature-map").install Dir["share/feature_map/*"] if File.directory?("share/feature_map")
+  end
+
+  test do
+    assert_match "1.0.0", shell_output("#{bin}/feature-map --version")
+  end
+end

feature_map_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taptics
+
+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.

feature_map_cli-1.0.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: feature-map-cli
+Version: 1.0.0
+Summary: Cross-app architecture research CLI driven by .features/*.yaml maps
+Project-URL: Homepage, https://github.com/markschellhas/feature-map
+Project-URL: Repository, https://github.com/markschellhas/feature-map
+Author: Taptics
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,architecture,cli,feature-map
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.8
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Feature Map
+
+Cross-app architecture research CLI. Agents and engineers keep authoritative
+feature maps in `.features/*.yaml`; `feature-map` lists, searches, validates,
+and graphs them.
+
+A wiki stores architecture as prose — agents re-read a whole page to find three
+files. Feature Map stores **fields** (`purpose`, `entry_points`, `apps`) and a
+CLI that returns **names and sections**, so lookup is cheap and `check` can
+prove paths still exist.
+
+## Install
+
+```bash
+pip install -e .
+# pip install feature-map-cli
+# brew install feature-map
+```
+
+Requires Python 3.8+ and PyYAML. The CLI is `feature-map`. Install from PyPI as
+`feature-map-cli` — `pip install featuremap` is a different (biology) project,
+and `feature-map` is blocked on PyPI as too similar to that name.
+
+## Usage
+
+```bash
+cd my-repo
+feature-map init
+feature-map init auth          # scaffold .features/auth.yaml
+feature-map list
+feature-map search billing
+feature-map validate
+```
+
+`feature-map init` is idempotent. It:
+
+1. Creates `.features/`
+2. Copies the agent skill to `.agents/skills/feature-map/` (or `.grok/skills/` if that tree already exists)
+3. Writes `.feature-map.yaml` defaults when missing
+4. Appends an `AGENTS.md` block (skip with `--no-agents`)
+5. Writes `bin/feature-map` as a repo-local shim (skip with `--no-shim`)
+
+Refresh the skill after upgrading the package:
+
+```bash
+feature-map init --upgrade-skill
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `list` | All feature slugs |
+| `show <name>` / `<name>` | Print a map (or `--section`) |
+| `search <query>` | Full-text search |
+| `find <path>` | Reverse lookup by path fragment |
+| `graph [name]` | `related_features` graph (`mermaid`, `json`, `dot`) |
+| `validate [--strict]` | Structural checks |
+| `check` | Stale `entry_points` / `core_components` paths |
+| `impact <file>` | Which maps reference a file |
+| `stats` | Coverage summary |
+| `init` / `init <name>` | Bootstrap repo or scaffold a map |
+| `install` | Setup status |
+| `--json` / `--version` | Machine output / version |
+
+Exit codes: `0` ok, `1` user error, `2` validation failure (`--strict`).
+
+## Per-repo config
+
+`.feature-map.yaml` at the git root:
+
+```yaml
+features_dir: .features
+apps:
+  - api
+  - web
+required_sections:
+  - purpose
+  - entry_points
+min_cli_version: "1.0.0"
+```
+
+`apps` prefixes are used by `check` when resolving paths.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q
+```
+
+## License
+
+MIT

feature_map_cli-1.0.0/README.md

@@ -0,0 +1,94 @@
+# Feature Map
+
+Cross-app architecture research CLI. Agents and engineers keep authoritative
+feature maps in `.features/*.yaml`; `feature-map` lists, searches, validates,
+and graphs them.
+
+A wiki stores architecture as prose — agents re-read a whole page to find three
+files. Feature Map stores **fields** (`purpose`, `entry_points`, `apps`) and a
+CLI that returns **names and sections**, so lookup is cheap and `check` can
+prove paths still exist.
+
+## Install
+
+```bash
+pip install -e .
+# pip install feature-map-cli
+# brew install feature-map
+```
+
+Requires Python 3.8+ and PyYAML. The CLI is `feature-map`. Install from PyPI as
+`feature-map-cli` — `pip install featuremap` is a different (biology) project,
+and `feature-map` is blocked on PyPI as too similar to that name.
+
+## Usage
+
+```bash
+cd my-repo
+feature-map init
+feature-map init auth          # scaffold .features/auth.yaml
+feature-map list
+feature-map search billing
+feature-map validate
+```
+
+`feature-map init` is idempotent. It:
+
+1. Creates `.features/`
+2. Copies the agent skill to `.agents/skills/feature-map/` (or `.grok/skills/` if that tree already exists)
+3. Writes `.feature-map.yaml` defaults when missing
+4. Appends an `AGENTS.md` block (skip with `--no-agents`)
+5. Writes `bin/feature-map` as a repo-local shim (skip with `--no-shim`)
+
+Refresh the skill after upgrading the package:
+
+```bash
+feature-map init --upgrade-skill
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `list` | All feature slugs |
+| `show <name>` / `<name>` | Print a map (or `--section`) |
+| `search <query>` | Full-text search |
+| `find <path>` | Reverse lookup by path fragment |
+| `graph [name]` | `related_features` graph (`mermaid`, `json`, `dot`) |
+| `validate [--strict]` | Structural checks |
+| `check` | Stale `entry_points` / `core_components` paths |
+| `impact <file>` | Which maps reference a file |
+| `stats` | Coverage summary |
+| `init` / `init <name>` | Bootstrap repo or scaffold a map |
+| `install` | Setup status |
+| `--json` / `--version` | Machine output / version |
+
+Exit codes: `0` ok, `1` user error, `2` validation failure (`--strict`).
+
+## Per-repo config
+
+`.feature-map.yaml` at the git root:
+
+```yaml
+features_dir: .features
+apps:
+  - api
+  - web
+required_sections:
+  - purpose
+  - entry_points
+min_cli_version: "1.0.0"
+```
+
+`apps` prefixes are used by `check` when resolving paths.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q
+```
+
+## License
+
+MIT

feature_map_cli-1.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "feature-map-cli"
+version = "1.0.0"
+description = "Cross-app architecture research CLI driven by .features/*.yaml maps"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+  { name = "Taptics" },
+]
+keywords = ["architecture", "feature-map", "cli", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+  "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+]
+
+[project.scripts]
+feature-map = "feature_map.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/markschellhas/feature-map"
+Repository = "https://github.com/markschellhas/feature-map"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/feature_map"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"share/feature_map" = "feature_map/share"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/feature_map",
+  "share/feature_map",
+  "tests",
+  "Formula",
+  "README.md",
+  "LICENSE",
+  "CHANGELOG.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]

feature_map_cli-1.0.0/share/feature_map/schema/feature-map.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Map",
+  "type": "object",
+  "required": ["feature_name", "purpose", "entry_points"],
+  "properties": {
+    "feature_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 1
+    },
+    "entry_points": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      }
+    },
+    "apps": {
+      "type": ["array", "object"]
+    },
+    "user_flow": {
+      "type": "object"
+    },
+    "related_features": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "notes": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}

feature_map_cli-1.0.0/share/feature_map/skill/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: feature-map
+version: 1.0.0
+description: "Research cross-app architecture via the Feature Map CLI before feature work, debugging, PRDs, or implementation plans. Run list, show, search, find, graph, validate, and check against .features/*.yaml. On existing repos with no maps, scour the code and author maps first."
+---
+
+# Feature Map
+
+Authoritative cross-app architecture lives in `.features/*.yaml`. **Always**
+use this skill before touching a feature. Do not plan, debug, or implement
+from a cold grep when a map exists — or when one should exist and does not.
+
+Maps are **fields, not a wiki**. Prefer `list` / `search` / `show --section`
+over reading a long markdown doc. That keeps token use on paths and purpose,
+not narrative. When writing or updating a map, same rule: cover every door
+and coupling; do not write narrative (`references/authoring.md`, Density).
+See the package `GUIDE.md` ("Why this, not a wiki").
+
+## When to invoke
+
+- Before feature implementation, debugging, PRDs, implementation plans, or pre-mortems
+- When unsure which feature map applies
+- After shipping changes that affect architecture (update maps, then validate)
+- When `list` is empty or `search`/`find` miss: **scour the repo and author maps** before other work (see `references/existing-repos.md`)
+
+## Research sequence
+
+```bash
+feature-map list
+feature-map search <keyword>    # when the feature name is unclear
+feature-map find <path-fragment>
+feature-map <feature-name>      # or: show <feature-name>
+feature-map graph <feature>     # cross-cutting dependencies
+```
+
+`./bin/feature-map` is a repo-local shim for the same CLI (created by `feature-map init`).
+
+Use `show <name> --section entry_points` (or `purpose`, `user_flow`, etc.) to limit token use on large maps.
+
+If the list is empty, or nothing matches the area you are about to change,
+**stop**. Follow `references/existing-repos.md`: inventory apps, cluster
+capabilities, `feature-map init <slug>`, fill real paths, `validate` + `check`.
+Then resume the research sequence.
+
+## After implementation
+
+1. Patch the fields that changed. Do not grow the map with prose.
+2. Run `feature-map validate`
+3. Run `feature-map check`
+
+## Commands
+
+See `references/commands.md` for the full CLI reference.
+
+## Authoring
+
+See `references/authoring.md` for shape, density, and conventions.
+See `references/existing-repos.md` when adopting Feature Map on a codebase that already exists.

feature_map_cli-1.0.0/share/feature_map/skill/references/authoring.md

@@ -0,0 +1,37 @@
+# Authoring Feature Maps
+
+Feature maps live in `.features/<slug>.yaml` at the repo root.
+
+## Required sections
+
+- `feature_name` — must match the filename stem (normalized)
+- `purpose` — one sentence: what it does. Skip motivation unless it changes where you look.
+- `entry_points` — primary doors only (routes, screens, jobs, CLIs); real paths
+- `apps` — app names as a list, not descriptions (recommended; warning if missing)
+
+## Recommended sections
+
+- `user_flow` — one line per distinct path: `Actor → step → result`. Add `alt`/`error` only if code diverges.
+- `related_features` — `slug (coupling)`; parenthetical is a phrase
+
+## Optional
+
+- `notes` — caveats and unknowns only; omit the key if none. Never history, README, or process tips. `validate` does not warn when this key is absent.
+
+## Density
+
+Index, not essay. Completeness is doors, apps, and couplings. Delete a sentence if it would not change which file the next agent opens. Do not drop a real door, app, or related slug to stay short. Do not add narrative keys (`overview`, `history`, `architecture`, `background`). `core_components` is the only extra path group `check` understands.
+
+## Conventions
+
+- Use underscores in filenames: `user_signup.yaml`
+- `related_features` entries should start with a resolvable slug
+- Run `feature-map validate` and `feature-map check` after edits
+- Scaffold new maps: `feature-map init <name>`
+- Bootstrap a new repo: `feature-map init`
+- Existing repo with no maps: scour the code first (`existing-repos.md`); do not skip maps because the codebase predates Feature Map
+- Patch fields in place when the architecture changes; do not append prose
+
+## Schema
+
+JSON Schema ships with the package at `share/feature_map/schema/feature-map.schema.json`.

feature_map_cli-1.0.0/share/feature_map/skill/references/commands.md

@@ -0,0 +1,47 @@
+# Feature Map CLI Reference
+
+Invocation: `feature-map` (on PATH) or `./bin/feature-map` (repo-local shim).
+
+Global flags: `--json`, `--version`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `list [--json]` | All feature slugs; JSON includes mtime and app count |
+| `show <name> [--section <key>] [--json]` | Full map or one top-level section |
+| `<name>` | Alias for `show <name>` |
+| `search <query> [--json]` | Full-text search across all maps |
+| `find <path-fragment> [--json]` | Reverse lookup by path string |
+| `graph [name] [--format mermaid\|json\|dot]` | `related_features` graph |
+| `validate [--strict] [--json]` | Structural validation |
+| `check [--json]` | Staleness check for entry-point paths |
+| `impact <file> [--transitive] [--json]` | Features referencing a file |
+| `stats [--json]` | Coverage statistics |
+| `init` | Bootstrap `.features/`, agent skill, config, AGENTS.md, shim |
+| `init <name> [--force]` | Scaffold `.features/<name>.yaml` |
+| `init --upgrade-skill` | Refresh the agent skill from the installed package |
+| `install [--json]` | Verify install and repo setup |
+
+## Examples
+
+```bash
+feature-map list
+feature-map auth
+feature-map show auth --section entry_points
+feature-map search billing
+feature-map find src/app.py
+feature-map graph auth --format mermaid
+feature-map validate
+feature-map check --json
+feature-map impact src/app.py
+feature-map stats --json
+feature-map init
+feature-map init billing --force
+```
+
+## Exit codes
+
+- `0` — success
+- `1` — user error (e.g. feature not found)
+- `2` — validation failure (`validate --strict`)

feature_map_cli-1.0.0/share/feature_map/skill/references/existing-repos.md

@@ -0,0 +1,43 @@
+# Bootstrapping maps on an existing repository
+
+`feature-map init` creates the workflow. It does **not** invent maps from
+source. On a repo that already has code, you must **scour the tree and
+author** `.features/*.yaml` before doing feature work.
+
+## When this applies
+
+- `feature-map list` is empty
+- `search` / `find` miss the area you are about to change
+- `.feature-map.yaml` `apps` is `[]` but the repo has multiple packages
+
+Do not skip this and "just grep". Author maps first, then implement.
+
+## Playbook
+
+1. **Inventory apps** — top-level directories and manifests (`Gemfile`,
+   `package.json`, `pyproject.toml`, `go.mod`, `pubspec.yaml`, `apps/`,
+   `packages/`). Write them under `apps:` in `.feature-map.yaml`.
+2. **Find seams** — routes, app shells, domain models, jobs, CLIs, docs,
+   and test names. These are where features show up.
+3. **Cluster** — one map per user-visible capability or subsystem, not
+   per file. Cross-app journeys are one map with several `apps` and
+   `entry_points`.
+4. **Scaffold + fill** — `feature-map init <slug>`, then replace
+   placeholders with real paths and a one-sentence `purpose` you
+   verified in code (`authoring.md`, Density).
+5. **Verify** — `feature-map validate` and `feature-map check`. Prefer
+   paths that exist on disk. Record uncertainty in `notes`.
+6. **Stop the first pass** when every listed app appears on at least one
+   map and the README's product nouns `search` successfully.
+
+Full narrative: the package `GUIDE.md` §3.4 (existing repos).
+
+## Anti-patterns
+
+- One map per source file
+- Invented `entry_points` that `check` would mark missing
+- `entry_points` as a file inventory (doors only)
+- Essays in `purpose`, `user_flow`, or `notes`
+- Extra narrative keys (`overview`, `history`, `architecture`)
+- `related_features` that do not start with a real slug
+- Planning or coding a feature that has no map "because the repo is old"

feature_map_cli-1.0.0/share/feature_map/templates/feature.yaml.tpl

@@ -0,0 +1,17 @@
+feature_name: {{feature_name}}
+purpose: "One sentence: what {{FEATURE_TITLE}} does."
+
+entry_points:
+  - path/to/primary/entry_point
+  - path/to/secondary/surface
+
+apps:
+  - app_name
+
+user_flow:
+  primary: "Actor → action → result."
+
+related_features:
+  - related_feature_slug (coupling)
+
+# notes: caveats/unknowns only — omit this key if none

feature_map_cli-1.0.0/src/feature_map/__init__.py

@@ -0,0 +1,3 @@
+from feature_map._version import __version__
+
+__all__ = ["__version__"]

feature_map_cli-1.0.0/src/feature_map/__main__.py

@@ -0,0 +1,3 @@
+from feature_map.cli import main
+
+raise SystemExit(main())

feature_map_cli-1.0.0/src/feature_map/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"