@agent-native/core 0.112.0 → 0.114.0

package/src/cli/telemetry.ts

@@ -0,0 +1,136 @@
+/**
+ * Best-effort install-funnel telemetry for the core CLI.
+ *
+ * Events are POSTed to the first-party Agent Native Analytics endpoint
+ * (analytics.agent-native.com/track) using a PUBLIC, write-only key — the same
+ * mechanism every agent-native app uses to report client-side events. Nothing
+ * here ever blocks or throws into the install flow: sends are fire-and-forget
+ * and `flush()` awaits any in-flight requests with a short cap before exit.
+ *
+ * Privacy: we report skill NAMES, client ids, scope, counts, platform, and the
+ * CLI version — never file paths, repo names, cwd, skill sources, or anything
+ * user-identifying. A random per-machine install id (unique installs) and a
+ * per-invocation run id (step-by-step dropoff) are the only identifiers.
+ *
+ * Opt out with DO_NOT_TRACK=1 or AGENT_NATIVE_TELEMETRY_DISABLED=1.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Public, write-only analytics key. Safe to embed (revocable from the Analytics
+// settings UI). Override with AGENT_NATIVE_ANALYTICS_PUBLIC_KEY for testing or
+// to point telemetry at a different first-party analytics instance.
+// guard:allow-public-key -- first-party analytics write key is public by design.
+const EMBEDDED_PUBLIC_KEY =
+  "anpk_dc523e34b99bc34d76e82d94c46593544e4a8509a4bfc93c";
+const DEFAULT_ENDPOINT = "https://analytics.agent-native.com/track";
+const FLUSH_TIMEOUT_MS = 1500;
+
+export interface CliTelemetryOptions {
+  /** Stable identifier for the emitting CLI, e.g. "skills-installer". */
+  cli: string;
+  cliVersion: string;
+  command: string;
+  interactive: boolean;
+}
+
+export interface CliTelemetry {
+  track(event: string, properties?: Record<string, unknown>): void;
+  flush(): Promise<void>;
+}
+
+function resolvePublicKey(): string {
+  const fromEnv = process.env.AGENT_NATIVE_ANALYTICS_PUBLIC_KEY?.trim();
+  return fromEnv || EMBEDDED_PUBLIC_KEY;
+}
+
+function resolveEndpoint(): string {
+  const fromEnv = process.env.AGENT_NATIVE_ANALYTICS_ENDPOINT?.trim();
+  return (fromEnv || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+}
+
+function telemetryDisabled(): boolean {
+  return (
+    process.env.DO_NOT_TRACK === "1" ||
+    process.env.AGENT_NATIVE_TELEMETRY_DISABLED === "1" ||
+    process.env.NODE_ENV === "test" ||
+    typeof fetch !== "function"
+  );
+}
+
+/**
+ * Read (or lazily create) a stable per-machine install id, shared across both
+ * skills CLIs so one developer counts once. Best-effort: an unwritable home
+ * directory just yields an ephemeral id for this run.
+ */
+function resolveInstallId(): string {
+  try {
+    const dir = path.join(os.homedir(), ".agent-native");
+    const file = path.join(dir, "installation-id");
+    const existing = fs.existsSync(file)
+      ? fs.readFileSync(file, "utf8").trim()
+      : "";
+    if (existing) return existing;
+    const id = crypto.randomUUID();
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, `${id}\n`, "utf8");
+    return id;
+  } catch {
+    return crypto.randomUUID();
+  }
+}
+
+export function createCliTelemetry(options: CliTelemetryOptions): CliTelemetry {
+  const publicKey = resolvePublicKey();
+  const disabled = telemetryDisabled() || !publicKey;
+  const endpoint = resolveEndpoint();
+  const installId = disabled ? "" : resolveInstallId();
+  const runId = crypto.randomUUID();
+  const inFlight = new Set<Promise<void>>();
+
+  const base = {
+    cli: options.cli,
+    cliVersion: options.cliVersion,
+    command: options.command,
+    node: process.version,
+    platform: process.platform,
+    ci: process.env.CI === "true",
+    interactive: options.interactive,
+    runId,
+    installId,
+  };
+
+  function track(event: string, properties?: Record<string, unknown>): void {
+    if (disabled) return;
+    const body = JSON.stringify({
+      publicKey,
+      event,
+      anonymousId: installId,
+      sessionId: runId,
+      timestamp: new Date().toISOString(),
+      properties: { ...base, ...properties },
+    });
+    const promise = fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      keepalive: true,
+    })
+      .then(() => undefined)
+      .catch(() => undefined);
+    inFlight.add(promise);
+    void promise.finally(() => inFlight.delete(promise));
+  }
+
+  async function flush(): Promise<void> {
+    if (disabled || inFlight.size === 0) return;
+    await Promise.race([
+      Promise.allSettled([...inFlight]),
+      new Promise((resolve) => setTimeout(resolve, FLUSH_TIMEOUT_MS)),
+    ]);
+  }
+
+  return { track, flush };
+}

package/src/cli/templates-meta.ts

@@ -0,0 +1,269 @@
+/**
+ * First-party template metadata used by the `agent-native` CLI.
+ *
+ * This file is intentionally inlined here (rather than imported from a
+ * separate workspace package) so that the published `@agent-native/core`
+ * has no `workspace:*` runtime dependencies. Without this inlining, `npx
+ * @agent-native/core create ...` fails on a fresh machine with:
+ *
+ *   npm error code EUNSUPPORTEDPROTOCOL
+ *   npm error Unsupported URL Type "workspace:": workspace:*
+ *
+ * Keep this list in sync with `packages/shared-app-config/templates.ts`,
+ * which serves the same metadata to the desktop / mobile / frame packages
+ * that always run inside the workspace. Duplication is intentional: the
+ * CLI must remain installable outside the monorepo.
+ */
+
+export interface TemplateMeta {
+  /** Directory name under templates/ and package name */
+  name: string;
+  /** Display name in pickers */
+  label: string;
+  /** One-line description shown in the picker */
+  hint: string;
+  /** Longer description (optional) */
+  description?: string;
+  /** Tabler icon name used in the desktop sidebar */
+  icon: string;
+  /** Hex accent color */
+  color: string;
+  /** CSS-safe RGB triplet (e.g. "59 130 246") */
+  colorRgb: string;
+  /** Dev server port for desktop `pnpm dev` */
+  devPort: number;
+  /** Production URL when running as a first-party app on agent-native.com */
+  prodUrl?: string;
+  /** Default URL path when deployed in a workspace (defaults to "/<name>") */
+  prodPath?: string;
+  /** Default mode when added to desktop app */
+  defaultMode?: "dev" | "prod";
+  /** Hide from pickers but still scaffoldable via explicit --template */
+  hidden?: boolean;
+  /** Include as a built-in connected A2A agent even when hidden from pickers */
+  defaultAgent?: boolean;
+  /** Always scaffold without prompting (e.g. chat as fallback) */
+  alwaysAvailable?: boolean;
+  /** Internal workspace packages this template depends on (e.g. "scheduling") */
+  requiredPackages?: string[];
+  /** Core app — featured in the CLI picker, homepage, and docs gallery */
+  core?: boolean;
+}
+
+export const TEMPLATES: TemplateMeta[] = [
+  {
+    name: "calendar",
+    label: "Calendar",
+    hint: "Agent-native Google Calendar — manage events, sync, and public booking",
+    icon: "CalendarDays",
+    color: "#00B5FF",
+    colorRgb: "0 181 255",
+    devPort: 8082,
+    prodUrl: "https://calendar.agent-native.com",
+    defaultMode: "prod",
+    requiredPackages: ["scheduling"],
+    core: true,
+  },
+  {
+    name: "content",
+    label: "Content",
+    hint: "Open-source Obsidian for MDX — edit local docs with agent assistance",
+    icon: "FileText",
+    color: "#10B981",
+    colorRgb: "16 185 129",
+    devPort: 8083,
+    prodUrl: "https://content.agent-native.com",
+    defaultMode: "prod",
+    requiredPackages: ["creative-context"],
+    core: true,
+  },
+  {
+    name: "plan",
+    label: "Plan",
+    hint: "Structured visual plans and PR recaps with diagrams, wireframes, prototypes, annotations, and sharing",
+    icon: "FileText",
+    color: "#52525B",
+    colorRgb: "82 82 91",
+    devPort: 8105,
+    prodUrl: "https://plan.agent-native.com",
+    defaultMode: "prod",
+    core: true,
+  },
+  {
+    name: "slides",
+    label: "Slides",
+    hint: "Agent-native Google Slides — generate and edit React presentations",
+    icon: "GalleryHorizontal",
+    color: "#EC4899",
+    colorRgb: "236 72 153",
+    devPort: 8086,
+    prodUrl: "https://slides.agent-native.com",
+    defaultMode: "prod",
+    requiredPackages: ["pinpoint", "creative-context"],
+    core: true,
+  },
+  {
+    name: "analytics",
+    label: "Analytics",
+    hint: "Agent-native Amplitude/Mixpanel — connect data sources, prompt for charts",
+    icon: "BarChart2",
+    color: "#F59E0B",
+    colorRgb: "245 158 11",
+    devPort: 8088,
+    prodUrl: "https://analytics.agent-native.com",
+    defaultMode: "prod",
+    core: true,
+  },
+  {
+    name: "mail",
+    label: "Mail",
+    hint: "Agent-native Superhuman — email client with keyboard shortcuts and AI triage",
+    icon: "Mail",
+    color: "#3B82F6",
+    colorRgb: "59 130 246",
+    devPort: 8085,
+    prodUrl: "https://mail.agent-native.com",
+    defaultMode: "prod",
+    core: true,
+  },
+  {
+    name: "dispatch",
+    label: "Dispatch",
+    hint: "Central Slack/Telegram router with jobs, memory, approvals, and A2A delegation",
+    icon: "MessageCircle",
+    color: "#14B8A6",
+    colorRgb: "20 184 166",
+    devPort: 8092,
+    prodUrl: "https://dispatch.agent-native.com",
+    defaultMode: "prod",
+    core: true,
+  },
+  {
+    name: "forms",
+    label: "Forms",
+    hint: "Agent-native form builder — create, edit, and manage forms",
+    icon: "ClipboardList",
+    color: "#06B6D4",
+    colorRgb: "6 182 212",
+    devPort: 8084,
+    prodUrl: "https://forms.agent-native.com",
+    defaultMode: "prod",
+    core: true,
+  },
+  {
+    name: "chat",
+    label: "Chat",
+    hint: "Minimal chat-first app with durable threads, actions, and the app-agent loop",
+    icon: "MessageCircle",
+    color: "#18181B",
+    colorRgb: "24 24 27",
+    devPort: 8089,
+    prodUrl: "https://chat.agent-native.com",
+    defaultMode: "prod",
+    alwaysAvailable: true,
+    core: true,
+  },
+  {
+    name: "clips",
+    label: "Clips",
+    hint: "Screen recording, meeting notes, and voice dictation — all with AI",
+    icon: "ScreenShare",
+    color: "#0EA5E9",
+    colorRgb: "14 165 233",
+    devPort: 8094,
+    prodUrl: "https://clips.agent-native.com",
+    defaultMode: "prod",
+    core: true,
+  },
+  {
+    name: "brain",
+    label: "Brain",
+    hint: "Cited company knowledge from Slack, meetings, transcripts, and decisions",
+    icon: "Brain",
+    color: "#8B5CF6",
+    colorRgb: "139 92 246",
+    devPort: 8102,
+    prodUrl: "https://brain.agent-native.com",
+    defaultMode: "prod",
+    defaultAgent: true,
+    core: true,
+  },
+  {
+    name: "design",
+    label: "Design",
+    hint: "Agent-native design tool — create and edit visual designs with agent assistance",
+    icon: "Brush",
+    color: "#F472B6",
+    colorRgb: "244 114 182",
+    devPort: 8099,
+    prodUrl: "https://design.agent-native.com",
+    defaultMode: "prod",
+    requiredPackages: ["pinpoint", "embedding", "creative-context"],
+    core: true,
+  },
+  {
+    name: "assets",
+    label: "Assets",
+    hint: "Digital asset manager — upload, organize, search, and generate on-brand images and videos",
+    icon: "Photo",
+    color: "#0F766E",
+    colorRgb: "15 118 110",
+    devPort: 8100,
+    prodUrl: "https://assets.agent-native.com",
+    defaultMode: "prod",
+    defaultAgent: true,
+    requiredPackages: ["embedding", "creative-context"],
+    core: true,
+  },
+  {
+    name: "tasks",
+    label: "Tasks",
+    hint: "Task-list-first workspace — inbox capture, custom fields, and drag-and-drop ordering",
+    icon: "ListCheck",
+    color: "#6366F1",
+    colorRgb: "99 102 241",
+    devPort: 8091,
+    prodUrl: "https://tasks.agent-native.com",
+    defaultMode: "prod",
+    hidden: true,
+    core: false,
+  },
+  {
+    name: "macros",
+    label: "Macros",
+    hint: "Internal template — not shown in pickers",
+    icon: "Code",
+    color: "#71717A",
+    colorRgb: "113 113 122",
+    devPort: 8093,
+    prodUrl: "https://macros.agent-native.com",
+    hidden: true,
+    defaultMode: "dev",
+  },
+];
+
+/** Return templates visible in user-facing pickers (excludes hidden). */
+export function visibleTemplates(): TemplateMeta[] {
+  return TEMPLATES.filter((t) => !t.hidden);
+}
+
+/** Return core templates — the featured set shown in CLI pickers by default. */
+export function coreTemplates(): TemplateMeta[] {
+  return TEMPLATES.filter((t) => t.core);
+}
+
+/** Lookup by name. Returns undefined for unknown names. */
+export function getTemplate(name: string): TemplateMeta | undefined {
+  // Tolerate legacy / renamed aliases.
+  if (name === "starter") name = "chat";
+  if (name === "image" || name === "images" || name === "asset") {
+    name = "assets";
+  }
+  if (name === "contracts" || name === "visual-plans") name = "plan";
+  return TEMPLATES.find((t) => t.name === name);
+}
+
+/** Names of all templates (including hidden) for validation. */
+export function allTemplateNames(): string[] {
+  return TEMPLATES.map((t) => t.name);
+}