@grosspoetrysystems/oompf 0.2.0 → 0.3.0

package/README.md

@@ -1,15 +1,15 @@
 # oompf
 
-`oompf` publishes, inspects, searches, and installs OMP (Oh My Pi) agent
-profiles through the OOMPF index at [oompf.run](https://oompf.run).
+`oompf` publishes, inspects, searches, installs, and upgrades OMP (Oh My Pi)
+agent profiles through the OOMPF index at [oompf.run](https://oompf.run).
 
 A local profile becomes a public GitHub Gist, its metadata is registered in the
 index, and anyone can reinstall it as a native OMP profile:
 
 ```text
-oompf publish <profile>   → public Gist → indexed → https://oompf.run/p/<id>
-oompf add <url>           → installs a native OMP profile
-omp --profile <name>      → run it
+oompf publish <profile-name>  → public Gist → indexed → https://oompf.run/p/<id>
+oompf add <oompf-url>         → installs a verified native OMP profile
+omp --profile <name>          → run it
 ```
 
 The canonical profile artifact always stays at its public Gist; OOMPF persists
@@ -97,8 +97,9 @@ Nothing is registered if local validation fails.
 
 ### `oompf add <ref> [--name <name>]`
 
-Install a shared profile as a native OMP profile. The reference may be an OOMPF
-URL or id, a public Gist URL, or a bare Gist id.
+Install a shared profile as a native OMP profile. The reference must be an
+OOMPF URL or profile id. Direct Gist URLs and ids are rejected because they
+have no indexed revision or fingerprint to verify.
 
 ```bash
 oompf add https://oompf.run/p/prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d
@@ -114,13 +115,14 @@ Output: the installed `name`, the `path` written, the artifact `hash`, the
 
 Failure modes:
 
+- `unverifiable_artifact` — the reference is not an indexed OOMPF profile, or
+  the indexed profile has no pinned revision.
 - `invalid_artifact` — the fetched artifact failed structural validation.
 - `invalid_name` — the derived (or `--name`) profile name violates OMP's naming
   rules; pass an explicit valid `--name`.
 - `target_exists` — a profile with that name already has a config; OOMPF refuses
   to overwrite it.
 - `network_error` — the index or Gist source could not be reached.
-- The Gist is missing or private, or the reference is not a supported Gist/URL.
 
 ### `oompf inspect <ref>`
 
@@ -131,9 +133,10 @@ oompf inspect https://oompf.run/p/prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d
 ```
 
 An OOMPF reference is answered from the index; a Gist reference is fetched and
-validated live. Output is metadata only — models, providers, aliases, the
-structural verdict, provenance, and the install command. The canonical artifact
-content is never emitted.
+validated live for inspection only. OOMPF output includes the verified install
+command; direct Gist output does not offer an install command. The output is
+metadata only — models, providers, aliases, the structural verdict, and
+provenance. The canonical artifact content is never emitted.
 
 Failure modes: `not_found` for an unknown indexed id; `network_error` when the
 index is unreachable; Gist fetch errors when the source is missing, private, or
@@ -153,6 +156,41 @@ verdict, source, and canonical URL).
 
 Failure mode: `network_error` when the index is unreachable.
 
+### `oompf upgrade <ref> [--yes]`
+
+Review, and optionally apply, model upgrades for a profile you published. The
+reference must be an OOMPF URL or profile id; the Gist must be owned by your
+authenticated `gh` account.
+
+```bash
+oompf upgrade https://oompf.run/p/prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d
+```
+
+The plan is computed from the Gist's current head rather than the indexed
+pinned revision, printed for review, and applied only after confirmation
+(`--yes` skips the prompt). Applying patches the same Gist in place and
+re-registers the unchanged source URL, so the `/p/<id>` reference stays stable
+while its revision and fingerprint change. Successors come from a
+code-reviewed catalog; an unclassified model is reported unchanged rather than
+guessed at.
+
+Output: the `catalogRevision`, the `currentRevision` and `updatedRevision`, the
+`changes` applied per role, anything left `unchanged` with a reason, and the
+`oompfUrl`.
+
+Failure modes:
+
+- `invalid_ref` — the reference is not an OOMPF URL or profile id.
+- `unverifiable_artifact` — the indexed profile has no source Gist.
+- `unowned_gist` — the Gist belongs to another account, or `gh` is not
+  authenticated.
+- `head_changed` — the Gist moved during review; nothing is patched.
+- `invalid_artifact` / `blocking_secrets` — the upgraded YAML failed validation
+  or tripped the secret scan; nothing is patched.
+- `index_update_failed` — the Gist was patched but the index could not be
+  refreshed; re-register the unchanged source URL rather than re-running the
+  patch.
+
 ## JSON output and errors
 
 - `--json` on any command returns the same data the human output renders,

package/dist/index.d.mts

@@ -1,4 +1,46 @@
 import { Cli } from "incur";
+//#region ../../packages/core/dist/agent-runtime.d.ts
+/**
+ * Agent-runtime detection and selection.
+ *
+ * OOMPF commands ask the local `omp` binary for profile paths. That binary is
+ * one of two agent runtimes — `omp` (OMP) or `pi` (Programmable Intelligence).
+ * This module resolves which binary a command should invoke: the installed
+ * runtime, the sole installed one, or an explicit `--agent` request.
+ *
+ * It selects the *binary* only. `pi`'s profile-path layout compatibility is
+ * tracked upstream (GPS-148) and is deliberately out of scope here — the
+ * chosen command simply flows through the existing `ompCommand` seam.
+ */
+/** The agent runtimes OOMPF knows how to drive. */
+type AgentRuntime = "omp" | "pi";
+/** A resolved runtime: the binary to invoke plus which runtime it is. */
+interface AgentRuntimeSelection {
+  readonly command: string;
+  readonly runtime: AgentRuntime;
+}
+/** Options controlling {@link resolveAgentRuntime}. */
+interface AgentRuntimeOptions {
+  /**
+   * Probe seam; defaults to running `<command> --version` and treating any
+   * result as "present". Tests inject a fake so no real binary is touched.
+   */
+  readonly probe?: (command: string) => Promise<boolean>;
+  /** The runtime the caller explicitly requested via `--agent`. */
+  readonly requested?: AgentRuntime;
+}
+/**
+ * Resolve which agent-runtime binary a command should drive.
+ *
+ * Precedence:
+ * 1. `requested` set -> probe only that runtime. Present -> return it;
+ *    absent -> throw {@link AgentRuntimeUnavailableError}.
+ * 2. `requested` unset -> probe both concurrently. Both present -> `omp`;
+ *    exactly one -> that one; neither -> throw
+ *    {@link AgentRuntimeUnavailableError}.
+ */
+declare function resolveAgentRuntime(options?: AgentRuntimeOptions): Promise<AgentRuntimeSelection>;
+//#endregion
 //#region ../../packages/core/dist/omp-profile.d.ts
 /**
  * Portable OMP profile discovery and path resolution.
@@ -109,6 +151,10 @@ type CommandRunner = (input: CommandInput) => Promise<CommandResult>;
 //#region ../../packages/github/dist/gists.d.ts
 /** Minimal structural view of a `fetch` response used by this module. */
 interface GistFetchResponse {
+  /** Raw response body stream, used to cap oversized payloads pre-read. */
+  readonly body?: ReadableStream<Uint8Array> | null;
+  /** Response headers; only `content-length` is consulted. */
+  readonly headers?: Headers | Readonly<Record<string, string>>;
   readonly ok: boolean;
   readonly status: number;
   text(): Promise<string>;
@@ -118,6 +164,12 @@ type GistFetch = (url: string, init?: {
   readonly headers?: Record<string, string>;
 }) => Promise<GistFetchResponse>;
 //#endregion
+//#region src/profile-selector.d.ts
+interface ProfileSelector {
+  isInteractive(): boolean;
+  selectProfile(names: readonly string[]): Promise<string | null>;
+}
+//#endregion
 //#region src/deps.d.ts
 /** Minimal structural view of an HTTP response the API client consumes. */
 interface HttpResponse {
@@ -156,6 +208,10 @@ interface CliDeps {
   readonly httpFetch?: HttpFetch;
   /** `omp` executable name; defaults to `"omp"`. */
   readonly ompCommand?: string;
+  /** Interactive native-profile selection seam (publish). */
+  readonly profileSelector?: ProfileSelector;
+  /** Agent-runtime resolver seam (probes omp/pi when no binary is pinned). */
+  readonly resolveAgentRuntime?: typeof resolveAgentRuntime;
   /** Install-target resolver seam (add). */
   readonly resolveInstallTarget?: typeof resolveInstallTarget;
   /** Existing-profile resolver seam (publish). */

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../../packages/core/dist/omp-profile.d.ts","../../../packages/github/dist/gh.d.ts","../../../packages/github/dist/gists.d.ts","../src/deps.ts","../src/index.ts"],"mappings":";;;;;;;;;;;;;;;;;UAeiB;;WAEJ;;WAEA;;WAEA;;;UAGI;;WAEJ;;WAEA;;WAEA,UAAU;;WAEV;;;UAGI;;WAEJ;;;;;;;;;iBASW,qBAAqB,cAAc,UAAU,oBAAoB;;;;;;;;iBAQjE,qBAAqB,iBAAiB,UAAU,oBAAoB,QAAQ;;;;;;;;;iBAS5E,iBAAiB,UAAU,oBAAoB,QAAQ;;;;;;;;;;;;;;;;;;UChD9D;;WAEJ;WACA;WACA;;;UAGI;;WAEJ;;WAEA;;WAEA;;;;;;;;;;KAUD,iBAAiB,OAAO,iBAAiB,QAAQ;;;;UCG5C;WACJ;WACA;EACT,QAAQ;;;KAGA,aAAa,aAAa;WACzB,UAAU;MACjB,QAAQ;;;;UC3BG;WACN;WACA;EACT,QAAQ;;;KAIE,aACV,aACA;WACW;WACA,UAAU;WACV;MAER,QAAQ;;UAGI;;EAEf,OAAO,eAAe;;EAEtB,MAAM,cAAc,eAAe;;EAEnC,SAAS,eAAe;;EAExB,UAAU,cAAc,cAAc,eAAe;;;UAoCtC;;WAEN,0BAA0B;;WAE1B,KAAK;;WAEL;;WAEA,YAAY;;WAEZ,YAAY;;WAEZ;;WAEA,8BAA8B;;WAE9B,8BAA8B;;WAE9B,SAAS;;;;;;;;;;;;cC1EP;;iBAGG,UAAU,OAAM,UAAY,IAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../packages/core/dist/agent-runtime.d.ts","../../../packages/core/dist/omp-profile.d.ts","../../../packages/github/dist/gh.d.ts","../../../packages/github/dist/gists.d.ts","../src/profile-selector.ts","../src/deps.ts","../src/index.ts"],"mappings":";;;;;;;;;;;;;;;KAaY;;UAEK;WACJ;WACA,SAAS;;;UAGL;;;;;WAKJ,SAAS,oBAAoB;;WAE7B,YAAY;;;;;;;;;;;;iBAkBD,oBAAoB,UAAU,sBAAsB,QAAQ;;;;;;;;;;;;;;;;;;UC9BnE;;WAEJ;;WAEA;;WAEA;;;UAGI;;WAEJ;;WAEA;;WAEA,UAAU;;WAEV;;;UAGI;;WAEJ;;;;;;;;;iBAeW,qBAAqB,cAAc,UAAU,oBAAoB;;;;;;;;iBAQjE,qBAAqB,iBAAiB,UAAU,oBAAoB,QAAQ;;;;;;;;;iBAS5E,iBAAiB,UAAU,oBAAoB,QAAQ;;;;;;;;;;;;;;;;;;UCtD9D;;WAEJ;WACA;WACA;;;UAGI;;WAEJ;;WAEA;;WAEA;;;;;;;;;;KAUD,iBAAiB,OAAO,iBAAiB,QAAQ;;;;UCG5C;;WAEJ,OAAO,eAAe;;WAEtB,UAAU,UAAU,SAAS;WAC7B;WACA;EACT,QAAQ;;;KAGA,aAAa,aAAa;WACzB,UAAU;MACjB,QAAQ;;;UCnDG;EACf;EACA,cAAc,2BAA2B;;;;;UCyB1B;WACN;WACA;EACT,QAAQ;;;KAIE,aACV,aACA;WACW;WACA,UAAU;WACV;MAER,QAAQ;;UAGI;;EAEf,OAAO,eAAe;;EAEtB,MAAM,cAAc,eAAe;;EAEnC,SAAS,eAAe;;EAExB,UAAU,cAAc,cAAc,eAAe;;;UAuCtC;;WAEN,0BAA0B;;WAE1B,KAAK;;WAEL;;WAEA,YAAY;;WAEZ,YAAY;;WAEZ;;WAEA,kBAAkB;;WAElB,6BAA6B;;WAE7B,8BAA8B;;WAE9B,8BAA8B;;WAE9B,SAAS;;;;;;;;;;;;cCtFP;;iBAGG,UAAU,OAAM,UAAY,IAAA"}