@nurix/apollo 0.2.0

package/README.md

@@ -0,0 +1,114 @@
+# `@nurix/apollo` — the `apollo` CLI
+
+The consumer-side installer for the Apollo discovery plane. It implements the
+build-time integration flow of the
+[consumer journey](../../docs/discovery/consumer-journey.md): exchange your
+application key for service-scoped credentials, write them into a managed
+`.env` block, install the service's npm package, and record the `consumes`
+edge in your `apollo.service.json` (the application's bill of materials).
+
+Interactive UX is built on [`@clack/prompts`](https://github.com/bombshell-dev/clack).
+
+## Install
+
+Published to npm with **restricted access** under the `@nurix` scope — you need
+an npm account with read rights to the `nurix` org (`npm login`, then verify
+with `npm whoami`).
+
+```
+npx @nurix/apollo@latest --help      # one-shot
+npm install -g @nurix/apollo         # or install the `apollo` binary globally
+```
+
+## Commands (implemented)
+
+```
+apollo init                  # store + validate APOLLO_APP_KEY, gitignore .env,
+                             # scaffold apollo.service.json
+apollo add <service>         # the installer (see flow below)
+apollo add                   # same, picking the service from the catalogue
+apollo list                  # one line per catalogue service
+
+apollo sync                  # re-project ALL credentials issued to this
+                             # application into the managed block (server wins;
+                             # stale entries removed)
+apollo describe <svc> [--json]   # full catalogue entry, pretty or raw
+apollo validate [manifest] [--schema <pathOrUrl>]
+                             # JSON Schema validation (apollo.dev/v1, draft-07;
+                             # schema bundled into dist/ at build time)
+apollo graph [--mermaid]     # consumes-graph: ascii edges or mermaid `graph LR`
+apollo doctor                # key validity + per-credential health probes +
+                             # manifest conformance + deprecated-consumes warnings
+apollo open <svc> [--env <name>] # open endpoint (default production) or repo URL
+```
+
+Global options: `--apollo-url <url>` (defaults to `$APOLLO_URL`, then the
+hosted instance `https://apollo.nurix-ai.co`).
+
+### `apollo init`
+
+1. Prompts for your `APOLLO_APP_KEY` (created with your application in the
+   Apollo console) and **validates it against Apollo — no key, no install**.
+2. Writes it into the **Apollo-managed block** of `.env` (+ a placeholder in
+   `.env.example`) and makes sure `.env` is gitignored.
+3. Offers to scaffold `apollo.service.json` if the repo has none.
+
+### `apollo add <service>` — the installer
+
+1. Reads `APOLLO_APP_KEY` from the managed block (or the environment); fails
+   loudly with remediation if missing.
+2. Fetches the catalogue and resolves the service (interactive select when no
+   name is passed).
+3. `POST /api/v1/keys/exchange` → `{ endpoint, serviceKey }` — idempotent per
+   (application × service), so re-running is safe.
+4. Writes `<SERVICE>_ENDPOINT` + `<SERVICE>_KEY` into the managed `.env`
+   block, placeholders into `.env.example`.
+5. Installs the service's npm package when it ships one (package manager
+   detected from the repo's lockfile).
+6. Appends the `consumes` edge to `apollo.service.json` (offers a scaffold if
+   the manifest is missing).
+7. Best-effort health probe against the issued endpoint (never blocks).
+
+### The managed `.env` block
+
+The CLI owns **only** the delimited block — everything outside it is yours and
+is never touched:
+
+```
+MY_OWN_SECRET=untouched
+
+# >>> apollo:managed — do not edit by hand; the apollo CLI rewrites this block >>>
+APOLLO_APP_KEY=apollo_app_…
+EMAIL_ENDPOINT=https://…
+EMAIL_KEY=apollo_svc_…
+# <<< apollo:managed <<<
+```
+
+Inside the block the server is the source of truth (manual edits get
+overwritten); outside it, nothing is ever rewritten.
+
+## Development
+
+```
+pnpm --filter @nurix/apollo build              # tsc → dist/ (+ schema copy)
+pnpm --filter @nurix/apollo typecheck
+node packages/cli/dist/index.js --help         # run from the repo root
+```
+
+ESM, Node ≥ 22, strict TypeScript. `bin` is `dist/index.js` (`apollo`).
+Releases ship via `.github/workflows/publish-cli-to-npm.yml` — merges to `dev`
+touching `packages/cli/**` auto-publish a patch; dispatch the workflow for
+minor/major.
+
+## Current limitations
+
+- The hosted catalogue is empty until the registry read path lands
+  (consumer-journey.md R3) — `list`/`describe`/`graph`/`open` degrade with a
+  clear message; `apollo add <name>` still works for services seeded into the
+  KV catalogue, since the exchange resolves endpoints server-side.
+- `apollo sync` needs `GET /api/v1/keys/credentials` (journey R7) — the route
+  is in the worker code; it goes live with the next worker deploy.
+- Exchange still returns `{endpoint, serviceKey}` together; once it slims to
+  credential-only with Apollo-served definitions (journey §9.2–§9.3), the
+  client picks the endpoint up from the definition instead
+  (`src/lib/apollo_client.ts` is the seam).

package/dist/commands/add.js

@@ -0,0 +1,152 @@
+// packages/cli/src/commands/add.ts - `apollo add <service>`: the installer.
+// Resolves the service in the catalogue, exchanges the app key for a scoped
+// credential, writes the managed .env block, installs the npm package, and
+// records the consumes edge (consumer-journey.md §4–§5).
+import path from "node:path";
+import * as p from "@clack/prompts";
+import { exchangeServiceCredential, fetchCatalogue, resolveApolloUrl, } from "../lib/apollo_client.js";
+import { readManagedValues, upsertManagedValues } from "../lib/env_file.js";
+import { detectPackageManager, installPackage } from "../lib/package_manager.js";
+import { appendConsumesEdge, hasManifest, scaffoldManifest } from "../lib/manifest.js";
+import { confirmOrFallback, isInteractive } from "../lib/interactive.js";
+// Run the installer flow end to end for one service.
+export async function runAdd(serviceArg, options) {
+    const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(options);
+    p.intro(`apollo add${serviceArg ? ` ${serviceArg}` : ""}`);
+    const managedValues = await readManagedValues(path.join(cwd, ".env"));
+    const appKey = managedValues.APOLLO_APP_KEY ?? process.env.APOLLO_APP_KEY;
+    if (!appKey) {
+        p.log.error("No APOLLO_APP_KEY found (managed .env block or environment).");
+        p.outro("Run `apollo init` first — no key, no install.");
+        process.exitCode = 1;
+        return;
+    }
+    const spinner = p.spinner();
+    spinner.start("Fetching the catalogue");
+    const catalogue = await fetchCatalogue(baseUrl).catch(() => null);
+    const services = catalogue?.services ?? [];
+    spinner.stop(`Catalogue loaded: ${services.length} service(s)`);
+    const serviceName = serviceArg ?? (await pickService(services));
+    if (!serviceName) {
+        p.outro("Nothing was written.");
+        process.exitCode = 1;
+        return;
+    }
+    const catalogueEntry = services.find((service) => service.name === serviceName);
+    if (!catalogueEntry) {
+        p.log.warn(`'${serviceName}' is not in the catalogue — attempting the exchange anyway.`);
+    }
+    spinner.start(`Exchanging credentials for '${serviceName}'`);
+    let credential;
+    try {
+        credential = await exchangeServiceCredential(baseUrl, appKey, serviceName);
+    }
+    catch (error) {
+        spinner.stop("Exchange failed", 1);
+        p.log.error(error instanceof Error ? error.message : String(error));
+        p.outro("Nothing was written.");
+        process.exitCode = 1;
+        return;
+    }
+    spinner.stop("Credential issued (idempotent per application + service)");
+    const envPrefix = toEnvPrefix(serviceName);
+    await upsertManagedValues(path.join(cwd, ".env"), {
+        [`${envPrefix}_ENDPOINT`]: credential.endpoint,
+        [`${envPrefix}_KEY`]: credential.serviceKey,
+    });
+    await upsertManagedValues(path.join(cwd, ".env.example"), {
+        [`${envPrefix}_ENDPOINT`]: "",
+        [`${envPrefix}_KEY`]: "",
+    });
+    p.log.success(`Wrote ${envPrefix}_ENDPOINT and ${envPrefix}_KEY to the managed .env block`);
+    await maybeInstallPackage(catalogueEntry, cwd);
+    await recordConsumesEdge(catalogueEntry, serviceName, cwd);
+    await probeHealth(catalogueEntry, credential);
+    p.outro(`'${serviceName}' is wired in.`);
+}
+// Let the user pick a service interactively when none was passed.
+async function pickService(services) {
+    if (services.length === 0) {
+        p.log.error("The catalogue is empty — pass the service name explicitly: apollo add <service>");
+        return undefined;
+    }
+    if (!isInteractive()) {
+        p.log.error("No terminal for the picker — pass the service name explicitly: apollo add <service>");
+        return undefined;
+    }
+    const selection = await p.select({
+        message: "Which service do you want to add?",
+        options: services.map((service) => ({
+            value: service.name,
+            label: service.name,
+            hint: [service.type ?? service.kind, service.status].filter(Boolean).join(" · "),
+        })),
+    });
+    if (p.isCancel(selection)) {
+        p.cancel("add cancelled.");
+        return undefined;
+    }
+    return selection;
+}
+// Derive the env-var prefix from the service name (nustack-rag → NUSTACK_RAG).
+function toEnvPrefix(serviceName) {
+    return serviceName.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+// Install the service's npm package when it ships one, after confirmation.
+async function maybeInstallPackage(entry, cwd) {
+    const packageName = entry?.npm?.package;
+    if (!packageName)
+        return;
+    const manager = detectPackageManager(cwd);
+    const shouldInstall = await confirmOrFallback(`Install ${packageName} with ${manager}?`, true);
+    if (!shouldInstall) {
+        p.log.info(`Skipped the package install — run: ${manager} add ${packageName}`);
+        return;
+    }
+    try {
+        await installPackage(manager, packageName, cwd);
+        p.log.success(`Installed ${packageName}`);
+    }
+    catch (error) {
+        p.log.warn(`Package install failed (non-blocking): ${error instanceof Error ? error.message : error}`);
+    }
+}
+// Record the consumes edge in apollo.service.json, offering a scaffold if absent.
+async function recordConsumesEdge(entry, serviceName, cwd) {
+    if (!hasManifest(cwd)) {
+        const repoName = path.basename(cwd).toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+        const shouldScaffold = await confirmOrFallback(`No apollo.service.json — scaffold one for "${repoName}" to record the consumes edge?`, true);
+        if (!shouldScaffold) {
+            p.log.info("Skipped — the consumes edge (bill of materials) was not recorded.");
+            return;
+        }
+        await scaffoldManifest(cwd, repoName);
+        p.log.success("Scaffolded apollo.service.json");
+    }
+    const via = entry?.npm?.package ? "npm" : "http";
+    const wasAppended = await appendConsumesEdge(cwd, { service: serviceName, via, endpoint: "production" });
+    p.log.success(wasAppended
+        ? `Recorded the consumes edge: ${serviceName} (via ${via})`
+        : `Consumes edge for ${serviceName} already declared`);
+}
+// Best-effort health probe against the issued endpoint; warns, never blocks.
+async function probeHealth(entry, credential) {
+    const healthPath = entry?.http?.health ?? "/health";
+    const url = credential.endpoint.replace(/\/+$/, "") + healthPath;
+    try {
+        const response = await fetch(url, {
+            headers: { Authorization: `Bearer ${credential.serviceKey}` },
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (response.ok) {
+            p.log.success(`Health check passed (${url})`);
+        }
+        else {
+            p.log.warn(`Health check returned HTTP ${response.status} (${url}) — non-blocking`);
+        }
+    }
+    catch {
+        p.log.warn(`Health probe unreachable (${url}) — non-blocking`);
+    }
+}

package/dist/commands/describe.js

@@ -0,0 +1,36 @@
+// packages/cli/src/commands/describe.ts - `apollo describe <service>`: the full
+// catalogue entry for one service, prettified or raw JSON.
+import * as p from "@clack/prompts";
+import { fetchCatalogue, resolveApolloUrl } from "../lib/apollo_client.js";
+// Print one catalogue entry; --json emits the raw object for piping.
+export async function runDescribe(serviceName, options, globals) {
+    const baseUrl = resolveApolloUrl(globals);
+    const catalogue = await fetchCatalogue(baseUrl);
+    const entry = (catalogue.services ?? []).find((service) => service.name === serviceName);
+    if (!entry) {
+        p.log.error(`'${serviceName}' is not in the catalogue at ${baseUrl} (${catalogue.services?.length ?? 0} services listed).`);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(entry, null, 2));
+        return;
+    }
+    console.log(`${entry.name}  —  ${entry.description ?? "(no description)"}`);
+    console.log(`  kind/type:  ${entry.kind ?? "?"} / ${entry.type ?? "?"}`);
+    console.log(`  status:     ${entry.status ?? "?"}`);
+    if (entry.repository)
+        console.log(`  repository: ${entry.repository}`);
+    if (entry.npm?.package)
+        console.log(`  npm:        ${entry.npm.package}`);
+    for (const [envName, url] of Object.entries(entry.http?.endpoints ?? {})) {
+        console.log(`  endpoint:   ${envName} → ${url}`);
+    }
+    if (entry.env?.required?.length)
+        console.log(`  env (required): ${entry.env.required.join(", ")}`);
+    if (entry.env?.optional?.length)
+        console.log(`  env (optional): ${entry.env.optional.join(", ")}`);
+    for (const edge of entry.consumes ?? []) {
+        console.log(`  consumes:   ${edge.service}${edge.via ? ` (via ${edge.via})` : ""}`);
+    }
+}

package/dist/commands/doctor.js

@@ -0,0 +1,130 @@
+// packages/cli/src/commands/doctor.ts - `apollo doctor`: repo health — key
+// validity, per-credential health probes, manifest schema validity, and
+// consumes edges cross-checked against the catalogue. Warnings inform;
+// errors exit 1.
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import * as p from "@clack/prompts";
+import { fetchCatalogue, resolveApolloUrl, validateAppKey, } from "../lib/apollo_client.js";
+import { readManagedValues } from "../lib/env_file.js";
+import { hasManifest, manifestPath } from "../lib/manifest.js";
+import { loadSchema, validateManifest } from "../lib/schema_validator.js";
+// Run every check; exit 1 when any error (not warning) was found.
+export async function runDoctor(globals) {
+    const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(globals);
+    p.intro("apollo doctor");
+    const counters = { errors: 0, warnings: 0 };
+    const managedValues = await readManagedValues(path.join(cwd, ".env"));
+    await checkAppKey(managedValues, baseUrl, counters);
+    await checkServiceCredentials(managedValues, counters);
+    await checkManifest(cwd, baseUrl, counters);
+    const summary = `${counters.errors} error(s), ${counters.warnings} warning(s)`;
+    if (counters.errors > 0) {
+        p.outro(`Unhealthy — ${summary}.`);
+        process.exitCode = 1;
+    }
+    else {
+        p.outro(`Healthy — ${summary}.`);
+    }
+}
+// Check the APOLLO_APP_KEY exists and is still accepted by Apollo.
+async function checkAppKey(managedValues, baseUrl, counters) {
+    const appKey = managedValues.APOLLO_APP_KEY ?? process.env.APOLLO_APP_KEY;
+    if (!appKey) {
+        p.log.error("APOLLO_APP_KEY missing — run `apollo init`.");
+        counters.errors += 1;
+        return;
+    }
+    const isValid = await validateAppKey(baseUrl, appKey).catch(() => false);
+    if (isValid) {
+        p.log.success("APOLLO_APP_KEY accepted by Apollo");
+    }
+    else {
+        p.log.error("APOLLO_APP_KEY rejected (revoked or invalid) — re-run `apollo init`.");
+        counters.errors += 1;
+    }
+}
+// Probe /health for every <PREFIX>_ENDPOINT/<PREFIX>_KEY pair in the managed block.
+async function checkServiceCredentials(managedValues, counters) {
+    const endpointKeys = Object.keys(managedValues).filter((key) => key.endsWith("_ENDPOINT") && key !== "APOLLO_APP_KEY");
+    if (endpointKeys.length === 0) {
+        p.log.info("No service credentials in the managed block yet.");
+        return;
+    }
+    for (const endpointKey of endpointKeys) {
+        const prefix = endpointKey.slice(0, -"_ENDPOINT".length);
+        const endpoint = managedValues[endpointKey];
+        const serviceKey = managedValues[`${prefix}_KEY`];
+        if (!serviceKey) {
+            p.log.warn(`${prefix}: endpoint present but ${prefix}_KEY missing — run \`apollo sync\`.`);
+            counters.warnings += 1;
+            continue;
+        }
+        try {
+            const response = await fetch(`${endpoint.replace(/\/+$/, "")}/health`, {
+                headers: { Authorization: `Bearer ${serviceKey}` },
+                signal: AbortSignal.timeout(5_000),
+            });
+            if (response.ok) {
+                p.log.success(`${prefix}: health OK (${endpoint})`);
+            }
+            else {
+                p.log.warn(`${prefix}: health returned HTTP ${response.status} (${endpoint})`);
+                counters.warnings += 1;
+            }
+        }
+        catch {
+            p.log.warn(`${prefix}: unreachable (${endpoint})`);
+            counters.warnings += 1;
+        }
+    }
+}
+// Validate the manifest and cross-check its consumes edges against the catalogue.
+async function checkManifest(cwd, baseUrl, counters) {
+    if (!hasManifest(cwd)) {
+        p.log.warn("No apollo.service.json — the app has no bill of materials. `apollo init` scaffolds one.");
+        counters.warnings += 1;
+        return;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath(cwd), "utf8"));
+    }
+    catch {
+        p.log.error("apollo.service.json is not valid JSON.");
+        counters.errors += 1;
+        return;
+    }
+    const schema = await loadSchema().catch(() => null);
+    if (schema) {
+        const result = validateManifest(schema, manifest);
+        if (result.isValid) {
+            p.log.success("apollo.service.json is schema-valid");
+        }
+        else {
+            p.log.error(`apollo.service.json fails the schema: ${result.errors.join("; ")}`);
+            counters.errors += 1;
+        }
+    }
+    const edges = (manifest.services ?? []).flatMap((service) => service.consumes ?? []);
+    if (edges.length === 0)
+        return;
+    const catalogue = await fetchCatalogue(baseUrl).catch(() => null);
+    const services = catalogue?.services ?? [];
+    if (services.length === 0) {
+        p.log.info("Catalogue empty — consumes edges not cross-checked.");
+        return;
+    }
+    for (const edge of edges) {
+        const entry = services.find((service) => service.name === edge.service);
+        if (!entry) {
+            p.log.warn(`consumes '${edge.service}' — not found in the catalogue.`);
+            counters.warnings += 1;
+        }
+        else if (entry.status === "deprecated") {
+            p.log.warn(`consumes '${edge.service}' — service is deprecated; plan a migration.`);
+            counters.warnings += 1;
+        }
+    }
+}

package/dist/commands/graph.js

@@ -0,0 +1,36 @@
+// packages/cli/src/commands/graph.ts - `apollo graph`: render the catalogue's
+// consumes-graph as an ascii edge list or a mermaid block.
+import { fetchCatalogue, resolveApolloUrl } from "../lib/apollo_client.js";
+// Print every consumes edge in the catalogue; --mermaid emits `graph LR`.
+export async function runGraph(options, globals) {
+    const baseUrl = resolveApolloUrl(globals);
+    const catalogue = await fetchCatalogue(baseUrl);
+    const services = catalogue.services ?? [];
+    const edges = services.flatMap((service) => (service.consumes ?? []).map((edge) => ({
+        from: service.name,
+        to: edge.service,
+        via: edge.via ?? "http",
+    })));
+    if (services.length === 0) {
+        console.log(`Catalogue at ${baseUrl} is empty — nothing to graph.`);
+        return;
+    }
+    if (edges.length === 0) {
+        console.log(`${services.length} service(s) in the catalogue, but no consumes edges declared.`);
+        return;
+    }
+    if (options.mermaid) {
+        console.log("graph LR");
+        for (const edge of edges) {
+            console.log(`    ${sanitizeMermaidId(edge.from)} -->|${edge.via}| ${sanitizeMermaidId(edge.to)}`);
+        }
+        return;
+    }
+    for (const edge of edges) {
+        console.log(`${edge.from.padEnd(30)} ──${edge.via}──▶ ${edge.to}`);
+    }
+}
+// Mermaid node ids can't contain slashes/dots — normalize while keeping them readable.
+function sanitizeMermaidId(name) {
+    return name.replace(/[^A-Za-z0-9_-]/g, "_");
+}

package/dist/commands/init.js

@@ -0,0 +1,73 @@
+// packages/cli/src/commands/init.ts - `apollo init`: store the APOLLO_APP_KEY in
+// the managed .env block (validated against Apollo — no key, no install),
+// gitignore .env, and scaffold the repo manifest.
+import path from "node:path";
+import * as p from "@clack/prompts";
+import { resolveApolloUrl, validateAppKey } from "../lib/apollo_client.js";
+import { ensureEnvGitignored, readManagedValues, upsertManagedValues } from "../lib/env_file.js";
+import { hasManifest, scaffoldManifest } from "../lib/manifest.js";
+import { isInteractive } from "../lib/interactive.js";
+// Run the init flow: collect + validate the key, write managed blocks, scaffold.
+export async function runInit(options) {
+    const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(options);
+    p.intro("apollo init");
+    if (!isInteractive()) {
+        p.log.error("apollo init needs an interactive terminal (it prompts for the key).");
+        p.outro("Re-run in a terminal, or write APOLLO_APP_KEY into the managed .env block directly.");
+        process.exitCode = 1;
+        return;
+    }
+    const managedValues = await readManagedValues(path.join(cwd, ".env"));
+    if (managedValues.APOLLO_APP_KEY) {
+        const shouldReplace = await p.confirm({
+            message: "An APOLLO_APP_KEY is already configured here. Replace it?",
+        });
+        if (p.isCancel(shouldReplace) || !shouldReplace) {
+            p.cancel("Kept the existing key — nothing changed.");
+            return;
+        }
+    }
+    const appKey = await p.password({
+        message: `Paste your APOLLO_APP_KEY (create an application in the Apollo console: ${baseUrl})`,
+        validate: (value) => value?.startsWith("apollo_app_") ? undefined : "Expected a key starting with apollo_app_",
+    });
+    if (p.isCancel(appKey)) {
+        p.cancel("init cancelled — nothing written.");
+        return;
+    }
+    const spinner = p.spinner();
+    spinner.start("Validating the key against Apollo");
+    const isValid = await validateAppKey(baseUrl, appKey).catch(() => false);
+    if (!isValid) {
+        spinner.stop("Key rejected by Apollo", 1);
+        p.outro("No key, no install — fix the key and re-run `apollo init`.");
+        process.exitCode = 1;
+        return;
+    }
+    spinner.stop("Key accepted");
+    await upsertManagedValues(path.join(cwd, ".env"), { APOLLO_APP_KEY: appKey });
+    await upsertManagedValues(path.join(cwd, ".env.example"), { APOLLO_APP_KEY: "" });
+    if (await ensureEnvGitignored(cwd)) {
+        p.log.info("Added .env to .gitignore");
+    }
+    if (!hasManifest(cwd)) {
+        const repoName = deriveRepoName(cwd);
+        const shouldScaffold = await p.confirm({
+            message: `No apollo.service.json found — scaffold one for "${repoName}"? Its consumes[] edges are the app's bill of materials.`,
+        });
+        if (!p.isCancel(shouldScaffold) && shouldScaffold) {
+            await scaffoldManifest(cwd, repoName);
+            p.log.success("Scaffolded apollo.service.json");
+        }
+    }
+    p.outro("Ready — run `apollo add <service>` to wire in your first stack service.");
+}
+// Derive a spec-conformant repo name (lowercase, hyphenated) from the folder name.
+function deriveRepoName(cwd) {
+    return path
+        .basename(cwd)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}

package/dist/commands/list.js

@@ -0,0 +1,18 @@
+// packages/cli/src/commands/list.ts - `apollo list`: print the discovery
+// catalogue, one line per service.
+import { fetchCatalogue, resolveApolloUrl } from "../lib/apollo_client.js";
+// Print the catalogue as aligned columns: name, classifier, status, description.
+export async function runList(options) {
+    const baseUrl = resolveApolloUrl(options);
+    const catalogue = await fetchCatalogue(baseUrl);
+    const services = catalogue.services ?? [];
+    if (services.length === 0) {
+        console.log(`Catalogue at ${baseUrl} is empty — the registry read path / refresh isn't wired yet.`);
+        return;
+    }
+    for (const service of services) {
+        const classifier = service.type ?? service.kind ?? "?";
+        const status = service.status ?? "?";
+        console.log(`${service.name.padEnd(30)} ${classifier.padEnd(18)} ${status.padEnd(14)} ${service.description ?? ""}`);
+    }
+}

package/dist/commands/open.js

@@ -0,0 +1,37 @@
+// packages/cli/src/commands/open.ts - `apollo open <service>`: open the
+// service's endpoint (or repository) in the default browser.
+import { spawn } from "node:child_process";
+import * as p from "@clack/prompts";
+import { fetchCatalogue, resolveApolloUrl } from "../lib/apollo_client.js";
+// Resolve the URL to open (chosen endpoint > production > any > repository) and launch it.
+export async function runOpen(serviceName, options, globals) {
+    const baseUrl = resolveApolloUrl(globals);
+    const catalogue = await fetchCatalogue(baseUrl);
+    const entry = (catalogue.services ?? []).find((service) => service.name === serviceName);
+    if (!entry) {
+        p.log.error(`'${serviceName}' is not in the catalogue at ${baseUrl}.`);
+        process.exitCode = 1;
+        return;
+    }
+    const endpoints = entry.http?.endpoints ?? {};
+    const url = (options.env ? endpoints[options.env] : undefined) ??
+        endpoints["production"] ??
+        Object.values(endpoints)[0] ??
+        entry.repository;
+    if (!url) {
+        p.log.error(`'${serviceName}' declares no endpoints and no repository to open.`);
+        process.exitCode = 1;
+        return;
+    }
+    launchBrowser(url);
+    p.log.success(`Opening ${url}`);
+}
+// Launch the platform's default opener, detached so the CLI can exit.
+function launchBrowser(url) {
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    spawn(command, args, { detached: true, stdio: "ignore" }).unref();
+}

package/dist/commands/sync.js

@@ -0,0 +1,57 @@
+// packages/cli/src/commands/sync.ts - `apollo sync`: re-project the
+// application's full server-side credential set into the managed .env block
+// (consumer-journey.md §6 — the server wins inside the block; stale
+// credentials disappear).
+import path from "node:path";
+import * as p from "@clack/prompts";
+import { fetchAppCredentials, resolveApolloUrl } from "../lib/apollo_client.js";
+import { readManagedValues, upsertManagedValues, writeManagedValues } from "../lib/env_file.js";
+// Run the sync flow: fetch the projection, rewrite the managed block wholly.
+export async function runSync(options) {
+    const cwd = process.cwd();
+    const baseUrl = resolveApolloUrl(options);
+    p.intro("apollo sync");
+    const managedValues = await readManagedValues(path.join(cwd, ".env"));
+    const appKey = managedValues.APOLLO_APP_KEY ?? process.env.APOLLO_APP_KEY;
+    if (!appKey) {
+        p.log.error("No APOLLO_APP_KEY found (managed .env block or environment).");
+        p.outro("Run `apollo init` first — no key, no sync.");
+        process.exitCode = 1;
+        return;
+    }
+    const spinner = p.spinner();
+    spinner.start("Fetching the application's credential projection");
+    let projection;
+    try {
+        projection = await fetchAppCredentials(baseUrl, appKey);
+    }
+    catch (error) {
+        spinner.stop("Projection failed", 1);
+        p.log.error(error instanceof Error ? error.message : String(error));
+        p.outro("The managed block was not touched.");
+        process.exitCode = 1;
+        return;
+    }
+    spinner.stop(`Application '${projection.app.name}' (${projection.app.environment}): ${projection.credentials.length} credential(s)`);
+    const nextValues = { APOLLO_APP_KEY: appKey };
+    const placeholders = { APOLLO_APP_KEY: "" };
+    for (const credential of [...projection.credentials].sort((a, b) => a.service.localeCompare(b.service))) {
+        const prefix = toEnvPrefix(credential.service);
+        nextValues[`${prefix}_ENDPOINT`] = credential.endpoint;
+        nextValues[`${prefix}_KEY`] = credential.serviceKey;
+        placeholders[`${prefix}_ENDPOINT`] = "";
+        placeholders[`${prefix}_KEY`] = "";
+    }
+    const removedKeys = Object.keys(managedValues).filter((key) => !(key in nextValues));
+    await writeManagedValues(path.join(cwd, ".env"), nextValues);
+    await upsertManagedValues(path.join(cwd, ".env.example"), placeholders);
+    p.log.success(`Managed block rewritten: ${projection.credentials.length} service credential(s).`);
+    if (removedKeys.length > 0) {
+        p.log.info(`Removed stale entries: ${removedKeys.join(", ")}`);
+    }
+    p.outro("In sync with Apollo.");
+}
+// Derive the env-var prefix from the service name (nustack-rag → NUSTACK_RAG).
+function toEnvPrefix(serviceName) {
+    return serviceName.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}