@grosspoetrysystems/oompf 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,171 @@
+# oompf
+
+`oompf` publishes, inspects, searches, and installs 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
+```
+
+The canonical profile artifact always stays at its public Gist; OOMPF persists
+and serves **metadata only**.
+
+## Requirements
+
+- **Node >= 22 or Bun.** The CLI uses `Promise.withResolvers`, which requires
+  Node 22+ (or any Bun release).
+- **GitHub CLI (`gh`), authenticated** — required for `publish`, which creates a
+  public Gist with your `gh` account. Verify with `gh auth status`; run
+  `gh auth login` first if needed.
+- **OMP CLI (`omp`) on `PATH`** — required for `publish` (resolves the local
+  profile's config path) and `add` (resolves the install directory). OOMPF asks
+  OMP where a profile lives rather than hardcoding a home path. `omp` is itself
+  a Bun program.
+
+## Install
+
+```bash
+bunx @grosspoetrysystems/oompf@latest --help
+```
+
+Or keep it on `PATH`:
+
+```bash
+npm install -g @grosspoetrysystems/oompf
+```
+
+The package is scoped; the binary is plain `oompf`. Examples below use the
+binary name.
+
+Working in a clone of the repository? Run it from source with
+`bun apps/cli/src/index.ts <command>`.
+
+## Commands
+
+Every command prints human-readable output by default and structured JSON with
+`--json`. On failure, every command exits non-zero and prints a stable error
+envelope: a machine-readable `code`, a human `message`, and optional
+value-free `details`.
+
+All commands target `https://oompf.run` by default. Set `OOMPF_BASE_URL` to point
+elsewhere, for example at a local instance:
+
+```bash
+OOMPF_BASE_URL=http://localhost:4321 oompf search anthropic
+```
+
+### `oompf publish [profile]`
+
+Resolve a local OMP profile (pass the name, or omit it when exactly one profile
+is unambiguous), validate and secret-scan its `config.yml`, create a public
+one-file Gist, and register its metadata with the index.
+
+```bash
+oompf publish work
+```
+
+Output: the `githubUrl`, the canonical `oompfUrl` (`https://oompf.run/p/<id>`),
+a copyable `addCommand`, the artifact `hash`, the structural verdict, and any
+warnings.
+
+Failure modes:
+
+- `no_profile` — no OMP profiles were found; pass an explicit name.
+- `ambiguous_profile` — more than one profile exists; pass the one to publish.
+- `missing_config` — the profile has no `config.yml` / `config.yaml`.
+- `invalid_artifact` — the profile failed structural validation.
+- `blocking_secrets` — high-confidence secrets were detected in the config;
+  nothing is published. Remove them and retry.
+- GitHub authentication or Gist-creation failure (e.g. `gh` not installed or
+  not authenticated), or registration failure against the index
+  (`network_error`, or the server's own code such as `validation_failed`).
+
+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.
+
+```bash
+oompf add https://oompf.run/p/prof_1b7c9e0a4d2f3a5b6c8d9e0f1a2b3c4d
+```
+
+The canonical YAML is fetched and re-validated before anything is written. The
+local name defaults to `<owner>-<profile>` and overrides with `--name`. The
+install directory is resolved by asking OMP itself. An existing config is
+refused outright — there is no overwrite and no `--force`.
+
+Output: the installed `name`, the `path` written, the artifact `hash`, the
+`command` to run it, and any warnings.
+
+Failure modes:
+
+- `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>`
+
+Show a shared profile's metadata without installing it.
+
+```bash
+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.
+
+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
+unsupported.
+
+### `oompf search [query]`
+
+Free-text search over the index. Omitting the query lists all indexed profiles.
+
+```bash
+oompf search anthropic
+```
+
+Output: the normalized `query`, the result `count`, and one compact metadata-only
+record per match (id, name, owner, models, providers, revision, structural
+verdict, source, and canonical URL).
+
+Failure mode: `network_error` when the index is unreachable.
+
+## JSON output and errors
+
+- `--json` on any command returns the same data the human output renders,
+  machine-readable.
+- Failures use a stable envelope with a machine-readable `code` — see the codes
+  listed per command above. Network failures map to `network_error`; unexpected
+  errors fall back to the generic code `error`. Server errors surface the
+  server's own code (for example `not_found`, `validation_failed`,
+  `internal_error`).
+
+## Safety
+
+- **Secrets are scanned before publish.** High-confidence findings block the
+  publish with `blocking_secrets`; nothing leaves your machine.
+- **Installs never overwrite.** An existing target raises `target_exists`; there
+  is no `--force`.
+- **Metadata only.** OOMPF indexes metadata and validation results; the canonical
+  artifact stays at its public Gist.
+
+## Links
+
+- Documentation: [https://oompf.run/docs/](https://oompf.run/docs/)
+- Repository: [grosspoetrysystems/oompf](https://github.com/grosspoetrysystems/oompf)
+- Issues: [https://github.com/grosspoetrysystems/oompf/issues](https://github.com/grosspoetrysystems/oompf/issues)

package/dist/index.d.mts

@@ -0,0 +1,179 @@
+import { Cli } from "incur";
+//#region ../../packages/core/dist/omp-profile.d.ts
+/**
+ * Portable OMP profile discovery and path resolution.
+ *
+ * OOMPF never hardcodes `~/.omp`. Instead it treats the OMP CLI as the single
+ * source of truth for where a profile's agent directory lives, invoking
+ * `omp --profile <name> config path` (and the profile-less `omp config path`)
+ * with the current environment propagated. This honours `PI_CONFIG_DIR`,
+ * `PI_CODING_AGENT_DIR`, XDG base directories, and OMP's own profile
+ * resolution without OOMPF having to re-implement any of it.
+ *
+ * OMP is always invoked as an argv array (never a shell string), so profile
+ * names — even hostile ones — are passed as opaque arguments with no shell
+ * interpolation.
+ */
+/** A profile found on disk under OMP's resolved profiles directory. */
+interface DiscoveredProfile {
+  /** Absolute path to the profile's agent directory. */
+  readonly agentDir: string;
+  /** Absolute path to `config.yml`/`config.yaml`, or `null` if neither exists. */
+  readonly configPath: string | null;
+  /** The profile name (directory basename), already OMP-valid. */
+  readonly name: string;
+}
+/** The fully resolved configuration for a single existing profile. */
+interface ResolvedProfileConfig {
+  /** Absolute path to the profile's agent directory (verified to exist). */
+  readonly agentDir: string;
+  /** Absolute path to the loaded config file, or `null` when none is present. */
+  readonly configPath: string | null;
+  /** Parsed config document (mapping root), or `null` when no config exists. */
+  readonly document: Record<string, unknown> | null;
+  /** The profile name that was resolved. */
+  readonly profile: string;
+}
+/** Options accepted by every resolver; `ompCommand` overrides the binary. */
+interface OmpProfileOptions {
+  /** Executable used to invoke OMP. Defaults to `"omp"` on `PATH`. */
+  readonly ompCommand?: string;
+}
+/**
+ * Resolve the agent directory OMP would use to install a profile named `name`.
+ *
+ * Validates the name first, then asks OMP for the path. Succeeds for a profile
+ * that does not yet exist — the returned directory is an install target, so it
+ * is not required to be present on disk.
+ */
+declare function resolveInstallTarget(name: string, options?: OmpProfileOptions): Promise<string>;
+/**
+ * Resolve the full configuration for an existing profile.
+ *
+ * Validates the name, resolves the agent directory via OMP (which MUST exist),
+ * then loads `config.yml`/`config.yaml` if present. Rejects when the profile's
+ * agent directory is missing.
+ */
+declare function resolveProfileConfig(profile: string, options?: OmpProfileOptions): Promise<ResolvedProfileConfig>;
+/**
+ * Discover every profile present under OMP's resolved profiles directory.
+ *
+ * The profiles root is derived from OMP's own default agent path (`omp config
+ * path`), so it follows whatever `PI_CONFIG_DIR`/XDG/etc. resolution OMP
+ * applies. Directory entries whose names are not OMP-valid, and profiles whose
+ * agent directory is absent, are skipped. Results are sorted by name.
+ */
+declare function discoverProfiles(options?: OmpProfileOptions): Promise<DiscoveredProfile[]>;
+//#endregion
+//#region ../../packages/github/dist/gh.d.ts
+/**
+ * CLI-side `gh` (GitHub CLI) integration for OOMPF.
+ *
+ * This module shells out to the `gh` binary to read the authenticated identity
+ * and to publish public Gists. It MUST only ever be imported by CLI-side code:
+ * it spawns child processes and therefore cannot run inside a Cloudflare
+ * Worker. Every invocation passes an explicit argument array to the runner —
+ * there is no shell string and no interpolation, so profile names,
+ * descriptions, and file contents can never be reinterpreted as shell syntax.
+ *
+ * All process spawning is funnelled through an injectable {@link CommandRunner}
+ * seam so tests can exercise identity resolution and Gist publishing
+ * hermetically, without a real `gh` binary and without creating real Gists.
+ */
+/** Outcome of running a single command. */
+interface CommandResult {
+  /** Process exit code; `null` when the process was terminated by a signal. */
+  readonly exitCode: number | null;
+  readonly stderr: string;
+  readonly stdout: string;
+}
+/** A single command invocation: an executable plus a literal argument array. */
+interface CommandInput {
+  /** Arguments passed verbatim; never concatenated into a shell command. */
+  readonly args: readonly string[];
+  /** Executable to run (e.g. `"gh"`). Never a shell string. */
+  readonly command: string;
+  /** Optional UTF-8 text piped to the process stdin. */
+  readonly stdin?: string;
+}
+/**
+ * Injectable command seam. Implementations MUST NOT invoke a shell; they run
+ * `input.command` with `input.args` as discrete argv entries.
+ *
+ * A missing executable MUST reject (e.g. an `ENOENT` error) rather than
+ * resolve with a non-zero exit code, so callers can distinguish "not
+ * installed" from "ran and failed".
+ */
+type CommandRunner = (input: CommandInput) => Promise<CommandResult>;
+//#endregion
+//#region ../../packages/github/dist/gists.d.ts
+/** Minimal structural view of a `fetch` response used by this module. */
+interface GistFetchResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  text(): Promise<string>;
+}
+/** Injectable `fetch` seam so tests never hit the network. */
+type GistFetch = (url: string, init?: {
+  readonly headers?: Record<string, string>;
+}) => Promise<GistFetchResponse>;
+//#endregion
+//#region src/deps.d.ts
+/** Minimal structural view of an HTTP response the API client consumes. */
+interface HttpResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  text(): Promise<string>;
+}
+/** Injectable HTTP seam for the OOMPF web API (register/search/metadata). */
+type HttpFetch = (url: string, init?: {
+  readonly method?: string;
+  readonly headers?: Record<string, string>;
+  readonly body?: string;
+}) => Promise<HttpResponse>;
+/** Injectable filesystem seam for reading and atomically installing configs. */
+interface FsSeam {
+  /** True when a path exists (file or directory). */
+  exists(path: string): Promise<boolean>;
+  /** Recursively create a directory with the given octal permission mode. */
+  mkdir(path: string, mode: number): Promise<void>;
+  /** Read a UTF-8 text file. */
+  readFile(path: string): Promise<string>;
+  /** Write a UTF-8 text file with the given octal permission mode. */
+  writeFile(path: string, data: string, mode: number): Promise<void>;
+}
+/** Every seam a command may need, each optional and defaulted at the boundary. */
+interface CliDeps {
+  /** Profile discovery seam (publish default-profile derivation). */
+  readonly discoverProfiles?: typeof discoverProfiles;
+  /** Filesystem seam. */
+  readonly fs?: FsSeam;
+  /** `gh` executable name; defaults to `"gh"`. */
+  readonly ghCommand?: string;
+  /** Gist raw-fetch seam; defaults to the global `fetch`. */
+  readonly gistFetch?: GistFetch;
+  /** OOMPF web API HTTP seam; defaults to the global `fetch`. */
+  readonly httpFetch?: HttpFetch;
+  /** `omp` executable name; defaults to `"omp"`. */
+  readonly ompCommand?: string;
+  /** Install-target resolver seam (add). */
+  readonly resolveInstallTarget?: typeof resolveInstallTarget;
+  /** Existing-profile resolver seam (publish). */
+  readonly resolveProfileConfig?: typeof resolveProfileConfig;
+  /** `gh` command runner seam (auth check + Gist creation). */
+  readonly runner?: CommandRunner;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * OOMPF CLI version, surfaced by `oompf --version`.
+ *
+ * Must match `package.json`; `index.test.ts` asserts it, because a published
+ * binary reporting the wrong version makes every bug report ambiguous.
+ */
+declare const CLI_VERSION = "0.1.0";
+/** Build the OOMPF CLI with the given (optional) injectable seams. */
+declare function createCli(deps?: CliDeps): Cli.Cli<{}, undefined, undefined, undefined>;
+//#endregion
+export { CLI_VERSION, createCli };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +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;;;;;;;;;;cC5EP;;iBAGG,UAAU,OAAM,UAAY,IAAA"}