@pleri/olam-cli 0.1.7

package/dist/commands/host-cp.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Phase F-2-D (D1+D2+D3): `olam host-cp <subcommand>` — operator-facing
+ * lifecycle for the host CP container.
+ *
+ * Subcommands:
+ *   start  — generate token, audit port 19000, docker compose up, write PID
+ *   stop   — docker compose down, remove PID + token
+ *   status — diagnostic probe (with optional --json flag)
+ *
+ * Wraps the compose stack at `packages/host-cp/compose.yaml`. Token
+ * lives at `~/.olam/host-cp.token` (chmod 600). PID file at
+ * `~/.olam/host-cp.pid`. Both are operator-state files, not repo state.
+ */
+import type { Command } from 'commander';
+/**
+ * Path to the operator-state shared auth-service secret.
+ *
+ * Created by `olam auth up` when the auth-service container first
+ * starts. Both the auth-service container and host-cp container must
+ * use the same secret value as their `X-Olam-Secret` so host-cp's
+ * `/credentials/*` calls authenticate correctly.
+ *
+ * Honors OLAM_HOME for tests (matches `olamHome()`).
+ */
+export declare function authSecretPath(): string;
+/**
+ * Read the shared auth-service secret from `~/.olam/auth-secret`.
+ *
+ * Returns null when the file is missing (auth-service was never started
+ * or the file was deleted). Returns null instead of throwing because
+ * `host-cp start` should still bring host-cp up — but it then logs a
+ * loud warning so the operator notices that credential surfaces will
+ * 401 until they run `olam auth up` to regenerate the secret.
+ *
+ * Empty/whitespace files are treated as "not set" (null) — a 0-byte
+ * file would otherwise round-trip to compose as an empty env var,
+ * which is exactly the silent-failure mode this whole helper exists
+ * to prevent.
+ */
+export declare function readAuthSecret(): string | null;
+export interface R2Credentials {
+    account_id: string;
+    bucket: string;
+    access_key_id: string;
+    secret_access_key: string;
+    public_url_base: string;
+}
+/** Path to `~/.olam/r2-credentials.json`. Honors OLAM_HOME for tests. */
+export declare function r2CredentialsPath(): string;
+/**
+ * Read R2 credentials from `~/.olam/r2-credentials.json`.
+ *
+ * Returns null when the file is missing — callers should print a clear
+ * "operator must configure" error rather than throwing. Returns null for
+ * malformed JSON so callers can surface a useful message instead of a
+ * raw parse stack trace.
+ */
+export declare function readR2Credentials(): R2Credentials | null;
+/**
+ * Generate a fresh 32-byte hex token and write it to `tokenPath()` with
+ * mode 0600. Creates the parent directory if missing. Idempotent: if a
+ * token already exists, this overwrites it (each `start` regenerates).
+ */
+export declare function writeToken(): string;
+export declare function readToken(): string | null;
+export declare function removeToken(): boolean;
+export declare function writePid(pid: number): void;
+export declare function readPid(): number | null;
+export declare function removePid(): boolean;
+interface ContainerInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly state: string;
+    readonly status: string;
+}
+/**
+ * Find the host-cp container by name. Returns null if absent.
+ */
+export declare function findHostCpContainer(): Promise<ContainerInfo | null>;
+/**
+ * Phase host-cp-reliability: Probe for a running host CP, supporting
+ * both bare-node (process on host) and container deployments.
+ *
+ * Strategy:
+ *   1. HTTP probe: try http://127.0.0.1:19000/api/bootstrap. If the
+ *      token file exists and the endpoint returns 200, host-cp is running.
+ *      Mode is 'bare' if no docker container found, 'container' otherwise.
+ *   2. Docker fallback: if HTTP probe fails, look for the docker container.
+ *      If found+running, probe its port.
+ *
+ * Returns null if both fail, along with probe diagnostics in the
+ * returned ProbeFailure for fail-loud error messages.
+ *
+ * @returns {Promise<{ url: string; mode: 'bare' | 'container' } | null>}
+ *   Result on success, null on failure.
+ */
+export declare function probeHostCp(): Promise<{
+    url: string;
+    mode: 'bare' | 'container';
+} | null>;
+/**
+ * Gather probe failure diagnostics for fail-loud error messages.
+ * Returns structured info about what was tried and why it failed.
+ */
+export declare function gatherProbeFailureDiagnostics(): Promise<{
+    bootstrapStatus: string;
+    containerStatus: string;
+}>;
+export interface ComposeResult {
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export declare function runCompose(args: readonly string[], composeFile: string, extraEnv?: Record<string, string>): ComposeResult;
+/**
+ * Build the extra env vars to pass to `docker compose up`. Pure helper
+ * extracted so the env-merge contract is unit-testable without spawning
+ * docker. Returns an object with only the keys we set; absent values
+ * are omitted so process.env defaults can win when the secret file is
+ * missing (and the boot warning surfaces the gap).
+ *
+ * Exported for tests.
+ */
+export declare function buildComposeEnv(authSecret: string | null, ghToken?: string | null): Record<string, string>;
+/**
+ * Capture the operator's GitHub token by running `gh auth token` on the
+ * host. Returns the token string on success, null when gh is not installed
+ * or the operator is not authenticated.
+ *
+ * Never throws — callers that need a token should check for null and warn,
+ * but must not block host-cp from starting.
+ *
+ * Exported for tests.
+ */
+export declare function captureGhToken(): string | null;
+export declare function registerHostCp(program: Command): void;
+/**
+ * Phase D6 (olam-dogfood-vision): open a Host CP URL in the operator's
+ * default browser.
+ *
+ * D-phase audit follow-up (HIGH-1): the helper now lives in
+ * `@olam/core/src/util/open-url.ts` so both this CLI and the MCP
+ * server can import it statically. Earlier shape duplicated the
+ * helper here and required @olam/mcp-server to dynamic-import the
+ * compiled CLI dist — fragile under stale-build conditions. Static
+ * import via @olam/core (already a declared dep on both packages)
+ * removes the cross-package dynamic-import + as-never-cast pattern.
+ *
+ * Re-exported here so existing callers don't need to update their
+ * imports.
+ */
+export { openUrl as openHostCpUrl } from '@olam/core/src/util/open-url.js';
+/**
+ * Phase C8 (olam-dogfood-vision): generic host-cp proxy caller for
+ * `/api/world/<id>/*` routes. Used by `olam lanes` subcommands to
+ * reach the per-world CP through host-cp's auth-injecting proxy
+ * (host-cp injects X-Olam-Secret server-side; the operator only
+ * sees the Bearer token).
+ *
+ * Returns the parsed JSON body on success, or {ok:false, error} on
+ * any failure (token missing, network error, non-2xx response).
+ *
+ * @param method
+ * @param worldId
+ * @param path  the per-world CP path including leading slash, e.g.
+ *              '/lanes', '/lanes/foo', '/lanes/foo/dispatch'
+ * @param body  optional JSON body for POST/DELETE
+ */
+export declare function callHostCpProxy(method: 'GET' | 'POST' | 'DELETE', worldId: string, path: string, body?: unknown): Promise<{
+    ok: true;
+    status: number;
+    data: unknown;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+}>;
+/**
+ * POST/DELETE the host-cp admin registry endpoint. Exported so other
+ * commands (create, destroy) can auto-register without re-implementing
+ * the fetch dance.
+ */
+export declare function callHostCpRegistry(method: 'POST' | 'DELETE', body: {
+    id: string;
+    port?: number;
+}): Promise<{
+    ok: boolean;
+    status: number;
+    error?: string;
+}>;
+//# sourceMappingURL=host-cp.d.ts.map

package/dist/commands/host-cp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-cp.d.ts","sourceRoot":"","sources":["../../src/commands/host-cp.ts"],"names":[],"mappings":"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"}