insightfactory-cli 1.0.1.dev5__tar.gz → 1.0.1.dev9__tar.gz

{insightfactory_cli-1.0.1.dev5 → insightfactory_cli-1.0.1.dev9}/.github/workflows/release.yml

@@ -1,6 +1,8 @@
 name: release
 
-# CD: merge to develop/main (or a v* tag) publishes to public PyPI.
+# CD: a push to develop publishes a `.dev<run_number>` pre-release; a `v*` tag
+# publishes the release. A merge to main runs CI and publishes nothing -- see
+# if_s_insightfactory_cli.yml for why releasing is a deliberate tag push.
 # Verify + build live in insightfactory-ai/if_sre_github_actions
 # (if_s_insightfactory_cli.yml). The publish job stays here because PyPI
 # Trusted Publishing is registered for this repository, workflow `release.yml`,

{insightfactory_cli-1.0.1.dev5 → insightfactory_cli-1.0.1.dev9}/CLAUDE.md

@@ -9,6 +9,7 @@ the `if-cli` executable. It uses Python 3.10+, uv, pytest, ruff, and ty.
 uv sync
 uv run pytest
 uv run ruff check .
+uv run ruff format --check .
 uv run ty check
 ```
 
@@ -22,7 +23,11 @@ uv run ty check
   Node CLI (`~/.insightfactory`, `INSIGHTFACTORY_CONFIG_DIR` override).
 - Do not commit credentials, access tokens, refresh tokens, or client secrets.
 - Test fixtures use only neutral hostnames (`factory.example`).
-- Do not publish to PyPI or create release tags from a developer machine;
-  merges to `develop` / `main` (and optional `v*` tags) publish via the
-  reusable workflow in `if_sre_github_actions` plus the OIDC job in
-  `.github/workflows/release.yml`.
+- Do not publish to PyPI from a developer machine. Publishing happens in CI: the
+  reusable workflow in `if_sre_github_actions` builds and stages, and the OIDC job
+  in `.github/workflows/release.yml` uploads.
+- **A release is a pushed `v*` tag, not a merge.** Merging to `main` runs CI and
+  publishes nothing; pushing `v<version>` publishes that version, and the tag must
+  match `pyproject.toml`. Pushing `develop` publishes a `.dev{run_number}`
+  pre-release. Creating the release tag is a deliberate human act — do not create
+  or push one unless asked to cut a release.

{insightfactory_cli-1.0.1.dev5 → insightfactory_cli-1.0.1.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: insightfactory-cli
-Version: 1.0.1.dev5
+Version: 1.0.1.dev9
 Summary: Profile-based authentication CLI for the InsightFactory Interfaces API
 Project-URL: Homepage, https://github.com/insightfactory-ai/insightfactory-cli
 Project-URL: Repository, https://github.com/insightfactory-ai/insightfactory-cli
@@ -102,6 +102,12 @@ prefixes.
 Override the config directory with `INSIGHTFACTORY_CONFIG_DIR` (useful in tests
 and CI). The default is `~/.insightfactory`.
 
+The request method goes in `-X`; `if-cli api` takes exactly one positional
+argument and reads it as the path. A `curl`-shaped `if-cli api GET /api/schedules`
+therefore parses `GET` as the path — write `if-cli api -X GET /api/schedules`
+instead. The CLI names the misplaced verb rather than reporting a problem with
+`/api/schedules`.
+
 On Git Bash (MSYS2) on Windows, path conversion rewrites a leading-slash
 argument such as `/api/agent-projects` into a Windows path. Prefix the command
 with `MSYS_NO_PATHCONV=1`:
@@ -212,12 +218,16 @@ Python 3.10 or newer is required. Runtime code is stdlib-only.
 
 ## Release
 
-Publishing is automatic from GitHub Actions on merge. Verify and build live in
-the reusable workflow
+**A release is cut by pushing a tag, not by merging.** Merging to `main` runs CI and
+publishes nothing.
+
+```bash
+git tag v1.0.1 && git push origin v1.0.1
+```
+
+Verify and build live in the reusable workflow
 [`if_s_insightfactory_cli.yml`](https://github.com/insightfactory-ai/if_sre_github_actions/blob/main/.github/workflows/if_s_insightfactory_cli.yml)
-in `insightfactory-ai/if_sre_github_actions`
-([PR #300](https://github.com/insightfactory-ai/if_sre_github_actions/pull/300)
-must merge before these stubs go green). This repository's
+in `insightfactory-ai/if_sre_github_actions`. This repository's
 `.github/workflows/release.yml` keeps only the OIDC publish job, because PyPI
 Trusted Publishing is registered for **this** repo, workflow `release.yml`, and
 environment `pypi` — a reusable workflow cannot be registered.
@@ -228,24 +238,38 @@ the reusable workflow and uploads it with `pypa/gh-action-pypi-publish`.
 
 | Trigger | Published version | PyPI role |
 |---|---|---|
-| Push / merge to `develop` | `1.0.0.dev{N}` | pre-release (`pip install --pre`) |
-| Push / merge to `main` | `1.0.0` (the version in `pyproject.toml`) | latest |
-| Push of a `v*` tag | same as `main` | retry / explicit cut of that version |
+| Push / merge to `develop` | `1.0.1.dev{N}` | pre-release (`pip install --pre`) |
+| Push of a `v*` tag | the version in `pyproject.toml`, which the tag must match | latest |
+| Merge to `main` | nothing — CI only | — |
 
 `N` is `github.run_number` of the reusable workflow: a per-workflow integer
 that goes up on every run and stays the same across re-runs of that run (so a
 failed publish can be retried under the same version). It does not depend on
-git history or clone depth. After a successful `main` publish, bump `version`
-in `pyproject.toml` on `develop` so later `.devN` builds sort *after* what just
-landed; PEP 440 puts `1.0.0.devN` before `1.0.0`. Because of that ordering, a
+git history or clone depth. After a successful release, bump `version` in
+`pyproject.toml` on `develop` so later `.devN` builds sort *after* what just
+landed; PEP 440 puts `1.0.1.devN` before `1.0.1`. Because of that ordering, a
 dependency spec of `insightfactory-cli>=1.0.0` does not match develop-channel
 `.devN` builds; an in-process consumer that wants them must specify a
 pre-release-bearing spec such as `insightfactory-cli>=1.0.0.dev0` (which also
 matches the final `1.0.0` release).
 
-A version that is already on PyPI is skipped rather than failing, so a second
-push to `main` (or a `v*` tag for the same version) is a no-op. A `v*` tag
-whose name does not match `pyproject.toml` fails before publishing.
+A `v*` tag whose name does not match `pyproject.toml` fails before publishing.
+
+The two channels treat an already-published version differently, on purpose:
+
+- **Release channel (a tag):** publishing fails, naming the fix. A tag is a request to
+  release that version; if it cannot be honoured, the run must say so rather than report
+  success having published nothing. (git also refuses to push a tag that already exists,
+  so this is hard to reach.)
+- **Dev channel (`develop`):** publishing is skipped quietly. `.dev{N}` uses
+  `github.run_number`, which is stable across re-runs of one run, so an already-present
+  version there can only mean a re-run of a run that already published — real idempotency,
+  not a swallowed mistake.
+
+This split is why releasing moved off `main`. While a merge was the trigger, an
+already-published version *had* to be tolerated as a no-op for merges to stay green — so a
+merge that released nothing looked exactly like one that released, and a forgotten version
+bump shipped nothing silently.
 
 ## Differences from the Node CLI
 

{insightfactory_cli-1.0.1.dev5 → insightfactory_cli-1.0.1.dev9}/README.md

@@ -86,6 +86,12 @@ prefixes.
 Override the config directory with `INSIGHTFACTORY_CONFIG_DIR` (useful in tests
 and CI). The default is `~/.insightfactory`.
 
+The request method goes in `-X`; `if-cli api` takes exactly one positional
+argument and reads it as the path. A `curl`-shaped `if-cli api GET /api/schedules`
+therefore parses `GET` as the path — write `if-cli api -X GET /api/schedules`
+instead. The CLI names the misplaced verb rather than reporting a problem with
+`/api/schedules`.
+
 On Git Bash (MSYS2) on Windows, path conversion rewrites a leading-slash
 argument such as `/api/agent-projects` into a Windows path. Prefix the command
 with `MSYS_NO_PATHCONV=1`:
@@ -196,12 +202,16 @@ Python 3.10 or newer is required. Runtime code is stdlib-only.
 
 ## Release
 
-Publishing is automatic from GitHub Actions on merge. Verify and build live in
-the reusable workflow
+**A release is cut by pushing a tag, not by merging.** Merging to `main` runs CI and
+publishes nothing.
+
+```bash
+git tag v1.0.1 && git push origin v1.0.1
+```
+
+Verify and build live in the reusable workflow
 [`if_s_insightfactory_cli.yml`](https://github.com/insightfactory-ai/if_sre_github_actions/blob/main/.github/workflows/if_s_insightfactory_cli.yml)
-in `insightfactory-ai/if_sre_github_actions`
-([PR #300](https://github.com/insightfactory-ai/if_sre_github_actions/pull/300)
-must merge before these stubs go green). This repository's
+in `insightfactory-ai/if_sre_github_actions`. This repository's
 `.github/workflows/release.yml` keeps only the OIDC publish job, because PyPI
 Trusted Publishing is registered for **this** repo, workflow `release.yml`, and
 environment `pypi` — a reusable workflow cannot be registered.
@@ -212,24 +222,38 @@ the reusable workflow and uploads it with `pypa/gh-action-pypi-publish`.
 
 | Trigger | Published version | PyPI role |
 |---|---|---|
-| Push / merge to `develop` | `1.0.0.dev{N}` | pre-release (`pip install --pre`) |
-| Push / merge to `main` | `1.0.0` (the version in `pyproject.toml`) | latest |
-| Push of a `v*` tag | same as `main` | retry / explicit cut of that version |
+| Push / merge to `develop` | `1.0.1.dev{N}` | pre-release (`pip install --pre`) |
+| Push of a `v*` tag | the version in `pyproject.toml`, which the tag must match | latest |
+| Merge to `main` | nothing — CI only | — |
 
 `N` is `github.run_number` of the reusable workflow: a per-workflow integer
 that goes up on every run and stays the same across re-runs of that run (so a
 failed publish can be retried under the same version). It does not depend on
-git history or clone depth. After a successful `main` publish, bump `version`
-in `pyproject.toml` on `develop` so later `.devN` builds sort *after* what just
-landed; PEP 440 puts `1.0.0.devN` before `1.0.0`. Because of that ordering, a
+git history or clone depth. After a successful release, bump `version` in
+`pyproject.toml` on `develop` so later `.devN` builds sort *after* what just
+landed; PEP 440 puts `1.0.1.devN` before `1.0.1`. Because of that ordering, a
 dependency spec of `insightfactory-cli>=1.0.0` does not match develop-channel
 `.devN` builds; an in-process consumer that wants them must specify a
 pre-release-bearing spec such as `insightfactory-cli>=1.0.0.dev0` (which also
 matches the final `1.0.0` release).
 
-A version that is already on PyPI is skipped rather than failing, so a second
-push to `main` (or a `v*` tag for the same version) is a no-op. A `v*` tag
-whose name does not match `pyproject.toml` fails before publishing.
+A `v*` tag whose name does not match `pyproject.toml` fails before publishing.
+
+The two channels treat an already-published version differently, on purpose:
+
+- **Release channel (a tag):** publishing fails, naming the fix. A tag is a request to
+  release that version; if it cannot be honoured, the run must say so rather than report
+  success having published nothing. (git also refuses to push a tag that already exists,
+  so this is hard to reach.)
+- **Dev channel (`develop`):** publishing is skipped quietly. `.dev{N}` uses
+  `github.run_number`, which is stable across re-runs of one run, so an already-present
+  version there can only mean a re-run of a run that already published — real idempotency,
+  not a swallowed mistake.
+
+This split is why releasing moved off `main`. While a merge was the trigger, an
+already-published version *had* to be tolerated as a no-op for merges to stay green — so a
+merge that released nothing looked exactly like one that released, and a forgotten version
+bump shipped nothing silently.
 
 ## Differences from the Node CLI
 

{insightfactory_cli-1.0.1.dev5 → insightfactory_cli-1.0.1.dev9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "insightfactory-cli"
-version = "1.0.1.dev5"
+version = "1.0.1.dev9"
 description = "Profile-based authentication CLI for the InsightFactory Interfaces API"
 readme = "README.md"
 requires-python = ">=3.10"

{insightfactory_cli-1.0.1.dev5 → insightfactory_cli-1.0.1.dev9}/src/if_cli/commands/api.py

@@ -61,6 +61,27 @@ def describe_route(document: dict[str, Any], method: str, path: str) -> dict[str
     return operation if isinstance(operation, dict) else None
 
 
+def _is_absolute_http_url(api_path: str) -> bool:
+    parsed = parse_url(api_path)
+    return parsed.scheme in {"http", "https"} and bool(parsed.hostname)
+
+
+def _die_on_misplaced_http_method(api_path: str, positionals: list[str]) -> None:
+    """Explain a `curl`-shaped `if-cli api GET /path`, where the verb is read as the path.
+
+    Recognition spans every verb a user might reach for, not just the ones -X accepts:
+    naming the misplaced verb is more useful than a path error even for TRACE, which
+    -X then rejects on its own terms.
+    """
+    method = api_path.lower()
+    if method not in HTTP_METHODS:
+        return
+    targets = [value for value in positionals[1:] if value.startswith("/") or _is_absolute_http_url(value)]
+    target = targets[0] if targets else "/api/path"
+    suggestion = f"if-cli api -X {method.upper()} {target}"
+    die(f"'{api_path}' looks like an HTTP method, not a path — did you mean: {suggestion} ?")
+
+
 def _die_on_msys_mangled_path(api_path: str) -> None:
     if not WINDOWS_DRIVE_PATH.search(api_path):
         return
@@ -73,11 +94,6 @@ def _die_on_msys_mangled_path(api_path: str) -> None:
     )
 
 
-def _is_absolute_http_url(api_path: str) -> bool:
-    parsed = parse_url(api_path)
-    return parsed.scheme in {"http", "https"} and bool(parsed.hostname)
-
-
 def resolve_api_url(host: str, api_path: str) -> ParseResult:
     if not api_path.startswith("/") and not _is_absolute_http_url(api_path):
         _die_on_msys_mangled_path(api_path)
@@ -145,6 +161,7 @@ def api_command(argv: list[str]) -> None:
     api_path = positionals[0] if positionals else None
     if not api_path:
         die(API_USAGE)
+    _die_on_misplaced_http_method(api_path, positionals)
 
     if values["method"] is not None:
         method = values["method"].upper()

{insightfactory_cli-1.0.1.dev5 → insightfactory_cli-1.0.1.dev9}/tests/test_api.py

@@ -37,6 +37,46 @@ def test_api_rejects_unsupported_request_methods_with_a_cli_error():
     assert "unsupported request method 'TRACE'" in result.stderr
 
 
+def test_api_names_a_misplaced_http_method_instead_of_blaming_the_path():
+    result = run_cli(["api", "GET", "/api/schedules"])
+    assert result.returncode == 1
+    assert "'GET' looks like an HTTP method, not a path" in result.stderr
+    assert "did you mean: if-cli api -X GET /api/schedules ?" in result.stderr
+    assert "API path must begin with" not in result.stderr
+
+
+def test_api_detects_a_misplaced_http_method_in_any_case_and_position():
+    lowercase = run_cli(["api", "put", "/api/orchestration/run"])
+    assert lowercase.returncode == 1
+    assert "'put' looks like an HTTP method, not a path" in lowercase.stderr
+    assert "did you mean: if-cli api -X PUT /api/orchestration/run ?" in lowercase.stderr
+
+    before_profile = run_cli(["api", "DELETE", "/api/schedules/1", "-p", "example-dev"])
+    assert before_profile.returncode == 1
+    assert "did you mean: if-cli api -X DELETE /api/schedules/1 ?" in before_profile.stderr
+
+
+def test_api_keeps_a_same_origin_absolute_url_in_the_correction():
+    result = run_cli(["api", "GET", "https://factory.example/api/schedules"])
+    assert result.returncode == 1
+    assert "did you mean: if-cli api -X GET https://factory.example/api/schedules ?" in result.stderr
+
+
+def test_api_names_a_misplaced_verb_that_x_would_not_accept():
+    result = run_cli(["api", "TRACE", "/api/schedules"])
+    assert result.returncode == 1
+    assert "'TRACE' looks like an HTTP method, not a path" in result.stderr
+    assert "did you mean: if-cli api -X TRACE /api/schedules ?" in result.stderr
+    assert "API path must begin with" not in result.stderr
+
+
+def test_api_suggests_a_placeholder_path_when_only_a_method_was_supplied():
+    result = run_cli(["api", "POST"])
+    assert result.returncode == 1
+    assert "'POST' looks like an HTTP method, not a path" in result.stderr
+    assert "did you mean: if-cli api -X POST /api/path ?" in result.stderr
+
+
 def test_discovers_and_sorts_all_openapi_operations():
     assert discover_routes(OPENAPI) == [
         "DELETE  /api/agent-projects/{id}  Delete an agent project",