instructware-tools 0.1.0__tar.gz

instructware_tools-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.so
+
+.venv/
+.uv-cache/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.tmp_iwp_e2e_tests/
+
+dist/
+build/
+*.egg-info/
+uv.lock
+
+.DS_Store

instructware_tools-0.1.0/LICENSE

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

instructware_tools-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: instructware-tools
+Version: 0.1.0
+Summary: CLI tools for InstructWare protocol linting and incremental build workflows.
+Project-URL: Homepage, https://github.com/InstructWare/iwp-tools
+Project-URL: Repository, https://github.com/InstructWare/iwp-tools
+Project-URL: Issues, https://github.com/InstructWare/iwp-tools/issues
+Author: InstructWare Maintainers
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0.1
+Description-Content-Type: text/markdown
+
+# iwp-tools
+
+`iwp-tools` is the standalone toolkit repository for InstructWare protocol workflows.
+
+It provides two CLI commands:
+
+- `iwp-lint`: schema/link/coverage quality checks
+- `iwp-build`: incremental build orchestration on top of `iwp-lint`
+
+## Install
+
+```bash
+pipx install instructware-tools
+iwp-lint --help
+iwp-build --help
+```
+
+## Local development
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright iwp_lint iwp_build test
+uv run python -m unittest iwp_lint.tests.test_regression
+uv run python -m unittest iwp_build.tests.test_e2e_suite
+uv run python -m unittest iwp_lint.tests.test_e2e_suite
+```
+
+## Build releases
+
+```bash
+uv build
+uv run pyinstaller --onefile --name iwp-lint iwp_lint/__main__.py
+uv run pyinstaller --onefile --name iwp-build iwp_build/__main__.py
+```
+
+## License
+
+This repository is licensed under MIT. See [`LICENSE`](./LICENSE).

instructware_tools-0.1.0/README.md

@@ -0,0 +1,40 @@
+# iwp-tools
+
+`iwp-tools` is the standalone toolkit repository for InstructWare protocol workflows.
+
+It provides two CLI commands:
+
+- `iwp-lint`: schema/link/coverage quality checks
+- `iwp-build`: incremental build orchestration on top of `iwp-lint`
+
+## Install
+
+```bash
+pipx install instructware-tools
+iwp-lint --help
+iwp-build --help
+```
+
+## Local development
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright iwp_lint iwp_build test
+uv run python -m unittest iwp_lint.tests.test_regression
+uv run python -m unittest iwp_build.tests.test_e2e_suite
+uv run python -m unittest iwp_lint.tests.test_e2e_suite
+```
+
+## Build releases
+
+```bash
+uv build
+uv run pyinstaller --onefile --name iwp-lint iwp_lint/__main__.py
+uv run pyinstaller --onefile --name iwp-build iwp_build/__main__.py
+```
+
+## License
+
+This repository is licensed under MIT. See [`LICENSE`](./LICENSE).

instructware_tools-0.1.0/iwp_build/README.md

@@ -0,0 +1,132 @@
+# iwp-build
+
+`iwp-build` is the orchestrator layer for IWP workflows.
+
+It provides the manual build checkpoint and reuses `iwp_lint` as the quality/diff engine.
+
+## Development Setup
+
+```bash
+uv sync --group dev
+uv run iwp-build --help
+```
+
+## Responsibilities
+
+- orchestrate workflow entrypoints (`build`, `verify`, `watch`)
+- provide a manual build checkpoint for intent diff and implementation gap output
+- call `iwp_lint` library API directly (no subprocess dependency)
+
+Non-goals:
+
+- does not re-implement lint/schema/coverage logic
+- does not replace agent runtime or code generation engine
+
+## Commands
+
+```bash
+uv run iwp-build build --config .iwp-lint.yaml
+uv run iwp-build build --config .iwp-lint.yaml --mode diff --json out/iwp-build.json --diff-json out/iwp-diff.json
+uv run iwp-build verify --config .iwp-lint.yaml --run-tests
+uv run iwp-build watch --config .iwp-lint.yaml --verify
+```
+
+Backward-compatible module entry still works:
+
+```bash
+python -m iwp_build build --config .iwp-lint.yaml
+```
+
+## Workflow
+
+1. `build`: compile `.iwc`, compute intent diff (markdown delta), then compute implementation gap (link/coverage diagnostics)
+2. agent uses the compact diff output as implementation hints and edits code
+3. `verify`: run compiled checks, full lint gate, and optional regression tests
+4. `watch` (optional local loop): incremental `.iwc` compile only; not a workflow checkpoint
+
+## Integration with iwp_lint API
+
+`iwp-build` uses these APIs from `iwp_lint/api.py`:
+
+- `snapshot_action(...)`
+- `run_quality_gate(...)`
+- `compile_context(...)`
+- `verify_compiled(...)`
+
+This design keeps one source of truth for lint and snapshot semantics.
+
+## Watch Mode (Hot Compile for `.iwc`)
+
+`iwp-build watch` is a local developer loop (optional):
+
+- starts with one full `.iwc` compile
+- polls markdown and control files
+- batches changes with debounce
+- recompiles only impacted markdown sources
+- targets `.iwc v2` dual artifacts (`.iwp/compiled/json/**` + `.iwp/compiled/md/**`)
+- can optionally verify artifacts and run tests after each cycle
+- does not generate workflow tasks or baseline checkpoints
+
+Example:
+
+```bash
+uv run iwp-build watch --config .iwp-lint.yaml --debounce-ms 600 --verify
+```
+
+## Suggested CI Usage
+
+Example:
+
+```bash
+uv run iwp-build build --config .iwp-lint.yaml --json out/iwp-build.json --diff-json out/iwp-diff.json
+# agent applies changes based on out/iwp-diff.json
+uv run iwp-build verify --config .iwp-lint.yaml --run-tests
+```
+
+Output notes:
+
+- `--json` writes the full checkpoint payload (`summary`, `compile`, `intent_diff`, `gap_report`)
+- `--diff-json` writes a compact payload for agent implementation loops (`summary`, `intent_diff`, `gap_report.diagnostics`, `gap_report.nodes`)
+
+## E2E Scenarios
+
+Build e2e tests are fixture-driven and map to agent flow checkpoints:
+
+- shared fixtures: `test/<scenario>/`
+- e2e suite entrypoint: `iwp_build/tests/test_e2e_suite.py`
+- compatibility wrapper: `iwp_build/tests/test_e2e_flow.py`
+
+Covered flows:
+
+- feature add node: build fails before link patch, then passes after `@iwp.link` update
+- feature delete node: stale link fails verify, cleanup + rebuild restores green state
+- feature modify node: impacted nodes detected in diff, link update required
+- bootstrap without baseline and without links: first build fails, patch links, second build initializes baseline
+- bootstrap first build: `--mode auto` enters `bootstrap_full` and initializes baseline
+
+Schema profile matrix:
+
+- every build e2e scenario runs both:
+  - `minimal` profile (shared test schema under `test/schema/`)
+  - `official` profile (`schema/iwp-schema.v1.json`)
+- tests rewrite fixture markdown as needed per profile to keep business intent assertions stable.
+
+Run only build e2e:
+
+```bash
+uv run python -m unittest iwp_build.tests.test_e2e_suite
+```
+
+## Migration from Legacy Commands
+
+The old task-oriented commands were removed to keep the tool surface minimal.
+
+- `iwp-build snapshot init|update|diff` -> `iwp-build build`
+- `iwp-build plan` -> `iwp-build build`
+- `iwp-build apply` -> removed (no task status workflow)
+- `iwp-build verify --id <task_id>` -> `iwp-build verify`
+
+Design change:
+
+- `build` is now the manual checkpoint for intent diff + implementation gap.
+- `watch` remains optional acceleration and does not define workflow checkpoints.

instructware_tools-0.1.0/iwp_build/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

instructware_tools-0.1.0/iwp_build/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

instructware_tools-0.1.0/iwp_build/cli.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import unittest
+from collections.abc import Mapping
+
+from iwp_build.watch import run_watch
+from iwp_lint.api import (
+    compile_context,
+    run_quality_gate,
+    snapshot_action,
+    verify_compiled,
+)
+from iwp_lint.config import load_config
+from iwp_lint.core.engine import print_console_report, run_diff, run_full
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="iwp-build", description="IWP incremental build orchestrator"
+    )
+    parser.add_argument("--config", help="Path to .iwp-lint.yaml or .json", default=None)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    build_cmd = sub.add_parser(
+        "build", help="Compile .iwc and compute incremental implementation gap"
+    )
+    build_cmd.add_argument("--config", help="Path to .iwp-lint.yaml or .json", default=None)
+    build_cmd.add_argument(
+        "--mode",
+        choices=["auto", "diff", "full"],
+        default="auto",
+        help="Build mode: auto tries diff first and falls back to full on first run",
+    )
+    build_cmd.add_argument("--json", help="Write build summary JSON to path", default=None)
+    build_cmd.add_argument(
+        "--diff-json",
+        help="Write compact diff payload for agent consumption",
+        default=None,
+    )
+    build_cmd.set_defaults(command="build")
+
+    verify_cmd = sub.add_parser("verify", help="Run compiled check + lint gate (+ tests)")
+    verify_cmd.add_argument("--config", help="Path to .iwp-lint.yaml or .json", default=None)
+    verify_cmd.add_argument("--run-tests", action="store_true", help="Run regression tests")
+    verify_cmd.set_defaults(command="verify")
+
+    watch_cmd = sub.add_parser(
+        "watch", help="Watch markdown changes and rebuild .iwc incrementally"
+    )
+    watch_cmd.add_argument("--config", help="Path to .iwp-lint.yaml or .json", default=None)
+    watch_cmd.add_argument(
+        "--debounce-ms",
+        type=int,
+        default=600,
+        help="Debounce window for change batching",
+    )
+    watch_cmd.add_argument(
+        "--poll-ms",
+        type=int,
+        default=250,
+        help="Polling interval for file change detection",
+    )
+    watch_cmd.add_argument(
+        "--verify",
+        action="store_true",
+        help="Verify compiled artifacts after each build",
+    )
+    watch_cmd.add_argument(
+        "--run-tests",
+        action="store_true",
+        help="Run regression tests after each successful build",
+    )
+    watch_cmd.add_argument(
+        "--once",
+        action="store_true",
+        help="Run one compile cycle and exit",
+    )
+    watch_cmd.set_defaults(command="watch")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    config = load_config(args.config)
+
+    if args.command == "build":
+        return _run_build(
+            config=config,
+            mode=args.mode,
+            json_path=args.json,
+            diff_json_path=args.diff_json,
+        )
+    if args.command == "verify":
+        return _run_verify(config, args.run_tests)
+    if args.command == "watch":
+        return run_watch(
+            config=config,
+            config_file=args.config,
+            debounce_ms=args.debounce_ms,
+            poll_ms=args.poll_ms,
+            verify=args.verify,
+            run_tests=args.run_tests,
+            once=args.once,
+            compile_fn=compile_context,
+            verify_fn=verify_compiled,
+        )
+    raise RuntimeError(f"unknown command: {args.command}")
+
+
+def _run_build(
+    config,
+    mode: str,
+    json_path: str | None,
+    diff_json_path: str | None = None,
+) -> int:
+    compile_result = compile_context(config)
+    build_mode = mode
+    needs_bootstrap_init = False
+    intent = {
+        "changed_files": [],
+        "changed_md_files": [],
+        "changed_code_files": [],
+        "changed_count": 0,
+        "impacted_nodes": [],
+    }
+
+    if mode in {"auto", "diff"}:
+        try:
+            intent = snapshot_action(config, "diff")
+            gap_report = run_diff(config, None, None)
+            build_mode = "diff"
+        except RuntimeError as exc:
+            if mode == "diff":
+                raise
+            if "baseline not found" not in str(exc):
+                raise
+            gap_report = run_full(config)
+            build_mode = "bootstrap_full"
+            needs_bootstrap_init = True
+    else:
+        gap_report = run_full(config)
+        build_mode = "full"
+
+    gap_error_count = int(gap_report["summary"]["error_count"])
+    baseline_bootstrapped = needs_bootstrap_init and gap_error_count == 0
+    summary = {
+        "build_mode": build_mode,
+        "baseline_bootstrapped": baseline_bootstrapped,
+        "compiled_count": int(compile_result.get("compiled_count", 0)),
+        "removed_count": int(compile_result.get("removed_count", 0)),
+        "changed_count": int(intent.get("changed_count", 0)),
+        "changed_md_count": _safe_len(intent.get("changed_md_files")),
+        "impacted_nodes_count": _safe_len(intent.get("impacted_nodes")),
+        "gap_error_count": gap_error_count,
+        "gap_warning_count": int(gap_report["summary"]["warning_count"]),
+    }
+    print(
+        "[iwp-build] build "
+        f"mode={summary['build_mode']} "
+        f"compiled={summary['compiled_count']} removed={summary['removed_count']} "
+        f"changed={summary['changed_count']} impacted_nodes={summary['impacted_nodes_count']} "
+        f"gap_errors={summary['gap_error_count']}"
+    )
+    print_console_report(gap_report)
+    full_payload = {
+        "summary": summary,
+        "compile": compile_result,
+        "intent_diff": intent,
+        "gap_report": gap_report,
+    }
+    written_json_path = _write_json(
+        json_path,
+        full_payload,
+    )
+    if written_json_path is not None:
+        print(
+            "[iwp-build] build json "
+            f"path={written_json_path} "
+            f"changed_md={summary['changed_md_count']} "
+            f"impacted_nodes={summary['impacted_nodes_count']} "
+            f"gap_errors={summary['gap_error_count']}"
+        )
+    written_diff_json_path = _write_json(
+        diff_json_path,
+        _to_compact_diff_payload(summary=summary, intent=intent, gap_report=gap_report),
+    )
+    if written_diff_json_path is not None:
+        print(
+            "[iwp-build] build diff json "
+            f"path={written_diff_json_path} "
+            f"changed_md={summary['changed_md_count']} "
+            f"impacted_nodes={summary['impacted_nodes_count']} "
+            f"gap_errors={summary['gap_error_count']}"
+        )
+
+    if gap_error_count > 0:
+        print("[iwp-build] build failed; keep previous baseline unchanged")
+        return 1
+
+    # Build completion is the manual checkpoint; only commit snapshot when gap checks pass.
+    if needs_bootstrap_init:
+        snapshot_action(config, "init")
+    else:
+        snapshot_action(config, "update")
+    return 0
+
+
+def _run_verify(config, run_tests: bool) -> int:
+    compiled = verify_compiled(config)
+    if not bool(compiled.get("ok", False)):
+        print(f"[iwp-build] verify compiled checked={compiled.get('checked_sources', 0)} ok=False")
+        return 1
+
+    gate = run_quality_gate(config)
+    print_console_report(gate["lint_report"])
+    if gate["lint_exit_code"] != 0:
+        return 1
+
+    if run_tests:
+        suite = unittest.defaultTestLoader.loadTestsFromName("iwp_lint.tests.test_regression")
+        result = unittest.TextTestRunner(stream=sys.stdout, verbosity=1).run(suite)
+        if not result.wasSuccessful():
+            return 1
+
+    print("[iwp-build] verify ok")
+    return 0
+
+
+def _safe_len(value: object) -> int:
+    return len(value) if isinstance(value, list) else 0
+
+
+def _to_compact_diff_payload(
+    *,
+    summary: dict[str, object],
+    intent: dict[str, object],
+    gap_report: dict[str, object],
+) -> dict[str, object]:
+    raw_gap_summary = gap_report.get("summary", {})
+    gap_summary: Mapping[str, object]
+    if isinstance(raw_gap_summary, Mapping):
+        gap_summary = raw_gap_summary
+    else:
+        gap_summary = {}
+    return {
+        "summary": {
+            "build_mode": summary.get("build_mode"),
+            "changed_md_count": summary.get("changed_md_count"),
+            "impacted_nodes_count": summary.get("impacted_nodes_count"),
+            "gap_error_count": summary.get("gap_error_count"),
+            "gap_warning_count": summary.get("gap_warning_count"),
+        },
+        "intent_diff": {
+            "changed_md_files": intent.get("changed_md_files", []),
+            "impacted_nodes": intent.get("impacted_nodes", []),
+        },
+        "gap_report": {
+            "mode": gap_report.get("mode"),
+            "summary": {
+                "error_count": gap_summary.get("error_count", 0),
+                "warning_count": gap_summary.get("warning_count", 0),
+                "total_nodes_in_scope": gap_summary.get("total_nodes_in_scope", 0),
+                "total_nodes_all": gap_summary.get("total_nodes_all", 0),
+                "covered_nodes": gap_summary.get("covered_nodes", 0),
+            },
+            "diagnostics": gap_report.get("diagnostics", []),
+            "nodes": gap_report.get("nodes", []),
+        },
+    }
+
+
+def _write_json(path: str | None, payload: dict[str, object]) -> str | None:
+    if not path:
+        return None
+    from pathlib import Path
+
+    out_path = Path(path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+    return out_path.as_posix()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

instructware_tools-0.1.0/iwp_build/tests/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

instructware_tools-0.1.0/iwp_build/tests/e2e/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

instructware_tools-0.1.0/iwp_build/tests/e2e/test_bootstrap_no_baseline_no_links.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import unittest
+
+from test.helpers import (
+    SCHEMA_PROFILES,
+    apply_schema_profile,
+    copy_scenario_to_workspace,
+    latest_snapshot_id,
+    read_json,
+    run_build,
+    write_architecture_markdown,
+    write_links_for_source,
+)
+
+
+class BootstrapNoBaselineNoLinksBuildE2E(unittest.TestCase):
+    def _assert_ok(self, result, label: str) -> None:
+        self.assertEqual(
+            result.returncode,
+            0,
+            msg=f"{label} failed\nstdout:\n{result.stdout}\nstderr:\n{result.stderr}",
+        )
+
+    def test_bootstrap_fail_then_patch_links_then_verify(self) -> None:
+        for profile in SCHEMA_PROFILES:
+            with self.subTest(schema_profile=profile):
+                tempdir, workspace = copy_scenario_to_workspace("bootstrap_no_baseline_no_links")
+                self.addCleanup(tempdir.cleanup)
+                config_path = workspace / ".iwp-lint.yaml"
+                out_dir = workspace / "out"
+                out_dir.mkdir(parents=True, exist_ok=True)
+                apply_schema_profile(config_path, profile)
+                write_architecture_markdown(workspace, profile, ["Alpha", "Beta"])
+
+                self.assertIsNone(latest_snapshot_id(config_path))
+                fail_result = run_build(
+                    [
+                        "build",
+                        "--config",
+                        str(config_path),
+                        "--mode",
+                        "auto",
+                        "--json",
+                        str(out_dir / "build_fail.json"),
+                    ]
+                )
+                self.assertEqual(fail_result.returncode, 1)
+                fail_payload = read_json(out_dir / "build_fail.json")
+                self.assertEqual(fail_payload["summary"]["build_mode"], "bootstrap_full")
+                self.assertFalse(fail_payload["summary"]["baseline_bootstrapped"])
+                self.assertGreater(fail_payload["summary"]["gap_error_count"], 0)
+                self.assertIsNone(latest_snapshot_id(config_path))
+
+                write_links_for_source(workspace, "architecture.md")
+                pass_result = run_build(
+                    [
+                        "build",
+                        "--config",
+                        str(config_path),
+                        "--mode",
+                        "auto",
+                        "--json",
+                        str(out_dir / "build_pass.json"),
+                    ]
+                )
+                self._assert_ok(pass_result, f"bootstrap after link patch ({profile})")
+                pass_payload = read_json(out_dir / "build_pass.json")
+                self.assertEqual(pass_payload["summary"]["build_mode"], "bootstrap_full")
+                self.assertTrue(pass_payload["summary"]["baseline_bootstrapped"])
+                self.assertEqual(pass_payload["summary"]["gap_error_count"], 0)
+                self.assertIsNotNone(latest_snapshot_id(config_path))
+                self._assert_ok(
+                    run_build(["verify", "--config", str(config_path)]),
+                    f"verify after bootstrap ({profile})",
+                )