@astrale-os/cli 0.5.0-alpha.0 → 0.6.0-alpha.0

package/src/telemetry/session.ts

@@ -0,0 +1,88 @@
+/**
+ * Session identity: buckets CLI invocations by workspace (git root, else cwd).
+ * ASTRALE_SESSION pins an explicit id owned by a surface; otherwise an ambient
+ * session is reused within the idle window or minted per root. Never spawns a
+ * child process; every fs touch is swallowed so telemetry can't break the CLI.
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import type { SessionMeta } from './types'
+
+import { listSessions, metaPath, sessionDir } from './store'
+
+export type ResolvedSession = { id: string; root: string; explicit: boolean }
+
+const MAX_ID_LEN = 64
+
+/** Nearest ancestor of `start` (inclusive) containing a `.git` entry, else null. */
+function findGitRoot(start: string): string | null {
+  let dir = start
+  for (;;) {
+    if (existsSync(join(dir, '.git'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** Keep only id-safe chars, capped to 64. */
+function sanitizeId(raw: string): string {
+  return raw.replace(/[^a-zA-Z0-9._-]/g, '').slice(0, MAX_ID_LEN)
+}
+
+/** Local-time yyyymmddHHmm stamp for a minted ambient id. */
+function stamp(d = new Date()): string {
+  const p = (n: number, w = 2) => String(n).padStart(w, '0')
+  return `${p(d.getFullYear(), 4)}${p(d.getMonth() + 1)}${p(d.getDate())}${p(d.getHours())}${p(d.getMinutes())}`
+}
+
+/** id of an open, ambient session already bucketed to `root`, else null.
+ *  Analyzed sessions are never reused — a straggler event may "reopen" one
+ *  after its report, and new work funneled there would never be analyzed. */
+function findOpenAmbient(root: string): string | null {
+  for (const s of listSessions()) {
+    if (s.meta?.root === root && s.meta.explicit === false && !s.closed && s.analyzed === null) {
+      return s.id
+    }
+  }
+  return null
+}
+
+function mintAmbientId(root: string): string {
+  const hash8 = createHash('sha256').update(root).digest('hex').slice(0, 8)
+  return `amb-${hash8}-${stamp()}`
+}
+
+/** Resolve the session identity for `cwd` without creating anything on disk. */
+export function resolveSession(cwd: string): ResolvedSession {
+  const root = findGitRoot(cwd) ?? cwd
+  const pinned = process.env.ASTRALE_SESSION
+  if (pinned) {
+    const id = sanitizeId(pinned)
+    if (id.length > 0) return { id, root, explicit: true }
+  }
+  return { id: findOpenAmbient(root) ?? mintAmbientId(root), root, explicit: false }
+}
+
+/** Resolve, then create the session dir + meta.json on first sight. */
+export function ensureSession(cwd: string): ResolvedSession {
+  const resolved = resolveSession(cwd)
+  const dir = sessionDir(resolved.id)
+  if (!existsSync(dir)) {
+    try {
+      mkdirSync(dir, { recursive: true })
+      const meta: SessionMeta = {
+        id: resolved.id,
+        root: resolved.root,
+        explicit: resolved.explicit,
+        createdAt: new Date().toISOString(),
+      }
+      writeFileSync(metaPath(resolved.id), JSON.stringify(meta, null, 2) + '\n')
+    } catch {
+      /* telemetry never breaks the CLI */
+    }
+  }
+  return resolved
+}

package/src/telemetry/settings.ts

@@ -0,0 +1,26 @@
+/**
+ * Telemetry kill-switch, evaluated synchronously at process start/exit.
+ * Off when ASTRALE_TELEMETRY is 0/false/off, or when config telemetry.enabled
+ * is false; on by default. Every read silent-fails to enabled.
+ */
+import { readFileSync } from 'node:fs'
+
+import { createPaths } from '../lib/env'
+
+const OFF_VALUES = new Set(['0', 'false', 'off'])
+
+/** Whether telemetry recording is enabled for this process. */
+export function telemetryEnabled(): boolean {
+  const env = process.env.ASTRALE_TELEMETRY
+  if (env !== undefined && OFF_VALUES.has(env.trim().toLowerCase())) return false
+  try {
+    // Call-time path resolution — see sessionsRoot() in store.ts for why.
+    const parsed = JSON.parse(readFileSync(createPaths().config, 'utf-8')) as {
+      telemetry?: { enabled?: boolean }
+    }
+    if (parsed.telemetry?.enabled === false) return false
+  } catch {
+    /* missing or broken config → default on */
+  }
+  return true
+}

package/src/telemetry/store.ts

@@ -0,0 +1,91 @@
+/**
+ * Session store layout under `~/.astrale/sessions/<id>/`:
+ *   events.jsonl   append-only CLI events; its mtime IS the session's last-activity
+ *   meta.json      SessionMeta, written once at creation
+ *   .analyzed      AnalyzedMarker, written by the analyzer (any outcome)
+ *   report.md      analyzer output
+ * A session is CLOSED when events.jsonl's mtime is older than IDLE_WINDOW_MS.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { AnalyzedMarker, SessionMeta } from './types'
+
+import { createPaths } from '../lib/env'
+
+export const IDLE_WINDOW_MS = 30 * 60 * 1000
+
+// Resolved at CALL time (not import time) so ASTRALE_HOME set late — notably
+// by tests whose module-load order is out of their control — always applies.
+// The env can't change mid-process in real CLI runs, so behavior is identical.
+export function sessionsRoot(): string {
+  return join(createPaths().home, 'sessions')
+}
+
+export function sessionDir(id: string): string {
+  return join(sessionsRoot(), id)
+}
+
+export function eventsPath(id: string): string {
+  return join(sessionDir(id), 'events.jsonl')
+}
+
+export function metaPath(id: string): string {
+  return join(sessionDir(id), 'meta.json')
+}
+
+export function markerPath(id: string): string {
+  return join(sessionDir(id), '.analyzed')
+}
+
+export function reportPath(id: string): string {
+  return join(sessionDir(id), 'report.md')
+}
+
+export type SessionInfo = {
+  id: string
+  meta: SessionMeta | null
+  lastEventAt: Date | null
+  closed: boolean
+  analyzed: AnalyzedMarker | null
+}
+
+function readJsonSafe<T>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as T
+  } catch {
+    return null
+  }
+}
+
+export function inspectSession(id: string, now = Date.now()): SessionInfo | null {
+  const dir = sessionDir(id)
+  if (!existsSync(dir)) return null
+  let lastEventAt: Date | null = null
+  try {
+    lastEventAt = statSync(eventsPath(id)).mtime
+  } catch {
+    /* no events yet */
+  }
+  return {
+    id,
+    meta: readJsonSafe<SessionMeta>(metaPath(id)),
+    lastEventAt,
+    closed: lastEventAt !== null && now - lastEventAt.getTime() > IDLE_WINDOW_MS,
+    analyzed: readJsonSafe<AnalyzedMarker>(markerPath(id)),
+  }
+}
+
+/** All sessions, newest activity first. Missing store dir → empty list. */
+export function listSessions(now = Date.now()): SessionInfo[] {
+  let ids: string[]
+  try {
+    ids = readdirSync(sessionsRoot()).filter((n) => !n.startsWith('.'))
+  } catch {
+    return []
+  }
+  return ids
+    .map((id) => inspectSession(id, now))
+    .filter((s): s is SessionInfo => s !== null)
+    .sort((a, b) => (b.lastEventAt?.getTime() ?? 0) - (a.lastEventAt?.getTime() ?? 0))
+}

package/src/telemetry/trigger.ts

@@ -0,0 +1,119 @@
+/**
+ * Opportunistic analysis trigger — the `git gc --auto` model. Each CLI start
+ * cheaply scans for a closed, unanalyzed session and spawns ONE detached
+ * analyzer for it. No daemon, no cron; a lockfile keeps it single-flight.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { telemetryEnabled } from './settings'
+import { listSessions, sessionDir, sessionsRoot, type SessionInfo } from './store'
+
+const LOCK_STALE_MS = 30 * 60 * 1000
+const GC_AGE_MS = 30 * 24 * 60 * 60 * 1000
+const GC_MAX_PER_RUN = 20
+
+/** Opportunistic GC: analyzed sessions idle past the retention age are removed
+ *  (capped per invocation) so the store — and the per-invocation scan — stays
+ *  bounded. Evidence worth keeping has left via reports or filed issues. */
+function gcOldSessions(sessions: SessionInfo[]): void {
+  try {
+    const cutoff = Date.now() - GC_AGE_MS
+    let removed = 0
+    for (const s of sessions) {
+      if (removed >= GC_MAX_PER_RUN) break
+      if (s.analyzed !== null && s.lastEventAt !== null && s.lastEventAt.getTime() < cutoff) {
+        rmSync(sessionDir(s.id), { recursive: true, force: true })
+        removed++
+      }
+    }
+  } catch {
+    /* best effort */
+  }
+}
+
+function lockPath(): string {
+  return join(sessionsRoot(), '.analyzer.lock')
+}
+
+/** True when the lock is free (or stale/dead) and was claimed. */
+function claimLock(): boolean {
+  const path = lockPath()
+  try {
+    if (existsSync(path)) {
+      const lock = JSON.parse(readFileSync(path, 'utf-8')) as { pid: number; at: number }
+      const stale = Date.now() - lock.at > LOCK_STALE_MS
+      let alive = false
+      try {
+        process.kill(lock.pid, 0)
+        alive = true
+      } catch {
+        /* dead */
+      }
+      if (alive && !stale) return false
+      unlinkSync(path)
+    }
+    mkdirSync(sessionsRoot(), { recursive: true })
+    writeFileSync(path, JSON.stringify({ pid: process.pid, at: Date.now() }))
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Release only in the parent that claimed; the child rewrites its own. */
+export function releaseLock(): void {
+  try {
+    unlinkSync(lockPath())
+  } catch {
+    /* already gone */
+  }
+}
+
+/**
+ * Fire-and-forget: spawn a detached `astrale session analyze <id> --auto` for
+ * the most recently closed unanalyzed session, if any. Never throws, never
+ * blocks — worst case a few ms of directory stats.
+ */
+export function maybeTriggerAnalysis(argv: string[]): void {
+  try {
+    if (!telemetryEnabled()) return
+    if (process.env.ASTRALE_TELEMETRY_NO_TRIGGER === '1') return
+    // Never cascade off the session commands themselves.
+    if (argv[2] === 'session') return
+
+    const sessions = listSessions()
+    gcOldSessions(sessions)
+    const target = sessions.find((s) => s.closed && s.analyzed === null && s.lastEventAt !== null)
+    if (!target) return
+    if (!claimLock()) return
+
+    // Re-invoke self: execPath is bun/node (dev) or the compiled binary; when
+    // argv[1] is a real script path, keep it as the first argument. In a
+    // bun-compiled binary argv[1] is a virtual /$bunfs/ path that must NOT be
+    // passed — the binary re-runs itself from execPath alone.
+    const script = process.argv[1]
+    const args =
+      script && script !== process.execPath && !script.startsWith('/$bunfs') ? [script] : []
+    args.push('session', 'analyze', target.id, '--auto')
+    const child = spawn(process.execPath, args, {
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env, ASTRALE_TELEMETRY_NO_TRIGGER: '1' },
+    })
+    child.unref()
+    // The lock hands over to the child: it re-stamps with its own pid on start.
+  } catch {
+    /* telemetry must never affect the CLI */
+  }
+}
+
+/** Called by `session analyze --auto` to take over the parent's claim. */
+export function restampLock(): void {
+  try {
+    writeFileSync(lockPath(), JSON.stringify({ pid: process.pid, at: Date.now() }))
+  } catch {
+    /* best effort */
+  }
+}

package/src/telemetry/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Telemetry contracts. One CLI invocation = one appended event; one session =
+ * one directory of evidence under `~/.astrale/sessions/`; harness adapters
+ * contribute transcript discovery + a reading guide, never normalization.
+ */
+
+/** One CLI invocation, one JSON line in events.jsonl. */
+export type TelemetryEvent = {
+  /** Envelope version. */
+  v: 1
+  /** ISO timestamp at process start. */
+  ts: string
+  /** argv after the binary name, secrets redacted (see redact.ts). */
+  argv: string[]
+  exitCode: number
+  durationMs: number
+  /** Error class name when the command threw (AstraleError code preferred). */
+  errorName?: string
+  cwd: string
+  /** Workspace root the session is bucketed by (git root, else cwd). */
+  root: string
+  /** Which surface produced the event. */
+  surface: 'cli'
+}
+
+/** Written once when a session directory is created. */
+export type SessionMeta = {
+  id: string
+  root: string
+  /** true when the id came from ASTRALE_SESSION (a surface owns the lifecycle). */
+  explicit: boolean
+  createdAt: string
+}
+
+/** Written by the analyzer when it finishes with a session (any outcome). */
+export type AnalyzedMarker = {
+  analyzedAt: string
+  outcome: 'skipped-quiet' | 'reported' | 'filed' | 'error'
+  note?: string
+}
+
+/** An agent-harness session discovered on this machine (transcript = evidence). */
+export type HarnessSession = {
+  harness: string
+  sessionId?: string
+  transcriptPath: string
+  cwd?: string
+  startedAt?: string
+  endedAt?: string
+  sizeBytes: number
+}
+
+/** Deterministic signals extracted from events.jsonl — the free gate's input. */
+export type SessionSignals = {
+  eventCount: number
+  /** Events with a non-zero exit, grouped by leading command tokens. */
+  failures: { command: string; count: number; errorNames: string[] }[]
+  /** Same leading command tokens re-run 3+ times (retry smell). */
+  retries: { command: string; count: number }[]
+  firstEventAt?: string
+  lastEventAt?: string
+  /** Harness transcripts overlapping this session's root + time window. */
+  harnessSessions: HarnessSession[]
+}