insightfactory-cli 1.0.0__tar.gz

insightfactory_cli-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: insightfactory-ai/if_sre_github_actions/.github/workflows/if_s_insightfactory_cli.yml@main
+    secrets: inherit

insightfactory_cli-1.0.0/.github/workflows/claude.yml

@@ -0,0 +1,76 @@
+# =======================================================
+# GitHub Actions Workflow: Claude Code Assistant
+#
+# Purpose: AI-powered code review and assistance, on demand only.
+#          Triggered by mentioning @claude in a PR comment, an issue
+#          comment, or an inline PR review comment (e.g. `@claude review`).
+#          There is no automatic review on PR open.
+#
+# =======================================================
+
+name: Claude Workflow
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+# Least privilege at the workflow level; the reusable workflow requests what it
+# needs for its own jobs.
+permissions:
+  contents: read
+
+jobs:
+  claude:
+    # Author gating. The comment body is attacker-controlled and the call below
+    # inherits every secret, so restrict the trigger to people with write-ish
+    # access rather than anyone who can leave a comment.
+    if: |
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association) &&
+      contains(github.event.comment.body, '@claude')
+    uses: insightfactory-ai/if_sre_github_actions/.github/workflows/if_s_claude_review.yml@main
+    secrets: inherit
+    with:
+      # CONSTRAINT: the value below is interpolated inside a double-quoted CLI argument with no
+      # escaping. Do NOT include ASCII double-quote characters. Use single quotes or backticks
+      # if you need to quote something. Newlines are fine.
+      append_system_prompt: |
+        This repository (insightfactory-cli) is the production Python `if-cli`, published to public
+        PyPI. Read CLAUDE.md and README.md before reviewing; the rules below are the ones that get
+        violated most often.
+
+        Runtime and layout:
+        - Runtime code is stdlib-only. Flag any new runtime dependency in pyproject.toml or any
+          import outside the standard library.
+        - Keep one module per CLI command under `src/if_cli/commands/`.
+        - Do not suggest third-party HTTP, OAuth, or CLI frameworks; the codebase uses urllib and
+          argparse deliberately.
+
+        Security and auth:
+        - A profile's bearer token must never be sent outside that profile's factory origin. Flag
+          any code path that could forward a token to another host.
+        - OAuth uses authorization-code flow with PKCE and a loopback-only (`127.0.0.1`) callback.
+          The CLI is a public client with no client secret.
+        - Do not commit credentials, access tokens, refresh tokens, or client secrets in code,
+          tests, or fixtures. Fixtures must use neutral hostnames such as `factory.example`.
+
+        On-disk compatibility:
+        - Profiles and tokens must be written only through the atomic private-file helpers
+          (`write_private_file` in config.py): `0o600` files, `0o700` directories, atomic replace
+          via temp file.
+        - On-disk profile and token-cache paths, JSON shapes, and file permissions must stay
+          byte-compatible with the Node `@insightfactory-ai/if-cli` so users can switch
+          implementations without re-authenticating.
+
+        Programmatic API (breaking-change surface):
+        - These four symbols are a supported in-process surface documented in README.md:
+          `if_cli.config.load_config`, `if_cli.config.get_profile`, `if_cli.oauth.get_valid_token`,
+          `if_cli.runtime.CliError`.
+        - They must raise `CliError` on failure (never `SystemExit`), never write to stdout, never
+          launch a browser or block on interactive input, and use only bounded waits.
+        - Changing signatures, behaviour, or removing any of them requires a major version bump.
+
+        Tests:
+        - `tests/` uses isolated config dirs via `INSIGHTFACTORY_CONFIG_DIR`; never smoke-test
+          against `~/.insightfactory`.

insightfactory_cli-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: release
+
+# CD: merge to develop/main (or a v* tag) publishes to public PyPI.
+# 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`,
+# and environment `pypi` — a reusable workflow cannot be registered.
+on:
+  push:
+    branches: [develop, main]
+    tags:
+      - "v*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: insightfactory-ai/if_sre_github_actions/.github/workflows/if_s_insightfactory_cli.yml@main
+    secrets: inherit
+
+  publish:
+    name: Publish to PyPI
+    needs: ci
+    if: needs.ci.outputs.should_publish == 'true'
+    runs-on: ${{ vars.RUN_LINUX }}
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/insightfactory-cli
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist-release
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

insightfactory_cli-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+.tycache/
+*.egg-info/
+dist/
+build/
+.DS_Store

insightfactory_cli-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

insightfactory_cli-1.0.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

insightfactory_cli-1.0.0/CLAUDE.md

@@ -0,0 +1,28 @@
+# InsightFactory CLI contributor guide
+
+This repository publishes `insightfactory-cli` to public PyPI, which installs
+the `if-cli` executable. It uses Python 3.10+, uv, pytest, ruff, and ty.
+
+## Commands
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ty check
+```
+
+## Conventions
+
+- Keep one module per CLI command under `src/if_cli/commands/`.
+- Never send a profile bearer token outside that profile's factory origin.
+- OAuth uses authorization-code flow with PKCE and a loopback-only callback.
+- Store profiles and tokens through the atomic private-file helpers.
+- On-disk profile/token-store paths and JSON shapes stay compatible with the
+  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`.

insightfactory_cli-1.0.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.5
+Name: insightfactory-cli
+Version: 1.0.0
+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
+Author-email: "insightfactory.ai Support" <support@insightfactory.ai>
+Keywords: cli,insightfactory,oauth,pkce
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# insightfactory-cli
+
+Profile-based authentication CLI for the InsightFactory Interfaces API. It
+installs the `if-cli` command: browser OAuth login (authorization-code + PKCE),
+token refresh, and authenticated API calls, with profiles stored in
+`~/.insightfactory` in the same layout as the Node `@insightfactory-ai/if-cli`
+so the two implementations can share a config directory.
+
+This is the production Python CLI, published to public PyPI. Python 3.10 or
+newer is required.
+
+## Install
+
+```bash
+uv tool install insightfactory-cli   # persistent install, on PATH
+uvx insightfactory-cli profiles      # or zero-install, run-once
+uv tool upgrade insightfactory-cli   # updates
+```
+
+`uv` fetches a managed Python automatically if the machine lacks one. Fallbacks:
+
+```bash
+pipx install insightfactory-cli
+pip install insightfactory-cli
+```
+
+Develop-branch builds are published as PEP 440 `.devN` pre-releases. Install the
+bleeding edge with:
+
+```bash
+pip install --pre insightfactory-cli
+uv tool install --prerelease allow insightfactory-cli
+```
+
+PEP 440 orders `1.0.0.devN` *before* `1.0.0`, so a dependency spec of
+`insightfactory-cli>=1.0.0` does **not** match a develop-channel dev build.
+An in-process consumer that wants those builds must use a pre-release-bearing
+spec such as `insightfactory-cli>=1.0.0.dev0`, which matches both `.devN`
+builds and the final `1.0.0` release.
+
+## Usage
+
+```bash
+# Create a profile and authenticate through the browser.
+if-cli login -p example-dev --host https://factory.example
+
+# Inspect profiles and cached-token status. Statuses are colour-coded on a TTY
+# (green valid, yellow refreshable-but-expired, red missing or broken); set
+# NO_COLOR=1 to disable or FORCE_COLOR=1 to keep colour when piping.
+if-cli profiles
+if-cli profiles --json
+
+# Read a single non-secret profile value for scripting.
+if-cli config get host -p example-dev
+
+# Print a valid token, refreshing it when a refresh token is available.
+if-cli token -p example-dev
+if-cli token -p example-dev --env
+if-cli token -p example-dev --env-name INSIGHTFACTORY_ACCESS_TOKEN_DEV
+
+# Make an authenticated API request.
+if-cli api -p example-dev /api/agent-projects
+if-cli api -p example-dev -X POST -d '{"name":"example"}' /api/example
+
+# Discover API routes from the factory's OpenAPI document.
+if-cli api routes -p example-dev
+if-cli api routes -p example-dev agent-projects
+if-cli api describe -p example-dev GET /api/agent-projects/{id}
+
+# Remove the cached credential for a profile.
+if-cli logout -p example-dev
+
+# Fallback for factories where browser OAuth is not available.
+if-cli set-token -p example-dev
+
+if-cli --version
+```
+
+Profile selection uses `-p`, then `INSIGHTFACTORY_CONFIG_PROFILE`, then
+`[DEFAULT]`. Route discovery reads `{host}/swagger/v1/swagger.json` and does
+not require a login. Authenticated API requests are restricted to the selected
+factory origin so a profile token cannot be forwarded to another host. Profile
+hosts must be bare origins rather than URLs containing application path
+prefixes.
+
+Override the config directory with `INSIGHTFACTORY_CONFIG_DIR` (useful in tests
+and CI). The default is `~/.insightfactory`.
+
+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`:
+
+```bash
+MSYS_NO_PATHCONV=1 if-cli api -p example-dev /api/agent-projects
+```
+
+### Scripting against profiles
+
+`profiles --json` and `config get` are the supported machine-readable
+interfaces; the padded `profiles` columns are for humans and are not a
+contract, and neither is the layout of `~/.insightfactory/config`.
+
+`if-cli profiles --json` prints an array — one entry per configured profile, in
+file order — of `name`, `host`, and `token`:
+
+```json
+[
+  {
+    "name": "example-dev",
+    "host": "https://factory.example",
+    "token": { "status": "valid", "expires_at": 1785918336, "refreshable": true }
+  },
+  { "name": "other", "host": "https://other.factory.example", "token": { "status": "none" } }
+]
+```
+
+`token.status` is `valid`, `expired`, `none`, or `unknown`; `expires_at` and
+`refreshable` are present only when a cached token exists. `valid` means
+`if-cli token` will hand back the cached token as-is, so a token inside the
+60-second slack window that command refreshes within is reported as `expired` —
+use the raw `expires_at` if you need the literal expiry instant instead. A
+profile that cannot be resolved has a `host` of `null` (or its raw configured
+value) and a top-level `error` describing the problem, and does not stop the
+other profiles from being listed; `token.error` is set only when the token
+cache itself could not be read.
+
+`if-cli config get <key> -p <profile>` prints one newline-terminated value and
+exits non-zero if the profile cannot be resolved, or the key is not configured
+within it. A profile with no host cannot be resolved at all, so every key on it
+fails, not just `host`. A key present but empty (`client_id =`) counts as not
+configured:
+
+```bash
+curl -H "Authorization: Bearer $(if-cli token -p example-dev)" \
+  "$(if-cli config get host -p example-dev)/api/agent-projects"
+```
+
+The readable keys are `host`, `audience`, `callback_port`, `client_id`, and
+`organization` — all non-secret, and resolved the same way the CLI itself
+resolves them, so `audience` and `callback_port` return their defaults when the
+profile omits them. Tokens are deliberately not readable this way; use
+`if-cli token`.
+
+## Programmatic API
+
+`insightfactory-cli` may be imported in-process as a library to resolve a
+profile to a factory host and a fresh access token. These four symbols are a
+supported programmatic surface for in-process consumers:
+
+- `if_cli.config.load_config`
+- `if_cli.config.get_profile`
+- `if_cli.oauth.get_valid_token`
+- `if_cli.runtime.CliError`
+
+They raise `CliError` on failure (never `SystemExit` or `sys.exit`), never
+write to stdout, never launch a browser or block on interactive input, and use
+only bounded waits. Changing or removing any of them is a breaking change and
+requires a major version bump.
+
+## How authentication works
+
+- Profiles are stored in `~/.insightfactory/config`, one per customer/environment.
+- The profile file is managed by the CLI and is regenerated on updates; comments
+  and empty sections are not preserved.
+- Tokens are cached by host in `~/.insightfactory/token-cache.json` with file
+  mode `0600`.
+- The configuration directory is `0700`; configuration and cache updates are
+  atomic.
+- Remote factory, authorization, and token endpoints must use HTTPS. HTTP is
+  accepted only for loopback development.
+- Login discovers OAuth metadata from
+  `{host}/.well-known/oauth-authorization-server`.
+- Authorization uses PKCE through the factory `/authorize` proxy with a
+  loopback-only (`127.0.0.1`) callback. The CLI is a public OAuth client: the
+  client ID is read from the factory's discovery document at runtime (no client
+  secret).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ty check
+```
+
+Smoke-test against a throwaway config directory, never `~/.insightfactory`:
+
+```bash
+uv run if-cli --help
+uv run if-cli --version
+INSIGHTFACTORY_CONFIG_DIR=$(mktemp -d) uv run if-cli profiles
+```
+
+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
+[`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
+`.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.
+
+A one-time trusted-publisher registration is required on the PyPI project for
+that triple. The publish job downloads the `dist-release` artifact staged by
+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 |
+
+`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
+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.
+
+## Differences from the Node CLI
+
+Behaviour matches `@insightfactory-ai/if-cli` except where the platforms
+genuinely diverge:
+
+- **Unknown-option wording** is aligned (`Unknown option '--flag'`). Other
+  argparse messages (for example a missing option value) still differ from
+  Node's `util.parseArgs`.
+- **Expiry timestamps** in human-readable output use the C-locale `%c` format
+  rather than JavaScript `Date#toLocaleString()`.
+- **`--version`** reads the installed package metadata (`1.0.0` and later)
+  rather than an npm `package.json`.
+
+On-disk profile and token-cache paths, JSON shapes, and file permissions stay
+compatible with the Node CLI, so you can switch implementations without
+re-authenticating.