workstate-bootstrap 0.5.2__py3-none-any.whl

workstate_bootstrap-0.5.2.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: workstate-bootstrap
+Version: 0.5.2
+Summary: Bootstrap CLI that hoists the shared workstate-system surface into consumer repos.
+Project-URL: Homepage, https://github.com/darce/workstate
+Project-URL: Source, https://github.com/darce/workstate/tree/main/packages/workstate-bootstrap
+Project-URL: Documentation, https://github.com/darce/workstate/blob/main/docs/CONSUMER.md
+Project-URL: Issues, https://github.com/darce/workstate/issues
+Author: darce
+License: Proprietary
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: workstate-protocol<0.2.0,>=0.1.4
+Provides-Extra: dev
+Requires-Dist: mcp-workstate-handoff; (python_version >= '3.12') and extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# workstate-bootstrap
+
+Pip-installable CLI that hoists the shared workstate-system surface
+(typed protocol, two MCP servers, hooks, skills, generated agent
+workflows) into consumer repositories. Lives inside
+[`darce/workstate`](https://github.com/darce/workstate).
+
+Consumers run `workstate-bootstrap install --target <path>` once; it
+clones the monorepo, materializes the overlay, and registers both
+managed MCP servers (`mcp-workstate-handoff`, `mcp-workstate-orchestrator`)
+across `.mcp.json`, `.vscode/mcp.json`, and `.codex/config.toml`. No
+hand-edits required.
+
+## Install
+
+### From PyPI (recommended)
+
+```bash
+uvx --from workstate-bootstrap workstate-bootstrap install --target /path/to/your/repo
+# or, persistent:
+uv tool install workstate-bootstrap
+```
+
+### From the monorepo source tree (development)
+
+```bash
+cd packages/workstate-bootstrap
+python -m pip install -e ".[dev]"
+```
+
+### Direct from git (private-repo phase, before PyPI release)
+
+One-shot (no install — fetches each invocation):
+
+```bash
+uvx --from "git+https://github.com/darce/workstate@workstate-bootstrap-v0.2.1#subdirectory=packages/workstate-bootstrap" \
+    workstate-bootstrap install \
+    --target /path/to/your/repo
+```
+
+Persistent (recommended once you start running `status` / `doctor`
+regularly — installs `workstate-bootstrap` onto `$PATH`):
+
+```bash
+uv tool install "git+https://github.com/darce/workstate@workstate-bootstrap-v0.2.1#subdirectory=packages/workstate-bootstrap"
+# then:
+workstate-bootstrap status --target /path/to/your/repo
+workstate-bootstrap doctor --target /path/to/your/repo
+# upgrade later:
+uv tool upgrade workstate-bootstrap
+```
+
+> **Hardlink warning on first install?** If you see
+> `Failed to hardlink files; falling back to full copy`, your `uv`
+> cache and tool dir live on different filesystems. The install still
+> succeeds; silence the warning with `export UV_LINK_MODE=copy` in
+> your shell profile.
+
+## Subcommands
+
+```text
+workstate-bootstrap install --target <path> [--remote-ref <tag>] [--mcp-servers <default|path>] [--no-mcp-servers]
+workstate-bootstrap update  --target <path> --remote-ref <tag>
+workstate-bootstrap status  --target <path>
+workstate-bootstrap doctor  --target <path> [--mcp-servers <default|path>]
+workstate-bootstrap repair  --target <path> [--force-dirty] [--mcp-servers <default|path>]
+```
+
+- `install`: Clone the monorepo, materialize SHARED + GENERATED
+  surfaces, write the three MCP-config files, run `init-state` to
+  provision `<target>/.task-state/handoff.db` (skipped under
+  `--no-mcp-servers`), set `core.hooksPath`, and write the overlay
+  manifest.
+- `update`: Re-run install at a new `--remote-ref`; refresh GENERATED
+  surfaces and, optionally, configs.
+- `status`: Print a summary of the installed overlay manifest. When
+  the install registered MCP servers, also reports the resolved
+  `state_dir` / `db_path` / `exports_dir` / `schema_version` via
+  `init-state --check`.
+- `doctor`: Detect drift in SHARED, GENERATED, config, and
+  initialized-state surfaces. Flags missing `.task-state/handoff.db`
+  as `state_drift` only when the manifest recorded `.mcp.json`. Exit
+  `1` when drift exists.
+- `repair`: Restore drifted surfaces flagged by `doctor`.
+
+See [`docs/CONSUMER.md`](https://github.com/darce/workstate/blob/main/docs/CONSUMER.md)
+for the consumer-facing walkthrough (upgrade, drift handling, skill
+overrides, the `current_task_auto_regen` migration note).
+
+## Surfaces written by `install`
+
+The canonical source of truth for bootstrap-managed surfaces is the
+installer implementation in
+`src/workstate_bootstrap/install.py` (`SHARED_SURFACES` and
+`GENERATED_SURFACES`). Keep this table aligned with those constants.
+
+| Surface                              | Source     | Layer       |
+| ------------------------------------ | ---------- | ----------- |
+| `scripts/hooks/`                     | shared     | symlink     |
+| `.github/hooks/`                     | shared     | symlink     |
+| `docs/agentic/contracts/`            | shared     | symlink     |
+| `docs/agentic/rules/`                | shared     | symlink     |
+| `Makefile.d/` non-excluded children  | shared     | carved dir  |
+| `scripts/workstate/` non-excluded children | shared | carved dir  |
+| `.github/prompts/`                   | generated  | real dir    |
+| `.agentic/generated/plugins/workstate-system/base/` | generated | real dir |
+| `.agentic/generated/plugins/workstate-system/effective/` | generated | real dir |
+| `.mcp.json`                          | generated  | real file   |
+| `.vscode/mcp.json`                   | generated  | real file   |
+| `.codex/config.toml`                 | generated  | real file   |
+| `core.hooksPath` git config          | generated  | git config  |
+| `.task-state/handoff.db`             | runtime    | sqlite      |
+| `.task-state/exports/`               | runtime    | dir         |
+| `.agentic/remote/`                   | bootstrap  | git clone   |
+| `.workstate-bootstrap.json`              | bootstrap  | manifest    |
+
+`.task-state/` is provisioned by the handoff server's `init-state`
+subcommand at install time and is gitignored — each fresh checkout
+regenerates it through `workstate-bootstrap install`.
+
+## Defaults
+
+- `--profile` defaults to `all`, which materializes the full surface
+  set: generated Copilot prompts, Claude/Codex plugin trees, shared
+  overlay surfaces, and the lifecycle hoist
+  (`Makefile.d/lifecycle.mk` plus the sentinel-bracketed `-include`
+  block in the consumer `Makefile`). Pass `--profile minimal` for a
+  clone-only install with no surfaces, or `--profile lifecycle` for
+  just the lifecycle runner and Makefile fragment. The active profile
+  is recorded in `.workstate-bootstrap.json` under `"profile"`.
+- `--remote-url` defaults to `git@github.com:darce/workstate.git`.
+- `--remote-ref` defaults to `main` (override with a release tag like `v0.1.0`).
+- `--mcp-servers` defaults to the built-in managed map registering
+  `mcp-workstate-handoff` and `mcp-workstate-orchestrator` via `uvx` with
+  `--workspace-root . serve-stdio`, so Codex, VS Code, and Claude
+  clients start real MCP stdio servers from the generated config.
+  Pass a JSON file path to override; pass `--no-mcp-servers` to skip
+  the three config writers entirely.
+- Plugin overrides are auto-discovered at
+  `workstate-overrides/workstate-system/` when that root contains an
+  `overrides.yaml` manifest. Use `--plugin-overrides <path>` on
+  `install`, `update`, `doctor`, or `repair` for a non-default root;
+  bootstrap records that path so later update/doctor/repair runs reuse
+  it. Override-aware installs generate effective plugin trees under
+  `.agentic/generated/plugins/workstate-system/effective/{claude,codex}`
+  and point marketplace pins at those generated trees.
+- `install` and `update` preserve plugin override files by default.
+  `--reset-overrides` is the explicit destructive path; it removes only
+  the resolved override root, refuses dirty git worktrees unless
+  `--backup` is supplied, and archives backups under
+  `.agentic/override-backups/<timestamp>/` before removal.
+
+## Development
+
+Tests live under `tests/`. From the monorepo root:
+
+```bash
+cd packages/workstate-bootstrap
+PYTHONPATH=.:src:../workstate-protocol/src pytest tests -q
+```

workstate_bootstrap-0.5.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+workstate_bootstrap/__init__.py,sha256=9vqpnSnUGUp2oNbR9anRXDkls9RaPweTh1wCDfR1nYM,184
+workstate_bootstrap/__main__.py,sha256=CcBfLrBHSgbnHsPRG2D26lyI7JNFiM0S0X9zgEJ_lIk,115
+workstate_bootstrap/cli.py,sha256=j3-VKdXVz8hHjzzIMMHF7UuutKAIlgxAEeAjlY3Wi3I,21604
+workstate_bootstrap/install.py,sha256=tED6kqshYlUVxitLufFDM05Hc9Q-LNRjAao8SQpwQ3U,78666
+workstate_bootstrap/mcp_sync.py,sha256=YCFAUnDMFCf4WnO711uhjvGvN8xYa9kJBCgMJxm4ubQ,10154
+workstate_bootstrap/subcommands.py,sha256=ruSXaPwfZlBLPI1rr-H3noCbiIecc4E9DDsmzED1OC0,48737
+workstate_bootstrap-0.5.2.dist-info/METADATA,sha256=3vH3OYMZLuxzBJx7Pczmt-K29LrOTBOlfXZ6kL8XzK8,8080
+workstate_bootstrap-0.5.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+workstate_bootstrap-0.5.2.dist-info/entry_points.txt,sha256=fy0phQVlduwJKn0pxDw_L8EGpKx7G20hA0kdcrOxLuI,69
+workstate_bootstrap-0.5.2.dist-info/RECORD,,

workstate_bootstrap-0.5.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

workstate_bootstrap-0.5.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+workstate-bootstrap = workstate_bootstrap.cli:main