@nurix/apollo 0.2.0

package/dist/commands/validate.js

@@ -0,0 +1,40 @@
+// packages/cli/src/commands/validate.ts - `apollo validate [manifest]`: JSON
+// Schema validation of an apollo.service.json against the apollo.dev/v1 grammar.
+import { readFile } from "node:fs/promises";
+import * as p from "@clack/prompts";
+import { loadSchema, validateManifest } from "../lib/schema_validator.js";
+// Validate one manifest (local path or URL); exit 1 when invalid.
+export async function runValidate(manifestArg, options) {
+    const target = manifestArg ?? "./apollo.service.json";
+    let manifestRaw;
+    try {
+        manifestRaw = target.startsWith("http://") || target.startsWith("https://")
+            ? await (await fetch(target, { signal: AbortSignal.timeout(10_000) })).text()
+            : await readFile(target, "utf8");
+    }
+    catch (error) {
+        p.log.error(`Could not read ${target}: ${error instanceof Error ? error.message : error}`);
+        process.exitCode = 1;
+        return;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestRaw);
+    }
+    catch {
+        p.log.error(`${target} is not valid JSON.`);
+        process.exitCode = 1;
+        return;
+    }
+    const schema = await loadSchema(options.schema);
+    const result = validateManifest(schema, manifest);
+    if (result.isValid) {
+        p.log.success(`${target} is a valid apollo.dev/v1 manifest.`);
+        return;
+    }
+    p.log.error(`${target} failed validation:`);
+    for (const error of result.errors) {
+        console.error(`  - ${error}`);
+    }
+    process.exitCode = 1;
+}

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// packages/cli/src/index.ts - `apollo` CLI entry: command wiring.
+import { Command } from "commander";
+import { runInit } from "./commands/init.js";
+import { runAdd } from "./commands/add.js";
+import { runList } from "./commands/list.js";
+import { runSync } from "./commands/sync.js";
+import { runDescribe } from "./commands/describe.js";
+import { runValidate } from "./commands/validate.js";
+import { runGraph } from "./commands/graph.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runOpen } from "./commands/open.js";
+const program = new Command();
+program
+    .name("apollo")
+    .description("Bootstrap NuStack services into your repo via the Apollo discovery plane.")
+    .version("0.2.0")
+    .option("--apollo-url <url>", "Apollo base URL (defaults to $APOLLO_URL, then the hosted instance)");
+program
+    .command("init")
+    .description("Store your APOLLO_APP_KEY in the managed .env block and scaffold the manifest")
+    .action(async () => runInit(program.opts()));
+program
+    .command("add [service]")
+    .description("Install a stack service: exchange credentials, write .env, install the package")
+    .action(async (service) => runAdd(service, program.opts()));
+program
+    .command("list")
+    .description("List the services in the Apollo catalogue")
+    .action(async () => runList(program.opts()));
+program
+    .command("sync")
+    .description("Re-project all credentials issued to this application into the managed .env block")
+    .action(async () => runSync(program.opts()));
+program
+    .command("describe <service>")
+    .description("Show the full catalogue entry for a service")
+    .option("--json", "emit the raw catalogue entry as JSON")
+    .action(async (service, options) => runDescribe(service, options, program.opts()));
+program
+    .command("validate [manifest]")
+    .description("Validate an apollo.service.json (path or URL) against the apollo.dev/v1 schema")
+    .option("--schema <pathOrUrl>", "override the bundled spec/schema.json")
+    .action(async (manifest, options) => runValidate(manifest, options));
+program
+    .command("graph")
+    .description("Render the catalogue's consumes-graph")
+    .option("--mermaid", "emit a mermaid `graph LR` block instead of ascii")
+    .action(async (options) => runGraph(options, program.opts()));
+program
+    .command("doctor")
+    .description("Check key validity, credential health, and manifest conformance")
+    .action(async () => runDoctor(program.opts()));
+program
+    .command("open <service>")
+    .description("Open the service's endpoint (or repository) in the browser")
+    .option("--env <name>", "pick a specific endpoint environment (default: production)")
+    .action(async (service, options) => runOpen(service, options, program.opts()));
+await program.parseAsync(process.argv);

package/dist/lib/apollo_client.js

@@ -0,0 +1,56 @@
+// packages/cli/src/lib/apollo_client.ts - HTTP client for the Apollo discovery
+// plane: catalogue fetch + credential exchange + key validation.
+const DEFAULT_APOLLO_URL = "https://apollo.nurix-ai.co";
+const REQUEST_TIMEOUT_MS = 10_000;
+// Resolve the Apollo base URL: --apollo-url flag > APOLLO_URL env > hosted default.
+export function resolveApolloUrl(options) {
+    return (options.apolloUrl ?? process.env.APOLLO_URL ?? DEFAULT_APOLLO_URL).replace(/\/+$/, "");
+}
+// Fetch the public discovery catalogue.
+export async function fetchCatalogue(baseUrl) {
+    const response = await fetch(`${baseUrl}/api/catalog.json`, {
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`catalogue fetch failed: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}
+// Exchange the app key for a service-scoped credential (idempotent per app + service).
+export async function exchangeServiceCredential(baseUrl, appKey, serviceName) {
+    const response = await fetch(`${baseUrl}/api/v1/keys/exchange`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${appKey}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ service: serviceName }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.endpoint || !payload?.serviceKey) {
+        throw new Error(payload?.message ?? `exchange failed: HTTP ${response.status}`);
+    }
+    return { endpoint: payload.endpoint, serviceKey: payload.serviceKey };
+}
+// Fetch every service credential issued to the calling application (for sync).
+export async function fetchAppCredentials(baseUrl, appKey) {
+    const response = await fetch(`${baseUrl}/api/v1/keys/credentials`, {
+        headers: { Authorization: `Bearer ${appKey}` },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.app || !Array.isArray(payload.credentials)) {
+        throw new Error(payload?.message ?? `credential projection failed: HTTP ${response.status}`);
+    }
+    return { app: payload.app, credentials: payload.credentials };
+}
+// Probe whether an app key is valid: an exchange with no service body returns
+// 400 for a good key but 401 for a bad one — the only key check the API
+// exposes today (a dedicated validation endpoint is journey work, R2).
+export async function validateAppKey(baseUrl, appKey) {
+    const response = await fetch(`${baseUrl}/api/v1/keys/exchange`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${appKey}`, "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    return response.status !== 401;
+}

package/dist/lib/env_file.js

@@ -0,0 +1,72 @@
+// packages/cli/src/lib/env_file.ts - Read/write the Apollo-managed block in .env
+// files. The CLI owns only this delimited block; everything outside it belongs
+// to the developer and is never touched (consumer-journey.md §6).
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+const BLOCK_START = "# >>> apollo:managed — do not edit by hand; the apollo CLI rewrites this block >>>";
+const BLOCK_END = "# <<< apollo:managed <<<";
+// Parse KEY=VALUE lines inside the managed block of an env file.
+export async function readManagedValues(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    const content = await readFile(filePath, "utf8");
+    const block = extractBlock(content);
+    if (block === null)
+        return {};
+    const values = {};
+    for (const line of block.split("\n")) {
+        const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+        if (match)
+            values[match[1]] = match[2];
+    }
+    return values;
+}
+// Merge values into the managed block, creating the file/block when missing.
+export async function upsertManagedValues(filePath, updates) {
+    const currentValues = await readManagedValues(filePath);
+    const mergedValues = { ...currentValues, ...updates };
+    const lines = Object.entries(mergedValues).map(([key, value]) => `${key}=${value}`);
+    const block = [BLOCK_START, ...lines, BLOCK_END].join("\n");
+    const existingContent = existsSync(filePath) ? await readFile(filePath, "utf8") : "";
+    await writeFile(filePath, replaceBlock(existingContent, block), "utf8");
+}
+// Replace the managed block wholly with exactly these values (sync semantics:
+// the server-side projection wins; stale entries disappear).
+export async function writeManagedValues(filePath, values) {
+    const lines = Object.entries(values).map(([key, value]) => `${key}=${value}`);
+    const block = [BLOCK_START, ...lines, BLOCK_END].join("\n");
+    const existingContent = existsSync(filePath) ? await readFile(filePath, "utf8") : "";
+    await writeFile(filePath, replaceBlock(existingContent, block), "utf8");
+}
+// Ensure .gitignore covers .env so managed secrets never get committed.
+export async function ensureEnvGitignored(cwd) {
+    const gitignorePath = path.join(cwd, ".gitignore");
+    const content = existsSync(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
+    const hasEnvRule = content
+        .split("\n")
+        .some((line) => [".env", "*.env", ".env*"].includes(line.trim()));
+    if (hasEnvRule)
+        return false;
+    const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+    await appendFile(gitignorePath, `${separator}.env\n`);
+    return true;
+}
+// Slice out the managed block's inner lines, or null when no block exists.
+function extractBlock(content) {
+    const start = content.indexOf(BLOCK_START);
+    const end = content.indexOf(BLOCK_END);
+    if (start === -1 || end === -1 || end < start)
+        return null;
+    return content.slice(start + BLOCK_START.length, end).trim();
+}
+// Swap the managed block in place, or append one to the end of the file.
+function replaceBlock(content, block) {
+    const start = content.indexOf(BLOCK_START);
+    const end = content.indexOf(BLOCK_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        return content.slice(0, start) + block + content.slice(end + BLOCK_END.length);
+    }
+    const separator = content === "" ? "" : content.endsWith("\n") ? "\n" : "\n\n";
+    return content + separator + block + "\n";
+}

package/dist/lib/interactive.js

@@ -0,0 +1,18 @@
+// packages/cli/src/lib/interactive.ts - Non-TTY guards for clack prompts: in
+// non-interactive contexts (CI, piped stdin) a prompt can never resolve, so
+// confirms fall back to the auto-bootstrap default (consumer-journey §9.5)
+// instead of hanging the process.
+import * as p from "@clack/prompts";
+// True when both stdin and stdout are attached to a terminal.
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+// Ask when interactive; otherwise log the default taken and return it.
+export async function confirmOrFallback(message, fallback) {
+    if (!isInteractive()) {
+        p.log.info(`${message} → ${fallback ? "yes" : "no"} (non-interactive default)`);
+        return fallback;
+    }
+    const answer = await p.confirm({ message });
+    return p.isCancel(answer) ? false : answer;
+}

package/dist/lib/manifest.js

@@ -0,0 +1,54 @@
+// packages/cli/src/lib/manifest.ts - Read and update the repo's
+// apollo.service.json (its consumes[] edges double as the application's bill
+// of materials, consumer-journey.md §7).
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+const MANIFEST_FILE = "apollo.service.json";
+// Absolute path of the manifest in the working directory.
+export function manifestPath(cwd) {
+    return path.join(cwd, MANIFEST_FILE);
+}
+export function hasManifest(cwd) {
+    return existsSync(manifestPath(cwd));
+}
+// Write a minimal, schema-valid single-service application manifest scaffold
+// (root description/repository are required with minLength/uri formats, so the
+// scaffold carries TODO placeholders rather than empty strings).
+export async function scaffoldManifest(cwd, repoName) {
+    const manifest = {
+        spec: "apollo.dev/v1",
+        name: repoName,
+        description: `TODO: describe ${repoName}`,
+        repository: `https://github.com/TODO/${repoName}`,
+        owner: "TODO",
+        services: [
+            {
+                name: repoName,
+                kind: "application",
+                type: "app",
+                version: "0.0.0",
+                status: "experimental",
+                description: `TODO: describe the ${repoName} application`,
+                application: { ui: "spa" },
+                consumes: [],
+            },
+        ],
+    };
+    await writeFile(manifestPath(cwd), JSON.stringify(manifest, null, 4) + "\n", "utf8");
+}
+// Append a consumes edge to the first service entry (no-op if already declared).
+export async function appendConsumesEdge(cwd, edge) {
+    const filePath = manifestPath(cwd);
+    const manifest = JSON.parse(await readFile(filePath, "utf8"));
+    const serviceEntry = manifest.services?.[0];
+    if (!serviceEntry)
+        throw new Error(`${MANIFEST_FILE} has no services[] entry`);
+    serviceEntry.consumes ??= [];
+    const isAlreadyDeclared = serviceEntry.consumes.some((existing) => existing.service === edge.service);
+    if (isAlreadyDeclared)
+        return false;
+    serviceEntry.consumes.push(edge);
+    await writeFile(filePath, JSON.stringify(manifest, null, 4) + "\n", "utf8");
+    return true;
+}

package/dist/lib/package_manager.js

@@ -0,0 +1,24 @@
+// packages/cli/src/lib/package_manager.ts - Detect the consumer repo's package
+// manager from its lockfile and run installs with it.
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+// Detect the package manager from the lockfile (pnpm-lock.yaml → pnpm, yarn.lock → yarn, default npm).
+export function detectPackageManager(cwd) {
+    if (existsSync(path.join(cwd, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(path.join(cwd, "yarn.lock")))
+        return "yarn";
+    return "npm";
+}
+// Install one package as a dependency, streaming the manager's own output.
+export function installPackage(manager, packageName, cwd) {
+    const args = manager === "npm" ? ["install", packageName] : ["add", packageName];
+    return new Promise((resolve, reject) => {
+        const child = spawn(manager, args, { cwd, stdio: "inherit" });
+        child.on("error", reject);
+        child.on("exit", (code) => code === 0
+            ? resolve()
+            : reject(new Error(`${manager} ${args.join(" ")} exited with code ${code}`)));
+    });
+}

package/dist/lib/schema_validator.js

@@ -0,0 +1,32 @@
+// packages/cli/src/lib/schema_validator.ts - Validate apollo.service.json
+// manifests against the apollo.dev/v1 JSON Schema (draft-07). The canonical
+// schema is copied from spec/schema.json into dist/ at build time so the
+// published CLI is self-contained; --schema overrides it.
+import { readFile } from "node:fs/promises";
+import { Ajv } from "ajv";
+import addFormatsImport from "ajv-formats";
+// ajv-formats ships CJS; under NodeNext resolution its callable surfaces as the
+// namespace object, so re-type it to the plugin function it is at runtime.
+const addFormats = addFormatsImport;
+// Load the schema: an explicit path/URL override, or the bundled copy.
+export async function loadSchema(override) {
+    if (override?.startsWith("http://") || override?.startsWith("https://")) {
+        const response = await fetch(override, { signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            throw new Error(`schema fetch failed: HTTP ${response.status}`);
+        return (await response.json());
+    }
+    const schemaUrl = override
+        ? new URL(override, `file://${process.cwd()}/`)
+        : new URL("../spec_schema.json", import.meta.url);
+    return JSON.parse(await readFile(schemaUrl, "utf8"));
+}
+// Validate a manifest object against the schema; returns human-readable errors.
+export function validateManifest(schema, manifest) {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const validate = ajv.compile(schema);
+    const isValid = validate(manifest);
+    const errors = (validate.errors ?? []).map((error) => `${error.instancePath || "/"} ${error.message ?? "invalid"}`);
+    return { isValid, errors };
+}