macrostates-cli 0.3.1__tar.gz → 0.5.0__tar.gz

macrostates_cli-0.5.0/.macrostates/implementation/application.yaml

@@ -0,0 +1,10 @@
+schema_version: 1
+name: macrostates-cli
+version: 0.5.0
+status: candidate
+specification: specs-2.0.0
+implementation: imp-2.0.0
+release_date: '2026-10-13'
+source:
+  tag: v0.5.0
+source_sha256: 9b1ce349710c5f6875d4c0b59027a5e0b023392d38822792df0df0e9028b4f90

macrostates_cli-0.5.0/.macrostates/implementation/release.yaml

@@ -0,0 +1,4 @@
+version: imp-2.0.0
+specification: specs-2.0.0
+release_date: '2026-10-13'
+schema_version: 2

macrostates_cli-0.5.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include .macrostates/implementation/release.yaml
+include .macrostates/implementation/application.yaml

macrostates_cli-0.5.0/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: macrostates-cli
+Version: 0.5.0
+Summary: Compose, install and validate versioned Macrostates specification packages.
+Author-email: Lucas Lopez <713375+lucaslopez@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Macrostates/macrostates-cli
+Project-URL: Documentation, https://github.com/Macrostates/macrostates-cli#readme
+Project-URL: Issues, https://github.com/Macrostates/macrostates-cli/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0.2
+Dynamic: license-file
+
+# Macrostates CLI
+
+Install, inspect, and check reusable specification packages. Prepare development
+change records, synchronize Git branches, and review integration and baseline
+release readiness. Packages stay readable in numbered, version-controlled
+directories such as `000_meta/` and `001_process/`.
+
+The `macrostates` command and public `macrostates` Python API share the same
+operations. Requires Python 3.12 or newer. Distribution name: `macrostates-cli`.
+Import package and executable name: `macrostates`.
+Licensed under [MIT](https://github.com/Macrostates/macrostates-cli/blob/main/LICENSE).
+
+Application version `0.5.0` supports Meta 3.0 and Process 5.1 alongside earlier
+selected policies. Its own composition uses released Meta 3.0.0, Process 5.1.0,
+Repository 4, Python 2.1.1 and Python-library 2 packages. Under Meta 3.0 and
+Process 5.1, implementers choose version impact within requested work without a
+separate Major-number approval.
+The CLI application version is independent from its Macrostates specification
+and implementation baselines. Older projects retain their selected formats and
+policies until explicitly adopted and migrated.
+
+## Installation
+
+Install the published package from
+[PyPI](https://pypi.org/project/macrostates-cli/) with pip in a Python 3.12 or
+newer environment:
+
+```bash
+python -m pip install "macrostates-cli>=0.5.0"
+macrostates --help
+```
+
+Use `python -m pip install macrostates-cli==0.5.0` to select this release, or
+`python -m pip install --upgrade macrostates-cli` to update. The older `0.3.1` and `0.4.0`
+releases remain available for projects that deliberately retain it. A virtual environment can be created with
+`python -m venv .venv`; activate it before installing when your environment
+requires one. For a command outside a project environment, use
+`pipx install macrostates-cli` or `uv tool install macrostates-cli`.
+
+To work from source, clone the repository and run `uv sync --locked`.
+Use `uv run macrostates ...` from that environment. Installed version reporting
+uses distribution metadata; source development identities are inspected through
+the separate `identity` command.
+
+## Start A Project
+
+Supply a composition with explicit package versions, sources, authority, and
+reading orders. The
+[minimal composition](https://github.com/Macrostates/macrostates-cli/blob/main/examples/composition.yaml)
+selects only Meta; add Process and the technology packages appropriate to your
+project.
+
+```bash
+macrostates init --from /path/to/composition.yaml
+macrostates install
+macrostates info
+macrostates check
+```
+
+The shorthand `macrostates init --name my-project --package meta@3.0.0`
+creates a composition. Repeat `--package NAME@VERSION` for additional packages.
+Input order supplies both reading order and authority, highest first; review them
+before installation. No dependency or latest release is selected automatically.
+Use `--from` for custom sources and deliberate orders.
+
+The default layout is:
+
+```text
+AGENTS.md
+.macrostates/
+  specs/
+    main.md
+    composition.yaml
+    composition.lock.yaml
+    000_meta/
+    ...
+  implementation/
+    main.md
+```
+
+Commit the composition, lock, package copies, and local requirements. Initialization
+preserves existing agent instructions, refuses overwrites, and creates
+specification scaffolding. Process 5 initialization supplies a provisional
+specification seed; it never invents an accepted implementation baseline. Establish
+the first baseline explicitly under the selected Process policy before using
+ordinary release planning.
+
+The CLI is strongly recommended and optional. Structural checks and recorded
+evidence assist specification reading; semantic requirements, truthful approval,
+and implementation conformance still need review. Existing projects keep their
+selected policies until deliberately adopted and migrated.
+
+## Package Commands
+
+| Command | Purpose | Effects |
+| --- | --- | --- |
+| `init` | Prepare selected specification files | Local writes |
+| `install` | Download and validate selected package releases | Source access and package/lock writes |
+| `install --locked` | Restore an unchanged locked selection | Source access and package/lock writes |
+| `lock` | Compare copies with canonical releases and record integrity | Source access and lock write |
+| `verify` | Check external inventories and executable flags | Offline, read-only |
+| `lint` | Check metadata, dependencies, orders, links, and selected policies | Offline, read-only |
+| `info` | Inspect selections, provenance, dependencies, and scopes | Offline, read-only |
+| `check` | Combine lint and integrity verification | Offline, read-only |
+| `check --staged` | Check the exact Git index | Offline, read-only |
+
+All commands accept `--project PATH` and `--json` before or after the command.
+Discovery uses the nearest composition and stops at a Git root. Ambiguous
+manifests/layouts fail clearly. Exit codes are **0** for success, **1** for failed
+checks, and **2** for invalid input/operations. Usage errors retain standard text
+help. Reports include diagnostic codes, messages, paths, and severity.
+
+Local packages use `source: {type: local}`. They remain editable and linted;
+external inventory checks exclude them. Exact composition selections and verified
+locks preserve downloaded package identities.
+
+## Git Package Sources And Recovery
+
+This version supports `source.type: git-archive` with an explicitly
+configured Git URL, SSH remote, or local repository and an annotated
+`vMAJOR.MINOR.PATCH` tag. It materializes the exact resolved commit as tracked
+files, using externally configured Git authentication. Installed packages are
+readable snapshots and do not contain upstream working clones.
+
+The legacy `github-archive` transport and public `GitHubSource` provider remain
+available for existing compositions. That provider retains explicit token,
+`GH_TOKEN`/`GITHUB_TOKEN`, and existing GitHub CLI login authentication precedence.
+The generic `GitSource` provider uses configured Git authentication. Credentials
+are never stored in compositions/locks or echoed in transport errors.
+
+For updates, deliberately change selected `version` and `source.tag`, review the
+human entrypoint and dependencies, then run `install`. It replaces a previous
+copy only when that copy matches its locked inventory. Modified content is
+preserved. Use `install --locked` to restore a missing unchanged copy.
+
+Locks record full commit IDs and SHA-256 inventories of bytes and executable
+flags. Reinstallation refuses a tag moved to another commit. Offline `verify`
+cannot discover remote tag movement or establish the trustworthiness of an edited
+lock; review locks with their package changes.
+
+Package and release preparation roll back ordinary replacement failures and
+retain recovery data when rollback itself fails. Interrupted operations require
+inspection before retrying. See
+[recovery guidance](https://github.com/Macrostates/macrostates-cli/blob/main/.macrostates/specs/051_cli/annex_recovery.md).
+
+## Development And Baseline Releases
+
+The following development commands require explicit selection of supported
+Process 5.0 or 5.1. `branch-status` and `branch-sync` also serve projects retaining older
+version policies. Core operations work with Git refs and commits; your repository
+policy defines the review/integration mechanism and required external checks.
+
+New baseline tooling uses a shared composition at the Git repository root,
+including monorepos with several applications. Independently composed nested
+projects within another checkout keep existing package checks, but need separate
+Git or manual procedures for independent baselines. Identity inspection explains
+when computed source identity is unavailable.
+
+| Command | Purpose |
+| --- | --- |
+| `start-work --id ID` | Capture starting commit and baseline provenance before development or synchronization |
+| `identity --work ID` | Inspect the work's computed development identity |
+| `deliverables` | Inspect optional application policies and effective default versions |
+| `change-create` | Declare separate specification/implementation impact, coverage, evidence, and gaps |
+| `change-check` | Check those records for readiness |
+| `closure-request` | List workflows and produce a numbered request for definer-authorized closure |
+| `branch-status --target REF` | Inspect divergence against cached target state |
+| `branch-sync --target REF --strategy merge\|rebase` | Incorporate upstream changes on a safe development branch |
+| `integration-check --target REF` | Validate exact proposed combined contents and local readiness |
+| `release-plan --target REF` | Calculate a reviewed, target/tree-bound baseline plan |
+| `release-prepare --plan PATH --date YYYY-MM-DD` | Prepare candidate declarations and consume included records |
+| `release-check` | Check candidate consistency and baseline identities |
+| `release-check --publication` | Additionally require integrated annotated baseline tags and declared release source identities |
+| `migrate-versioning` | Explicitly convert legacy declarations and preserve original refs/provenance |
+
+Create development and release branches through the repository's policy. The CLI
+does not create branches, submit integration proposals, approve reviews, tag,
+push, or upload artifacts. Synchronization may merge or rebase commits only when
+explicitly requested. It refuses the primary branch, dirty/detached states, and
+existing operations, and leaves conflicts for the implementer to resolve. Add
+`--fetch-remote NAME` to explicitly fetch a configured remote first.
+
+After creating a branch, capture work before adding commits:
+
+```bash
+macrostates start-work --id offline-mode
+macrostates identity --work offline-mode
+```
+
+If work started earlier, use `--origin-commit` with its actual full original
+commit ID. The original provenance remains unchanged when upstream updates are
+incorporated. A computed identity can look like
+`imp-0.3.1-branch.feature-x.gabc123`; it does not reserve the next release number.
+
+When preparing completed work, declare its impact explicitly:
+
+```bash
+macrostates change-create --id offline-mode --work offline-mode \
+  --summary "Support the specified offline operation" \
+  --specification-impact minor --implementation-impact minor \
+  --requirements /path/to/coverage.yaml \
+  --evidence "Offline behavior checks passed"
+macrostates change-check
+macrostates closure-request
+```
+
+The coverage document contains a `requirements` list with `requirement`,
+`implementation`, and `verification` entries. Use explicit `none` impacts for
+tracking-only changes. Semantic classification remains the implementer's
+responsibility. Obtain the definer's required closure authorization and record
+it; the CLI never closes workflows automatically.
+
+Commit the completed preparation, then run `integration-check` against the
+current target. Optional `--expected-target` binds the check to a full target
+commit. The combined result must have valid scope/evidence and no open or
+unconfirmed workflows, including history. Required external reviews and CI may
+begin after a proposal is created, but still block final integration.
+
+Accepted change records accumulate on the primary branch as unreleased work.
+When finalization is requested, create a release branch from current integrated
+state, refresh and incorporate the authoritative target, and review
+`release-plan --target origin/main` when that is the configured authoritative
+ref. The command uses cached state without fetching automatically. Save its
+output outside the checkout or in an
+ignored location. `release-prepare` applies that exact plan without committing it.
+Changed source, records, declarations, or target require reassessment. Close the
+release-preparation workflow, commit and check the candidate, then follow the
+project's reviewed integration procedure. Tagging and publication remain separate
+authorized operations.
+
+Applications can release independently of the shared `specs-*` and `imp-*`
+baselines. Without an application policy, their stable version is the numeric
+selected implementation version. Android can use that default version name and
+retain its own increasing version code. A new repository baseline does not
+automatically release every application. Preserve exact source and baseline
+provenance for each published deliverable.
+
+An application policy may permit a later release of identity metadata, such as its
+version/date or an Android counter, against an existing finalized baseline.
+Review a ready `none`/`none` change record with evidence and no gaps, close its
+workflows, and validate that only permitted metadata/bookkeeping changed. The
+record stays pending; the old baseline plan, consumed records, and tags remain
+unchanged. The application release identifies its new source commit separately
+from those exact baseline references. No no-bump baseline plan is created.
+Runtime, contract, or build-logic changes require ordinary impact classification.
+
+The application still needs a new identity accepted by its distribution policy.
+The numeric implementation default cannot be reused to upload changed artifacts
+under an already published immutable package version. Independent numbering or
+a technology-specific additional identity distinguishes another release.
+
+## Python API
+
+```python
+from macrostates import Project
+
+project = Project.open("/path/to/project")
+report = project.check()
+for diagnostic in report.diagnostics:
+    print(diagnostic.code, diagnostic.message, diagnostic.path)
+assert report.ok
+```
+
+Supported root exports include `Project`, `Report`, `Diagnostic`,
+`MacrostatesError`, `GitSource`, and `SourceProvider`, with the retained legacy
+transport provider documented above. `Project.open` and `Project.initialize`
+construct projects. The package and development operations in the tables have
+matching public methods, including `start_work`, `create_change`, `sync_branch`,
+`check_integration`, `plan_release`, and `prepare_release`.
+
+Pass `source=GitSource()` or an injected `SourceProvider` for explicit transport
+control. Report-returning checks return unsuccessful diagnostics rather than
+terminating the caller. Invalid operations raise `MacrostatesError`; ordinary
+file reads may raise `OSError`. Imports perform no project/network I/O or logging
+configuration. Explicit `__version__` access reads installed distribution metadata.
+See the
+[public library contract](https://github.com/Macrostates/macrostates-cli/blob/main/.macrostates/specs/051_cli/002_library.md)
+for signatures and the
+[development contract](https://github.com/Macrostates/macrostates-cli/blob/main/.macrostates/specs/051_cli/008_development-and-releases.md)
+for data and readiness boundaries.
+
+## Compatibility And Contributing
+
+Retain composition formats 0/1, package metadata format 1, inventory lock format
+1, modern and legacy locations, and previously supported release-policy adapters.
+New Process operations require deliberate policy adoption; reading an older
+project never migrates it. Tagged legacy subtrees remain maintainable through Git
+and canonical locking; archive installation does not convert them implicitly.
+Unknown future formats/policies fail clearly.
+
+```bash
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run pytest --cov=macrostates --cov-report=term-missing
+uv build
+```
+
+Contributor dependencies are locked. Build output goes to ignored `dist/` and
+temporary work to `tmp/<activity>/`. Optional hooks can run `check --staged`;
+integration-preparation checks belong at their dedicated gate, since ordinary
+development commits legitimately contain open workflows. Index checks preserve
+partial staging, have documented resource limits, and exclude submodule contents.
+
+The CLI tracks its own composition under `.macrostates/specs/`. The exact
+released selections passed canonical installation, locked reinstallation and
+offline checks. Baseline finalization and application publication retain their
+separate verification gates. The source uses an independent
+[application declaration](https://github.com/Macrostates/macrostates-cli/blob/main/.macrostates/implementation/application.yaml)
+for independent build version `0.5.0`; the Macrostates implementation declaration is a
+separate identity. Candidate/finalized builds bind verified shipped source and
+rebuild from source distributions without Git. Builds do not mutate declarations
+or publish artifacts.
+
+See
+[implementation documentation](https://github.com/Macrostates/macrostates-cli/blob/main/.macrostates/implementation/main.md)
+and
+[conformance mapping](https://github.com/Macrostates/macrostates-cli/blob/main/.macrostates/implementation/specification-conformance.md)
+for architecture, current adoption state, evidence, and limitations.
+
+## AI Assistance
+
+This project was developed with AI assistance.