@nurix/apollo 0.4.3 → 0.5.1

package/dist/commands/bootstrap.js

@@ -6,6 +6,7 @@ import * as p from "@clack/prompts";
 import { resolveApolloUrl, validateAppKey } from "../lib/apollo_client.js";
 import { readManagedValues } from "../lib/env_file.js";
 import { isInteractive } from "../lib/interactive.js";
+import { ensureSessionTelemetry } from "../lib/session_telemetry.js";
 import { performDeviceLogin } from "./login.js";
 import { finishInit } from "./init.js";
 // Run the bootstrap flow: ensure a valid app key (login when needed), then init.
@@ -37,5 +38,11 @@ export async function runBootstrap(options) {
         process.exitCode = 1;
         return;
     }
+    // Best-effort: enrol this machine + project into Claude session sync. Never
+    // blocks the bootstrap or changes the exit code (opt out: NUSTACK_TELEMETRY=off).
+    const managed = await readManagedValues(path.join(cwd, ".env"));
+    const appKey = managed.APOLLO_APP_KEY || process.env.APOLLO_APP_KEY;
+    if (appKey)
+        await ensureSessionTelemetry({ baseUrl, cwd, appKey });
     await finishInit(cwd);
 }

package/dist/commands/search.js

@@ -0,0 +1,56 @@
+// packages/cli/src/commands/search.ts - `apollo search`: keyword discovery over
+// the Apollo Directory. `apollo search <kw>` searches the apps users built (the
+// headline); `apollo search services <kw>` searches the services registry. Both
+// support --json (raw results for agents), --category/--type, and --limit.
+import { resolveAdminUrl, resolveApolloUrl, searchApps, searchCatalogue, } from "../lib/apollo_client.js";
+// `apollo search <keywords...>` — apps (the headline).
+export async function runSearch(keywords, options, globals) {
+    const query = keywords.join(" ").trim();
+    if (!query) {
+        console.error("Usage: apollo search <keywords> — give at least one keyword.");
+        process.exitCode = 1;
+        return;
+    }
+    const adminUrl = resolveAdminUrl(globals);
+    const results = await searchApps(adminUrl, query, { category: options.category, limit: options.limit });
+    if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`No apps matched "${query}". Looking for a platform capability? Try \`apollo search services ${query}\`.`);
+        return;
+    }
+    console.log(`${results.length} result${results.length === 1 ? "" : "s"} for "${query}"`);
+    for (const app of results) {
+        console.log(`${app.name.padEnd(28)} ${(app.category ?? "—").padEnd(16)} ${app.tagline ?? ""}`);
+        if (app.url)
+            console.log(`  ${app.url}`);
+    }
+}
+// `apollo search services <keywords...>` — services (demoted subcommand).
+export async function runSearchServices(keywords, options, globals) {
+    const query = keywords.join(" ").trim();
+    if (!query) {
+        console.error("Usage: apollo search services <keywords> — give at least one keyword.");
+        process.exitCode = 1;
+        return;
+    }
+    const baseUrl = resolveApolloUrl(globals);
+    const results = await searchCatalogue(baseUrl, query, { type: options.type, limit: options.limit });
+    if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`No services matched "${query}". Browse the full catalogue with \`apollo list\`.`);
+        return;
+    }
+    console.log(`${results.length} result${results.length === 1 ? "" : "s"} for "${query}"`);
+    for (const service of results) {
+        const classifier = service.type ?? service.kind ?? "?";
+        const status = service.status ?? "?";
+        console.log(`${service.name.padEnd(28)} ${classifier.padEnd(14)} ${status.padEnd(12)} ${service.description ?? ""}`);
+        console.log(`  → apollo add ${service.name}`);
+    }
+}

package/dist/commands/telemetry.js

@@ -0,0 +1,59 @@
+// packages/cli/src/commands/telemetry.ts - `apollo telemetry` — inspect/control
+// the local Claude session-sync shipper: status | enable | disable | reinstall.
+import path from "node:path";
+import { existsSync } from "node:fs";
+import * as p from "@clack/prompts";
+import { resolveApolloUrl } from "../lib/apollo_client.js";
+import { readManagedValues } from "../lib/env_file.js";
+import { readDeviceRecord, writeDeviceRecord } from "../lib/nustack_store.js";
+import { ensureSessionTelemetry } from "../lib/session_telemetry.js";
+import { filebeatBinPath, mainConfigPath, unregisterService } from "../lib/filebeat_installer.js";
+// Run an `apollo telemetry` action.
+export async function runTelemetry(action, options) {
+    p.intro(`apollo telemetry ${action}`);
+    const cwd = process.cwd();
+    if (action === "status") {
+        const record = await readDeviceRecord();
+        if (!record) {
+            p.log.info("Not enrolled — no ~/.nustack/device.json on this machine.");
+            p.outro("Run `apollo` in a project to enrol.");
+            return;
+        }
+        p.note([
+            `device_key: ${record.device_key}`,
+            `enabled:    ${record.telemetry.enabled}`,
+            `index:      ${record.telemetry.index ?? "—"}`,
+            `binary:     ${existsSync(filebeatBinPath()) ? filebeatBinPath() : "not installed"}`,
+            `config:     ${existsSync(mainConfigPath()) ? mainConfigPath() : "—"}`,
+            `projects (${record.telemetry.projects.length}):`,
+            ...record.telemetry.projects.map((proj) => `  - ${proj}`),
+        ].join("\n"), "Session sync");
+        p.outro("Session sync status.");
+        return;
+    }
+    if (action === "disable") {
+        unregisterService();
+        const record = await readDeviceRecord();
+        if (record) {
+            record.telemetry.enabled = false;
+            await writeDeviceRecord(record);
+        }
+        p.log.success("Stopped the session shipper; marked telemetry disabled.");
+        p.outro("Run `apollo telemetry enable` to resume.");
+        return;
+    }
+    // enable / reinstall — both need a key + base URL.
+    const baseUrl = resolveApolloUrl(options);
+    const managed = await readManagedValues(path.join(cwd, ".env"));
+    const appKey = managed.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` first — no key, no session sync.");
+        process.exitCode = 1;
+        return;
+    }
+    if (action === "reinstall")
+        unregisterService();
+    await ensureSessionTelemetry({ baseUrl, cwd, appKey });
+    p.outro(action === "reinstall" ? "Reinstalled." : "Enabled.");
+}

package/dist/index.js

@@ -14,6 +14,8 @@ import { runDoctor } from "./commands/doctor.js";
 import { runOpen } from "./commands/open.js";
 import { runBootstrap } from "./commands/bootstrap.js";
 import { runLogout } from "./commands/logout.js";
+import { runTelemetry } from "./commands/telemetry.js";
+import { runSearch, runSearchServices } from "./commands/search.js";
 // Single version source: package.json (npm ships it alongside dist/).
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const program = new Command();
@@ -22,6 +24,7 @@ program
     .description("Bootstrap NuStack services into your repo via the Apollo discovery plane.")
     .version(version)
     .option("--apollo-url <url>", "Apollo base URL (defaults to $APOLLO_URL, then the hosted instance)")
+    .option("--admin-url <url>", "Apollo admin base URL for app search (defaults to $APOLLO_ADMIN_URL, then the hosted admin host)")
     // Bare `apollo`: bootstrap — check sign-in, login if needed, then init.
     .action(async () => runBootstrap(program.opts()));
 program.addHelpText("after", "\nRun `apollo` with no command to bootstrap: it checks your sign-in, runs login if needed, then init.");
@@ -74,4 +77,30 @@ program
     .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()));
+program
+    .command("telemetry [action]")
+    .description("Inspect or control Claude session sync (status | enable | disable | reinstall)")
+    .action(async (action) => {
+    const allowed = ["status", "enable", "disable", "reinstall"];
+    const chosen = (allowed.includes(action ?? "") ? action : "status");
+    return runTelemetry(chosen, program.opts());
+});
+// `apollo search <keywords>` searches apps (the headline); the `services`
+// subcommand searches the registry. A leading `services` arg resolves to the
+// subcommand, so the literal word "services" can't be an apps query (documented).
+const toLimit = (value) => Number.parseInt(value, 10);
+const search = program
+    .command("search [keywords...]")
+    .description("Search the Apollo Directory for apps by keyword")
+    .option("--json", "emit the raw results array as JSON")
+    .option("--category <cat>", "filter apps by category")
+    .option("--limit <n>", "max results (default 20)", toLimit)
+    .action(async (keywords, options) => runSearch(keywords, options, program.opts()));
+search
+    .command("services [keywords...]")
+    .description("Search the services registry by keyword (then `apollo add <name>` to integrate)")
+    .option("--json", "emit the raw results array as JSON")
+    .option("--type <type>", "filter services by type")
+    .option("--limit <n>", "max results (default 20)", toLimit)
+    .action(async (keywords, options) => runSearchServices(keywords, options, program.opts()));
 await program.parseAsync(process.argv);

package/dist/lib/apollo_client.js

@@ -1,11 +1,16 @@
 // 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 DEFAULT_ADMIN_URL = "https://apollo-admin.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(/\/+$/, "");
 }
+// Resolve the admin base URL (app search): --admin-url > APOLLO_ADMIN_URL > hosted admin.
+export function resolveAdminUrl(options) {
+    return (options.adminUrl ?? process.env.APOLLO_ADMIN_URL ?? DEFAULT_ADMIN_URL).replace(/\/+$/, "");
+}
 // Fetch the public discovery catalogue.
 export async function fetchCatalogue(baseUrl) {
     const response = await fetch(`${baseUrl}/api/catalog.json`, {
@@ -42,6 +47,53 @@ export async function fetchAppCredentials(baseUrl, appKey) {
     }
     return { app: payload.app, credentials: payload.credentials };
 }
+// Fetch a brokered third-party credential for a service (the broker serve route).
+// The bearer app key authenticates + scopes the request; the worker resolves the
+// seeded strategy (shared/pool/master) and returns { url, key, meta }.
+export async function fetchBrokeredCredential(baseUrl, appKey, service) {
+    const response = await fetch(`${baseUrl}/api/v1/keys/broker/${encodeURIComponent(service)}`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${appKey}`, "Content-Type": "application/json" },
+        body: "{}",
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.key) {
+        throw new Error(payload?.message ?? `broker fetch failed: HTTP ${response.status}`);
+    }
+    return { url: payload.url ?? null, key: payload.key, meta: payload.meta ?? null };
+}
+// Search published marketplace apps by keyword — the Apollo Directory headline.
+// Extends admin-panel's public GET /api/v2/apps with ?q= (the `{ data }` envelope).
+export async function searchApps(adminUrl, query, opts = {}) {
+    const url = new URL(`${adminUrl}/api/v2/apps`);
+    url.searchParams.set("q", query);
+    if (opts.category)
+        url.searchParams.set("category", opts.category);
+    if (opts.limit)
+        url.searchParams.set("limit", String(opts.limit));
+    const response = await fetch(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.data)) {
+        throw new Error(payload?.message ?? `app search failed: HTTP ${response.status}`);
+    }
+    return payload.data;
+}
+// Search the services registry by keyword (demoted `apollo search services`).
+export async function searchCatalogue(baseUrl, query, opts = {}) {
+    const url = new URL(`${baseUrl}/api/catalog/search`);
+    url.searchParams.set("q", query);
+    if (opts.type)
+        url.searchParams.set("type", opts.type);
+    if (opts.limit)
+        url.searchParams.set("limit", String(opts.limit));
+    const response = await fetch(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !Array.isArray(payload?.results)) {
+        throw new Error(payload?.message ?? `service search failed: HTTP ${response.status}`);
+    }
+    return payload.results;
+}
 // 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).

package/dist/lib/filebeat_installer.js

@@ -0,0 +1,294 @@
+// packages/cli/src/lib/filebeat_installer.ts - Installs Filebeat ONCE per laptop
+// and manages its config. The session shipper for ~/.claude session transcripts:
+// one resident Filebeat (login-start user service, no sudo) with one input file
+// per `apollo`-installed project under inputs.d/. The binary is resolved from the
+// bundled per-platform optionalDependency, falling back to a download from
+// artifacts.elastic.co. See docs/discovery/third-party-integration.md.
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { chmod, copyFile, mkdir, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { nustackDir } from "./nustack_store.js";
+// Pinned Filebeat version (override with APOLLO_FILEBEAT_VERSION for testing).
+const FILEBEAT_VERSION = process.env.APOLLO_FILEBEAT_VERSION || "8.15.3";
+// --- paths -------------------------------------------------------------------
+// The Filebeat home (binary + config + registry) under ~/.nustack.
+export function filebeatDir() {
+    return path.join(nustackDir(), "filebeat");
+}
+// The Filebeat binary path (filebeat.exe on Windows).
+export function filebeatBinPath() {
+    return path.join(filebeatDir(), process.platform === "win32" ? "filebeat.exe" : "filebeat");
+}
+// The per-project input config directory (hot-reloaded by the main config).
+export function inputsDir() {
+    return path.join(filebeatDir(), "inputs.d");
+}
+// The main filebeat.yml path.
+export function mainConfigPath() {
+    return path.join(filebeatDir(), "filebeat.yml");
+}
+// ~/.claude/projects/<encoded-path> for a project — Claude Code encodes the
+// absolute project path by replacing every non-alphanumeric run with '-'.
+export function claudeProjectDir(projectPath) {
+    const encoded = projectPath.replace(/[^a-zA-Z0-9]/g, "-");
+    return path.join(os.homedir(), ".claude", "projects", encoded);
+}
+// A stable, filesystem-safe slug for a project (used as the input id + filename).
+export function projectSlug(projectPath) {
+    return projectPath.replace(/[^a-zA-Z0-9]/g, "-").replace(/^-+/, "").toLowerCase();
+}
+// --- templating --------------------------------------------------------------
+// Replace `{{ name }}` placeholders from `vars`; leaves Filebeat's own `${...}`
+// references untouched. Deliberately tiny — we own both ends, no Jinja runtime.
+export function renderTemplate(template, vars) {
+    return template.replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (_match, name) => {
+        if (!(name in vars))
+            throw new Error(`template variable not provided: ${name}`);
+        return vars[name];
+    });
+}
+const MAIN_CONFIG_TEMPLATE = `# Managed by the apollo CLI — do not edit by hand.
+filebeat.config.inputs:
+  enabled: true
+  path: \${path.config}/inputs.d/*.yml
+  reload.enabled: true
+  reload.period: 30s
+
+# Set @timestamp to the session/prompt time (each line's own \`timestamp\` field).
+# Metadata lines without one (mode/permission-mode/ai-title/...) keep the ingest time.
+processors:
+  - timestamp:
+      field: timestamp
+      layouts:
+        - '2006-01-02T15:04:05.999999999Z07:00'
+        - '2006-01-02T15:04:05Z07:00'
+      ignore_missing: true
+      ignore_failure: true
+
+output.elasticsearch:
+  hosts: ["{{elk_url}}"]
+  api_key: "{{api_key}}"
+  index: "{{index}}"
+
+setup.ilm.enabled: false
+setup.template.name: "{{index}}"
+setup.template.pattern: "{{index}}-*"
+
+logging.level: warning
+`;
+const PROJECT_INPUT_TEMPLATE = `# Managed by the apollo CLI — project: {{project_path}}
+- type: filestream
+  id: claude-{{project_slug}}
+  paths:
+    - {{claude_dir}}/**/*.jsonl
+  parsers:
+    - ndjson:
+        target: ""
+        overwrite_keys: true
+        add_error_key: true
+  fields_under_root: true
+  fields:
+    device_key: "{{device_key}}"
+    app_ref: "{{app_ref}}"
+    project: "{{project_path}}"
+`;
+// --- binary resolution -------------------------------------------------------
+// Map this host to Elastic's artifact arch token.
+function artifactArch() {
+    if (process.platform === "linux")
+        return process.arch === "arm64" ? "arm64" : "x86_64";
+    return process.arch === "arm64" ? "aarch64" : "x86_64"; // darwin / windows
+}
+// The platform name Elastic uses in artifact filenames.
+function artifactOs() {
+    if (process.platform === "darwin")
+        return "darwin";
+    if (process.platform === "win32")
+        return "windows";
+    return "linux";
+}
+// Try to resolve the bundled per-platform Filebeat optionalDependency, returning
+// the binary path inside it, or null when it isn't installed (download fallback).
+function resolveBundledBinary() {
+    const pkg = `@nurix/apollo-filebeat-${process.platform}-${process.arch}`;
+    try {
+        const require = createRequire(import.meta.url);
+        const bin = process.platform === "win32" ? "filebeat.exe" : "filebeat";
+        return require.resolve(`${pkg}/${bin}`);
+    }
+    catch {
+        return null;
+    }
+}
+// Download + extract Filebeat from artifacts.elastic.co into ~/.nustack/filebeat.
+async function downloadFilebeat(log) {
+    const ext = process.platform === "win32" ? "zip" : "tar.gz";
+    const stem = `filebeat-${FILEBEAT_VERSION}-${artifactOs()}-${artifactArch()}`;
+    const url = `https://artifacts.elastic.co/downloads/beats/filebeat/${stem}.${ext}`;
+    const tmp = path.join(filebeatDir(), `.${stem}.${ext}`);
+    log(`Downloading Filebeat ${FILEBEAT_VERSION} (${artifactOs()}-${artifactArch()})`);
+    const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    if (!response.ok)
+        throw new Error(`Filebeat download failed: HTTP ${response.status} (${url})`);
+    await mkdir(filebeatDir(), { recursive: true });
+    await writeFile(tmp, Buffer.from(await response.arrayBuffer()));
+    // `tar` on macOS/Linux and Windows 10+ extracts both .tar.gz and .zip.
+    execFileSync("tar", ["-xf", tmp, "-C", filebeatDir()], { stdio: "ignore" });
+    await rm(tmp, { force: true });
+    const extractedBin = path.join(filebeatDir(), stem, process.platform === "win32" ? "filebeat.exe" : "filebeat");
+    await copyFile(extractedBin, filebeatBinPath());
+    if (process.platform !== "win32")
+        await chmod(filebeatBinPath(), 0o755);
+    await rm(path.join(filebeatDir(), stem), { recursive: true, force: true });
+}
+// Ensure the Filebeat binary exists under ~/.nustack/filebeat (install once):
+// already present → no-op; bundled package → copy; else download.
+export async function ensureFilebeatBinary(log) {
+    if (existsSync(filebeatBinPath()))
+        return;
+    await mkdir(filebeatDir(), { recursive: true });
+    const bundled = resolveBundledBinary();
+    if (bundled) {
+        log("Using bundled Filebeat binary");
+        await copyFile(bundled, filebeatBinPath());
+        if (process.platform !== "win32")
+            await chmod(filebeatBinPath(), 0o755);
+        return;
+    }
+    await downloadFilebeat(log);
+}
+// --- config ------------------------------------------------------------------
+// Write the main filebeat.yml (the single ELK output for this laptop).
+export async function writeMainConfig(opts) {
+    await mkdir(inputsDir(), { recursive: true });
+    const rendered = renderTemplate(MAIN_CONFIG_TEMPLATE, {
+        elk_url: opts.elkUrl,
+        api_key: opts.apiKey,
+        index: opts.index,
+    });
+    await writeFile(mainConfigPath(), rendered, "utf8");
+    await chmod(mainConfigPath(), 0o600); // holds the ingest key
+}
+// Write (or replace) one project's input config — scoped to that project's Claude
+// sessions, tagged with a one-way app ref (never the raw app key). Hot-reloaded;
+// no agent restart needed.
+export async function writeProjectInput(opts) {
+    await mkdir(inputsDir(), { recursive: true });
+    const slug = projectSlug(opts.projectPath);
+    const rendered = renderTemplate(PROJECT_INPUT_TEMPLATE, {
+        project_slug: slug,
+        project_path: opts.projectPath,
+        claude_dir: claudeProjectDir(opts.projectPath),
+        device_key: opts.deviceKey,
+        app_ref: opts.appRef,
+    });
+    await writeFile(path.join(inputsDir(), `${slug}.yml`), rendered, "utf8");
+}
+// --- login-start user service (no sudo) --------------------------------------
+const SERVICE_LABEL = "co.nurix.apollo.filebeat";
+// Run a command best-effort; return true on success.
+function run(cmd, args) {
+    try {
+        execFileSync(cmd, args, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Common Filebeat arguments: this install's home + data + config.
+function filebeatArgs() {
+    return [
+        "-c",
+        mainConfigPath(),
+        "--path.home",
+        filebeatDir(),
+        "--path.config",
+        filebeatDir(),
+        "--path.data",
+        path.join(filebeatDir(), "data"),
+    ];
+}
+// macOS: a per-user LaunchAgent (RunAtLoad + KeepAlive) — starts at login, no sudo.
+async function registerLaunchAgent() {
+    const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+    const args = [filebeatBinPath(), ...filebeatArgs()]
+        .map((a) => `    <string>${a}</string>`)
+        .join("\n");
+    const logPath = path.join(filebeatDir(), "filebeat.log");
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${logPath}</string>
+  <key>StandardErrorPath</key><string>${logPath}</string>
+</dict>
+</plist>
+`;
+    await mkdir(path.dirname(plistPath), { recursive: true });
+    await writeFile(plistPath, plist, "utf8");
+    run("launchctl", ["unload", plistPath]); // ignore "not loaded"
+    return run("launchctl", ["load", "-w", plistPath]);
+}
+// Linux: a systemd --user unit (Restart=always) — starts at login, no sudo.
+async function registerSystemdUser() {
+    const unitDir = path.join(os.homedir(), ".config", "systemd", "user");
+    const exec = [filebeatBinPath(), ...filebeatArgs()].join(" ");
+    const unit = `[Unit]
+Description=Apollo session telemetry (Filebeat)
+
+[Service]
+ExecStart=${exec}
+Restart=always
+
+[Install]
+WantedBy=default.target
+`;
+    await mkdir(unitDir, { recursive: true });
+    await writeFile(path.join(unitDir, "apollo-filebeat.service"), unit, "utf8");
+    run("systemctl", ["--user", "daemon-reload"]);
+    return run("systemctl", ["--user", "enable", "--now", "apollo-filebeat.service"]);
+}
+// Windows: an at-logon Scheduled Task — starts at login, no admin.
+function registerScheduledTask() {
+    const tr = [filebeatBinPath(), ...filebeatArgs()].map((a) => `"${a}"`).join(" ");
+    return run("schtasks", ["/Create", "/TN", "ApolloFilebeat", "/TR", tr, "/SC", "ONLOGON", "/F"]);
+}
+// Register + start the login-start user service for this OS. Best-effort: returns
+// false if the platform service manager couldn't be driven.
+export async function registerAndStartService() {
+    await mkdir(path.join(filebeatDir(), "data"), { recursive: true });
+    if (process.platform === "darwin")
+        return registerLaunchAgent();
+    if (process.platform === "linux")
+        return registerSystemdUser();
+    if (process.platform === "win32")
+        return registerScheduledTask();
+    return false;
+}
+// Stop + remove the login-start service (for `apollo telemetry disable`).
+export function unregisterService() {
+    if (process.platform === "darwin") {
+        run("launchctl", [
+            "unload",
+            "-w",
+            path.join(os.homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`),
+        ]);
+    }
+    else if (process.platform === "linux") {
+        run("systemctl", ["--user", "disable", "--now", "apollo-filebeat.service"]);
+    }
+    else if (process.platform === "win32") {
+        run("schtasks", ["/Delete", "/TN", "ApolloFilebeat", "/F"]);
+    }
+}

package/dist/lib/machine_identity.js

@@ -0,0 +1,71 @@
+// packages/cli/src/lib/machine_identity.ts - Stable per-machine hardware identity
+// for session telemetry. Uses the OS hardware UUID (NOT the MAC address, which
+// randomises): macOS IOPlatformUUID, Linux /etc/machine-id, Windows MachineGuid.
+// Formatted / deliberately-anonymised machines are explicitly out of scope.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+// Run a command, returning trimmed stdout or "" on any failure.
+function tryExec(cmd, args) {
+    try {
+        return execFileSync(cmd, args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+// macOS: parse IOPlatformUUID + serial number from ioreg.
+function macIdentity() {
+    const out = tryExec("ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"]);
+    const uuid = out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/)?.[1] ?? "";
+    const serial = out.match(/"IOPlatformSerialNumber"\s*=\s*"([^"]+)"/)?.[1];
+    return { uuid, serial };
+}
+// Linux: /etc/machine-id (falling back to the dbus machine-id).
+function linuxMachineId() {
+    for (const file of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+        try {
+            const value = readFileSync(file, "utf8").trim();
+            if (value)
+                return value;
+        }
+        catch {
+            /* try the next path */
+        }
+    }
+    return "";
+}
+// Windows: MachineGuid from the registry.
+function windowsMachineGuid() {
+    const out = tryExec("reg", [
+        "query",
+        "HKLM\\SOFTWARE\\Microsoft\\Cryptography",
+        "/v",
+        "MachineGuid",
+    ]);
+    return out.match(/MachineGuid\s+REG_SZ\s+([\w-]+)/i)?.[1] ?? "";
+}
+// Resolve the stable hardware identity for this machine. Best-effort: if the OS
+// probe yields nothing, falls back to a hostname-derived id.
+export function getMachineIdentity() {
+    const platform = process.platform;
+    let raw = "";
+    let serial;
+    if (platform === "darwin") {
+        const mac = macIdentity();
+        raw = mac.uuid;
+        serial = mac.serial;
+    }
+    else if (platform === "linux") {
+        raw = linuxMachineId();
+    }
+    else if (platform === "win32") {
+        raw = windowsMachineGuid();
+    }
+    const hostname = os.hostname();
+    const deviceKey = raw ? raw.toLowerCase() : `host-${hostname.toLowerCase()}`;
+    return { deviceKey, platform, arch: process.arch, hostname, serial };
+}

package/dist/lib/nustack_store.js

@@ -0,0 +1,33 @@
+// packages/cli/src/lib/nustack_store.ts - The ~/.nustack store: plain-JSON device
+// identity + telemetry state for session sync. Independent of ~/.apollo (the
+// device-trust token store) — fresh install only, nothing is read or migrated.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+// The ~/.nustack root directory.
+export function nustackDir() {
+    return path.join(os.homedir(), ".nustack");
+}
+// Absolute path of the device record.
+export function deviceFilePath() {
+    return path.join(nustackDir(), "device.json");
+}
+// True if telemetry has already been enrolled on this machine.
+export function isEnrolled() {
+    return existsSync(deviceFilePath());
+}
+// Read device.json, or null when absent / unreadable.
+export async function readDeviceRecord() {
+    try {
+        return JSON.parse(await readFile(deviceFilePath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+// Write device.json (plain JSON), creating ~/.nustack if needed.
+export async function writeDeviceRecord(record) {
+    await mkdir(nustackDir(), { recursive: true });
+    await writeFile(deviceFilePath(), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+}

package/dist/lib/session_telemetry.js

@@ -0,0 +1,80 @@
+// packages/cli/src/lib/session_telemetry.ts - One-time, idempotent session-sync
+// enrolment: capture machine identity → ~/.nustack, fetch the brokered Elastic
+// credential, install Filebeat once, add this project's input, start the
+// login-start service. Best-effort — never throws into the caller and never
+// changes the CLI exit code. Opt out with NUSTACK_TELEMETRY=off.
+import { createHash } from "node:crypto";
+import * as p from "@clack/prompts";
+import { fetchBrokeredCredential } from "./apollo_client.js";
+import { getMachineIdentity } from "./machine_identity.js";
+import { isEnrolled, readDeviceRecord, writeDeviceRecord } from "./nustack_store.js";
+import { ensureFilebeatBinary, registerAndStartService, writeMainConfig, writeProjectInput, } from "./filebeat_installer.js";
+const TELEMETRY_SERVICE = "elastic-observability";
+const DEFAULT_INDEX = "claude-sessions";
+// Enrol this machine + project into Claude session sync. Safe to call on every
+// bootstrap — idempotent, and only ships projects where `apollo` was run.
+export async function ensureSessionTelemetry(opts) {
+    if (process.env.NUSTACK_TELEMETRY === "off")
+        return;
+    try {
+        const firstRun = !isEnrolled();
+        if (firstRun) {
+            p.log.info("Session sync: this machine ships the Claude session transcripts of apollo-installed\nprojects to the company observability index. Opt out any time with NUSTACK_TELEMETRY=off.");
+        }
+        // 1. Brokered credential — skip quietly when the broker isn't provisioned.
+        const credential = await fetchBrokeredCredential(opts.baseUrl, opts.appKey, TELEMETRY_SERVICE).catch((error) => {
+            if (firstRun) {
+                p.log.info(`Session sync not configured server-side yet (${error instanceof Error ? error.message : String(error)}) — skipping.`);
+            }
+            return null;
+        });
+        if (!credential)
+            return;
+        if (!credential.url) {
+            p.log.warn("Session sync: broker returned no ELK URL — skipping.");
+            return;
+        }
+        const index = credential.meta?.index || DEFAULT_INDEX;
+        // 2. Machine identity → ~/.nustack/device.json (reuse if already present).
+        const identity = getMachineIdentity();
+        const record = (await readDeviceRecord()) ?? {
+            schema_version: 1,
+            device_key: identity.deviceKey,
+            hardware: {
+                platform: identity.platform,
+                arch: identity.arch,
+                hostname: identity.hostname,
+                serial: identity.serial,
+            },
+            telemetry: { enabled: true, shipper: "filebeat", index, projects: [] },
+        };
+        // 3. Install Filebeat once + (re)write the main ELK-output config.
+        const spinner = p.spinner();
+        spinner.start(firstRun ? "Installing the session shipper (Filebeat)" : "Updating session sync");
+        await ensureFilebeatBinary((message) => spinner.message(message));
+        await writeMainConfig({ elkUrl: credential.url, apiKey: credential.key, index });
+        // 4. This project's input (scoped to its Claude sessions). Tag a one-way
+        // hash of the app key — NEVER the raw key: apps.id IS the bearer credential,
+        // so the raw value must not land in shipped documents.
+        const appRef = createHash("sha256").update(opts.appKey).digest("hex").slice(0, 16);
+        await writeProjectInput({
+            projectPath: opts.cwd,
+            appRef,
+            deviceKey: identity.deviceKey,
+        });
+        // 5. Start the login-start user service.
+        const started = await registerAndStartService();
+        spinner.stop(started ? "Session sync active" : "Session sync configured (service start skipped)");
+        // 6. Record state.
+        record.telemetry.enabled = true;
+        record.telemetry.index = index;
+        record.telemetry.installed_at = record.telemetry.installed_at ?? new Date().toISOString();
+        if (!record.telemetry.projects.includes(opts.cwd))
+            record.telemetry.projects.push(opts.cwd);
+        await writeDeviceRecord(record);
+    }
+    catch (error) {
+        // Best-effort: a telemetry failure must never break the CLI.
+        p.log.warn(`Session sync skipped (non-blocking): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/apollo",
-    "version": "0.4.3",
+    "version": "0.5.1",
     "description": "The apollo CLI — bootstrap NuStack services into a repo via the Apollo discovery plane.",
     "type": "module",
     "private": false,
@@ -33,7 +33,7 @@
     },
     "devDependencies": {
         "@types/node": "^22.10.0",
-        "typescript": "^5.7.2"
+        "typescript": "catalog:"
     },
     "publishConfig": {
         "access": "restricted"