@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

package/src/telemetry/store.ts

@@ -5,8 +5,14 @@
  *   .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.
+ *
+ * Two ways to read it, deliberately kept apart. scanSessions() answers the
+ * questions the CLI's start path asks — how old, open or closed, analyzed yet —
+ * from two stats per session and no file reads. listSessions() adds the parsed
+ * meta.json and marker, which only `session list` and the analyzer need. The
+ * start path runs before EVERY command, so the difference is not academic.
  */
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
 import type { AnalyzedMarker, SessionMeta } from './types'
@@ -42,6 +48,78 @@ export function reportPath(id: string): string {
   return join(sessionDir(id), 'report.md')
 }
 
+/**
+ * The cheap facts about one session: enough to bucket an invocation, sweep the
+ * store, and pick an analysis target. `analyzed` records that a marker EXISTS,
+ * not what it says — a stat, not a read.
+ */
+export type SessionScan = {
+  id: string
+  lastEventAt: Date | null
+  closed: boolean
+  analyzed: boolean
+}
+
+/** Session directory names, newest-first ordering applied by the callers. */
+function sessionIds(): string[] {
+  try {
+    return readdirSync(sessionsRoot()).filter((name) => !name.startsWith('.'))
+  } catch {
+    return []
+  }
+}
+
+/** Newest activity first. Two stats per session, no file reads, no parsing. */
+export function scanSessions(now = Date.now()): SessionScan[] {
+  return sessionIds()
+    .map((id) => {
+      let lastEventAt: Date | null = null
+      try {
+        lastEventAt = statSync(eventsPath(id)).mtime
+      } catch {
+        /* no events yet */
+      }
+      return {
+        id,
+        lastEventAt,
+        closed: lastEventAt !== null && now - lastEventAt.getTime() > IDLE_WINDOW_MS,
+        analyzed: existsSync(markerPath(id)),
+      }
+    })
+    .sort((a, b) => (b.lastEventAt?.getTime() ?? 0) - (a.lastEventAt?.getTime() ?? 0))
+}
+
+/** Bytes on disk under `dir`. Unreadable entries count as zero — a directory
+ *  racing away mid-walk is normal, not an error worth propagating. */
+function directoryBytes(dir: string): number {
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return 0
+  }
+  let total = 0
+  for (const entry of entries) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      total += directoryBytes(path)
+    } else if (entry.isFile()) {
+      try {
+        total += statSync(path).size
+      } catch {
+        /* raced away mid-walk */
+      }
+    }
+  }
+  return total
+}
+
+/** Bytes one session occupies. The analyzer runs with Write inside the session
+ *  directory and may nest, so this walks rather than listing one level. */
+export function sessionBytes(id: string): number {
+  return directoryBytes(sessionDir(id))
+}
+
 export type SessionInfo = {
   id: string
   meta: SessionMeta | null
@@ -50,6 +128,16 @@ export type SessionInfo = {
   analyzed: AnalyzedMarker | null
 }
 
+/** One session's meta.json, or null when absent or unparseable. */
+export function readMeta(id: string): SessionMeta | null {
+  return readJsonSafe<SessionMeta>(metaPath(id))
+}
+
+/** One session's analyzer marker, or null when absent or unparseable. */
+export function readMarker(id: string): AnalyzedMarker | null {
+  return readJsonSafe<AnalyzedMarker>(markerPath(id))
+}
+
 function readJsonSafe<T>(path: string): T | null {
   try {
     return JSON.parse(readFileSync(path, 'utf-8')) as T
@@ -76,15 +164,10 @@ export function inspectSession(id: string, now = Date.now()): SessionInfo | null
   }
 }
 
-/** All sessions, newest activity first. Missing store dir → empty list. */
+/** All sessions, newest activity first, fully parsed. Missing store dir → empty
+ *  list. Prefer scanSessions() anywhere latency matters — see the file header. */
 export function listSessions(now = Date.now()): SessionInfo[] {
-  let ids: string[]
-  try {
-    ids = readdirSync(sessionsRoot()).filter((n) => !n.startsWith('.'))
-  } catch {
-    return []
-  }
-  return ids
+  return sessionIds()
     .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

@@ -2,36 +2,18 @@
  * 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.
+ * The same scan pays for the age sweep (see retention.ts), which is why the
+ * store stays bounded without anything resembling a background job.
  */
 import { spawn } from 'node:child_process'
-import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { MAX_REMOVALS_ON_START, sweepByAge } from './retention'
 import { telemetryEnabled } from './settings'
-import { listSessions, sessionDir, sessionsRoot, type SessionInfo } from './store'
+import { scanSessions, sessionsRoot, type SessionScan } 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')
@@ -76,16 +58,22 @@ export function releaseLock(): void {
  * 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 {
+export function maybeTriggerAnalysis(argv: string[], scan?: readonly SessionScan[]): void {
   try {
-    if (!telemetryEnabled()) return
     if (process.env.ASTRALE_TELEMETRY_NO_TRIGGER === '1') return
+
+    const sessions = scan ?? scanSessions()
+    // Retention runs ahead of the kill-switch check and on `session` commands
+    // too — turning telemetry off must still drain what is already on disk.
+    const swept = new Set(sweepByAge(sessions, { limit: MAX_REMOVALS_ON_START }).removed)
+
+    if (!telemetryEnabled()) 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)
+    const target = sessions.find(
+      (s) => s.closed && !s.analyzed && s.lastEventAt !== null && !swept.has(s.id),
+    )
     if (!target) return
     if (!claimLock()) return
 

package/src/ui/.spec/api.d.ts

@@ -0,0 +1,14 @@
+export {
+  addUi,
+  applyPreset,
+  diffUi,
+  doctorUi,
+  initUi,
+  listUi,
+  viewUi,
+  type InitUiOptions,
+} from '../operations.js'
+export { UI_PRESETS, UiError, type UiLock, type UiPreset } from '../model.js'
+export { discoverUiProject, type UiProject } from '../project.js'
+export { resolveUiRelease } from '../release.js'
+export { shadcnInvocation, type UiRunner } from '../runner.js'

package/src/ui/.spec/architecture.md

@@ -0,0 +1,14 @@
+# UI local tooling
+
+This private CLI owner manages an existing local React project. It does not connect to a Kernel and
+does not add React, Base UI, Tailwind, shadcn, or the UI runtime to the installed CLI dependency
+graph.
+
+One registry operation resolves one immutable UI commit. During the V1 prerelease, operations
+without an explicit version resolve the npm `beta` dist-tag; the legacy `latest` channel is not a V1
+source. Package compatibility and registry reads use that commit. Patterns and blocks invoke the
+release-qualified shadcn CLI on demand through the detected package manager. Released themes copy
+the exact admitted embedded CSS directly, while a local playground export is admitted and copied
+without registry or shadcn. Both theme paths install consumer-owned source and activate it through
+one project-relative CSS import, and complete application writes before the lock advances. Dry-run,
+list, and doctor do not claim a file mutation.

package/src/ui/.spec/laws.ts

@@ -0,0 +1,50 @@
+import { defineLaw } from '@astrale-os/spec/authoring'
+
+export const CLI_UI_BETA_DEFAULT = defineLaw({
+  id: 'CLI-UI-BETA-DEFAULT',
+  statement:
+    'Until the UI V1 channel is promoted, an operation without an explicit version resolves the npm beta dist-tag and never the legacy latest dist-tag.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-BETA-DEFAULT' }],
+})
+
+export const CLI_UI_ONE_SNAPSHOT = defineLaw({
+  id: 'CLI-UI-ONE-SNAPSHOT',
+  statement:
+    'Each UI operation resolves one immutable repository commit and reads compatibility, registry, and item source only from that snapshot.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-ONE-SNAPSHOT' }],
+})
+
+export const CLI_UI_LOCK_AFTER_SUCCESS = defineLaw({
+  id: 'CLI-UI-LOCK-AFTER-SUCCESS',
+  statement:
+    'Dry runs and failed package or source operations do not advance astrale-ui.lock.json.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-LOCK-AFTER-SUCCESS' }],
+})
+
+export const CLI_UI_BOUNDED_REMOTE_DOCUMENTS = defineLaw({
+  id: 'CLI-UI-BOUNDED-REMOTE-DOCUMENTS',
+  statement:
+    'Release metadata and registry documents are size-bounded, include-bounded, and normalized to stable UI registry errors before any project mutation.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-BOUNDED-REMOTE-DOCUMENTS' }],
+})
+
+export const CLI_UI_EXACT_ITEM_SOURCE = defineLaw({
+  id: 'CLI-UI-EXACT-ITEM-SOURCE',
+  statement:
+    'An add operation admits the exact built item document against the release index and records its content-bearing source digest before any consumer mutation; only patterns and blocks invoke project tooling.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-EXACT-ITEM-SOURCE' }],
+})
+
+export const CLI_UI_THEME_OWNERSHIP = defineLaw({
+  id: 'CLI-UI-THEME-OWNERSHIP',
+  statement:
+    'A released or locally exported theme becomes one project-contained consumer-owned CSS file, is activated by one relative host stylesheet import, and rolls back file, import, and lock together on failure.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-THEME-OWNERSHIP' }],
+})
+
+export const CLI_UI_SEMANTIC_DIFF = defineLaw({
+  id: 'CLI-UI-SEMANTIC-DIFF',
+  statement:
+    'Diff is read-only, path-contained, and classifies locked source and files as upstream changed, unchanged, modified, or deleted without delegating truth to tool output.',
+  tests: [{ file: '../__tests__/ui.test.ts', id: 'TEST-CLI-UI-SEMANTIC-DIFF' }],
+})

package/src/ui/.spec/layout.ts

@@ -0,0 +1,16 @@
+import { defineLayout } from '@astrale-os/spec/authoring'
+
+export default defineLayout({
+  entries: [
+    '.spec/',
+    '__tests__/',
+    'index.ts',
+    'lock.ts',
+    'model.ts',
+    'operations.ts',
+    'project.ts',
+    'release.ts',
+    'runner.ts',
+  ],
+  exact: true,
+})