Metadata-Version: 2.5
Name: cogniflow
Version: 0.1.22
Summary: Thin Cogniflow bootstrap launcher.
Author: Cogniflow Maintainers
License: GPL-3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# cogniflow

`cogniflow` is the public launcher for Cogniflow installation and instance lifecycle operations. A real pip installation creates `cogniflow.exe` on Windows. Invoking it without arguments starts the installed sibling Ratatui frontend; explicit commands use the scriptable Python command surface.

## Source-version boundary

The source tree is prepared as the unpublished `0.1.15` release candidate. Public `0.1.14` artifacts remain immutable. Candidate wheels require independent Supervisor acceptance before any publication.

## Local Repository Mode

The interactive frontend asks for exactly source checkout, target root, instance ID, and profile. It derives working artifact locations and forwards the equivalent explicit command:

```text
cogniflow install --instance-id local-dev \
  --installation-root /opt/cogniflow-instance \
  --cogniflow-home /home/user/.cogniflow \
  --mode local-repository --checkout-path /work/cogniflow \
  --artifact-output-root /tmp/cogniflow-artifacts \
  --external-wheelhouse-path /tmp/cogniflow-external \
  --profile urn:cf:profile:minimal
```

The launcher discovers an installed orchestrator from `cogniflow.install_orchestrators.v1`, verifies its matching console script, and crosses a versioned JSON-lines process boundary. It coordinates the existing lifecycle owners but does not implement profile selection, artifact resolution, target transactions, managed-tool provisioning, or semantic service policy itself.

PyPI Mode accepts only the bundled exact release profile, `cogniflow` at the matching release version, and `https://pypi.org/simple`. The public installation is `python -m pip install cogniflow`; local wheelhouses, private indexes, editable metadata, and source checkout injection are not accepted as public-release proof. Publication and isolated release-validation procedures are documented in `../docs/scb-17-public-release.md`.

## Read-only Hub profiles

`cogniflow registry profiles --json` lists public Hub labels, descriptions, versions and an exact snapshot pin. `cogniflow registry profile-preview --profile IRI --version VERSION --snapshot-sha256 HASH --json` reads only that immutable snapshot, never the latest pointer. Both commands also offer a readable summary without `--json`.

The Stage-0 client uses only HTTPS at `knowledge-hub-b945cd.gitpages.uni-due.de`, with 10-second network timeouts, a shrinking socket timeout within a 10-second read deadline, a 4096-byte pointer limit, and an 8 MiB raw snapshot limit. It accepts up to 1000 profiles and 1000 candidates, with up to 128 capabilities per row. Duplicate distribution/version identities are rejected even when their hashes differ. Hub JSON output uses ASCII escapes so localized labels survive Windows subprocess pipes. It sends no credentials and follows no redirects, document paths or provider metadata. Exact raw SHA-256 and the canonical content revision are checked independently. Unsafe display text, malformed data and unknown selected versions fail closed. Multiple versions of a distribution remain alternatives; no winner is assigned. All results are advisory, retain `installation_authorized=false`, and make no signature, publisher trust, host compatibility or installation approval claim. Compatibility remains `UNASSESSED`. This path does not alter the bundled release preview or installer.

## Frozen-authorized Hub install plans

`cogniflow hub-install preview --profile IRI --version HUB_VERSION --snapshot-sha256 HASH`
prints the exact public-PyPI plan; add `--json` for structured output. This is
read-only. The document SHA-256 and capabilities must match the independently
finalized embedded release. Each release-selected provider must appear exactly once
among Hub candidates with the approved distribution, version and wheel hash.
Other candidates stay advisory. A pin, self-authored lock or confirmation never
approves artifacts.

To apply, use the same profile/version/pin with `hub-install apply`, adding
`--plan-digest sha256:...`, `--instance-id ID`, `--installation-root PATH`,
`--cogniflow-home PATH`, `--artifact-output-root PATH`, and `--confirm`.
The launcher rebuilds and compares the plan immediately before the existing
public-PyPI coordinator. Normal target validation and exact-byte installer checks
are unchanged. No plan-file input, lock override, alternate index or local
wheelhouse is accepted on this path.

In the TUI, select a Hub profile, preview it, then press **p** to request a plan.
An eligible plan shows the source and exact versions/hashes; **a** opens the normal
instance and target-root form. Final confirmation shows those values and the
plan digest. Errors do not authorize installation; Enter/Esc or **b** returns to
the pinned advisory preview.

The current production gap is intentional: live minimal **1.0.1** advertises
`cf-install-services` and `cf-bootstrap-instance` **0.1.20**, while this checkout's
development profile is minimal **1.0.0**. Source checkouts do not ship
`inner-release-lock.json`. Missing embedded authority and mismatched document or
artifact identities therefore reject installation. Tests use isolated synthetic
authority only; no deployed catalog or production approval is fabricated.

## Read-only registry preview

`cogniflow registry preview --profile urn:cf:profile:minimal --json` derives the required capabilities from the bundled release catalog and calls only `registry/discover` on an installed orchestrator. Use `--orchestrator NAME` when more than one is installed. Unknown profiles fail before discovery. The call has a 45-second timeout and forwards no registry credentials or release authority.

Results include the profile, `installation_authorized=false`, and a `none`, `unique`, or `ambiguous` outcome for each capability with candidate package names, versions and hashes. Omitting `--json` prints a readable summary. Candidates are not chosen or installed; malformed, unavailable, or installation-authorizing replies fail closed.

## Lifecycle commands

`cogniflow repair` exposes inspect, preview, and apply through semantic lifecycle services. `cogniflow update` previews or applies profile transitions. `cogniflow uninstall` previews and applies authenticated instance teardown. Provider and orchestrator listing inspect distribution metadata without executing providers.

Exit codes are 0 for success, 2 for CLI errors, 3 for discovery errors, 4 for process/protocol errors, and 5 for structured provider errors. Bootstrap discovery uses installed metadata and local semantic documents because the production runtime graph and Fuseki may not yet exist.
