@astrale-os/cli 1.0.0-beta.26 → 1.0.0-beta.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.26",
+  "version": "1.0.0-beta.28",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -68,8 +68,8 @@
     "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.1",
     "@commitlint/cli": "21.2.2",
     "@commitlint/config-conventional": "21.2.2",
-    "@types/bun": "^1.1.16",
     "@types/node": "^22.0.0",
+    "bun-types": "1.4.0",
     "husky": "~9.1.7",
     "lint-staged": "17.3.0",
     "msgpackr": "^2.0.5",
@@ -105,6 +105,7 @@
     "format": "pnpm exec oxfmt --write .",
     "format:check": "pnpm exec oxfmt --check .",
     "test": "node scripts/qualification/source-boundary.mjs --target && bun test src studio/client/src studio/server studio/shared && node --test scripts/*.test.mjs",
+    "test:skills-e2e": "node scripts/qualification/skills-update-e2e.mjs",
     "test:studio": "pnpm --dir studio test",
     "test:watch": "bun test --watch src"
   }

package/src/commands/__tests__/domain-install-operation.test.ts

@@ -93,6 +93,29 @@ describe('direct domain install operation identity', () => {
     ])
   })
 
+  test('keeps identity-override consent warnings out of machine output', async () => {
+    globalThis.fetch = mock(async () => publicationResponse()) as unknown as typeof fetch
+    const originalError = console.error
+    const warnings: unknown[][] = []
+    console.error = (...args: unknown[]) => {
+      warnings.push(args)
+    }
+    try {
+      await installDirect(
+        'https://alias.test',
+        { direct: true, json: true, allowIdentityOverride: true },
+        {
+          createOperationId: () => GENERATED,
+          runKernelCommand: async () => undefined,
+        },
+      )
+    } finally {
+      console.error = originalError
+    }
+
+    expect(warnings).toEqual([])
+  })
+
   test('rejects a non-UUID operation before metadata or Kernel transport', async () => {
     const originalExit = process.exit
     const originalWrite = process.stderr.write

package/src/commands/__tests__/install-identity-override.test.ts

@@ -54,11 +54,11 @@ describe('declared-origin Publication probe', () => {
     expect(await probeDeclaredOrigin(url)).toBe('crm.acme.dev')
   })
 
-  test('does not accept the removed pre-Kernel-V2 domainName shape', async () => {
-    const legacy = servePublication(() =>
+  test('does not accept a Publication without the canonical origin field', async () => {
+    const invalid = servePublication(() =>
       Response.json({ iss: 'https://x', domainName: 'crm.acme.dev' }),
     )
-    expect(await probeDeclaredOrigin(legacy)).toBeUndefined()
+    expect(await probeDeclaredOrigin(invalid)).toBeUndefined()
   })
 
   test('degrades to undefined on invalid Publication, non-200, bad JSON, or dead host', async () => {

package/src/commands/domain/install.ts

@@ -426,6 +426,7 @@ export async function installDirect(
       target,
       host,
       opts.allowIdentityOverride ?? false,
+      isMachine(opts),
     )
   } catch (e) {
     fatal(e, opts)
@@ -451,11 +452,13 @@ export async function installDirect(
       // aliases the host and the pre-install gate never consented to THAT
       // origin (lying or unavailable Publication), say so loudly after the fact.
       if (isIdentityOverride(installed.origin, host) && installed.origin !== consentedOrigin) {
-        log.warn(
-          `Installed origin "${installed.origin}" differs from the serving host "${host}" ` +
-            `and was not confirmed before install (the worker Publication was unavailable). ` +
-            `Every ${installed.origin}/* call on this instance now routes to ${host}.`,
-        )
+        if (!isMachine(fmtOpts)) {
+          log.warn(
+            `Installed origin "${installed.origin}" differs from the serving host "${host}" ` +
+              `and was not confirmed before install (the worker Publication was unavailable). ` +
+              `Every ${installed.origin}/* call on this instance now routes to ${host}.`,
+          )
+        }
       }
     },
   })
@@ -512,20 +515,25 @@ async function ensureIdentityOverrideConsent(
   url: string,
   host: string,
   allow: boolean,
+  machine: boolean,
 ): Promise<string | undefined> {
   const origin = await probeDeclaredOrigin(url)
   if (origin === undefined) {
-    log.warn(
-      `Could not read a declared origin from ` +
-        `${new URL('/.well-known/astrale/domain.json', url).href} — ` +
-        `skipping the pre-install identity check (the installed origin is verified after install).`,
-    )
+    if (!machine) {
+      log.warn(
+        `Could not read a declared origin from ` +
+          `${new URL('/.well-known/astrale/domain.json', url).href} — ` +
+          `skipping the pre-install identity check (the installed origin is verified after install).`,
+      )
+    }
     return undefined
   }
   if (!isIdentityOverride(origin, host)) return undefined
 
   if (allow) {
-    log.warn(`Identity override consented via --allow-identity-override: ${origin} ← ${host}`)
+    if (!machine) {
+      log.warn(`Identity override consented via --allow-identity-override: ${origin} ← ${host}`)
+    }
     return origin
   }
 

package/src/commands/get.ts

@@ -46,7 +46,7 @@ export default {
   description: 'Get one canonical node by Path or ID',
   afterHelpText: `
 Behavior:
-  Resolves one exact Kernel V2 Path and prints the canonical Node
+  Resolves one exact Kernel Path and prints the canonical Node
   { id, class, props }. Missing and authorization-masked nodes remain
   intentionally indistinguishable. @self is expanded before dispatch.
 

package/src/commands/identity/register.ts

@@ -45,10 +45,9 @@ Behavior:
   its result and stores the same target-bound registration. The callable owns
   authorization; the CLI never receives installed Domain authority.
 
-  Kernel V2 Nodes have opaque identity and no caller-assigned storage path, so
-  the historical --path option no longer exists. The CLI binds the key proof
-  to the exact provision fingerprint and target Kernel audience, then caches
-  the returned (issuer, subject) for subsequent calls.
+  The Kernel assigns each Node ID; callers do not choose a storage path. The
+  CLI binds the key proof to the exact provision fingerprint and target Kernel
+  audience, then caches the returned (issuer, subject) for subsequent calls.
 
 Example:
   $ astrale identity register alice --class /:accounts.example:class.User \

package/src/commands/logs.ts

@@ -341,11 +341,8 @@ Behavior:
   Calls the public Kernel journal syscall and emits its { records, cursor }
   page. Topic selection is exact or prefix-based; cursors and timestamps are
   opaque strings owned by the journal backend. --follow reuses one Client Session
-  and advances only with the returned cursor. Machine follow output is NDJSON:
-  one complete admitted record per line; YAML follow is unsupported.
-
-  Historical event-glob lowering and the application-specific services-domain
-  log buffer are not part of the Kernel V2 journal contract.
+  and advances only with the returned cursor. With --json, follow output is
+  NDJSON with one complete admitted record per line; YAML follow is unsupported.
 
 Examples:
   $ astrale logs -i staging --limit 50

package/src/commands/session/analyze.ts

@@ -4,13 +4,23 @@ import type { CommandDefinition } from '../../program/index'
 
 import { log } from '../../lib/log'
 import { analyzeSession } from '../../telemetry/analyze'
-import { listSessions } from '../../telemetry/store'
+import { sweepStore } from '../../telemetry/retention'
+import { scanSessions } from '../../telemetry/store'
 import { restampLock, releaseLock } from '../../telemetry/trigger'
 
 export default {
   name: 'analyze',
   description: 'Analyze a recorded session for DX frictions (dry-run: writes report.md)',
-  arguments: [{ name: 'id', description: 'Session id (default: most recent closed, unanalyzed)' }],
+  arguments: [
+    // Optional: the action resolves the most recent closed, unanalyzed session
+    // when no id is given, which is how a human is meant to invoke this. The
+    // opportunistic trigger always passes an explicit id.
+    {
+      name: 'id',
+      description: 'Session id (default: most recent closed, unanalyzed)',
+      required: false,
+    },
+  ],
   options: [
     { flags: '--file', description: 'File cleared findings as issues on the admin tracker' },
     { flags: '--model <model>', description: 'Model for the analyzer pass' },
@@ -22,10 +32,10 @@ export default {
     opts: { file?: boolean; model?: string; force?: boolean; auto?: boolean },
   ) => {
     if (opts.auto) restampLock()
+    let target = id
     try {
-      let target = id
       if (!target) {
-        const candidate = listSessions().find((s) => s.closed && (opts.force || !s.analyzed))
+        const candidate = scanSessions().find((s) => s.closed && (opts.force || !s.analyzed))
         if (!candidate) {
           if (!opts.auto) log.dim('Nothing to analyze — no closed, unanalyzed session.')
           return
@@ -45,6 +55,18 @@ export default {
       }
     } finally {
       if (opts.auto) releaseLock()
+      // The size bound is enforced here, not on the CLI's critical path:
+      // measuring every file of every session is only affordable in this
+      // process, and this is precisely where the store just grew. The session
+      // just analyzed is protected — it is the freshest evidence on disk.
+      try {
+        const swept = sweepStore({ protect: new Set(target === undefined ? [] : [target]) })
+        if (!opts.auto && swept.removed.length > 0) {
+          log.dim(`retention: removed ${swept.removed.length} session(s)`)
+        }
+      } catch {
+        /* retention must never fail the command that triggered it */
+      }
     }
   },
 } satisfies CommandDefinition

package/src/commands/update.ts

@@ -11,7 +11,12 @@ import {
   inDomainProject,
   type SdkOutdated,
 } from '../lib/sdk-deps'
-import { ASTRALE_CLI_SKILL, detectSkill, installSkills, SKILL_INSTALL_HINT } from '../lib/skills'
+import {
+  checkAstraleSkills,
+  type SkillApplyResult,
+  type SkillCheckResult,
+  syncAstraleSkills,
+} from '../lib/skills'
 import { DEFAULT_UPDATE_CHANNEL, packageManagedUpdateError, updateAstrale } from '../lib/update'
 
 type UpdateOpts = RawOutputOpts & {
@@ -23,26 +28,26 @@ type UpdateOpts = RawOutputOpts & {
   yes?: boolean
 }
 
-/**
- * Refresh the astrale agent skills alongside the binary. Delegates to the same
- * `npx skills add` installer `astrale setup` uses; re-running it updates an
- * existing install to the latest published SKILL.md.
- *
- * Only refreshes skills the user already has — `astrale update` keeps an existing
- * install current, it does not foist skills on a non-agent user; fresh installs
- * go through `astrale setup`. Best-effort: a failure here never fails the update
- * (the binary is already swapped), so we warn and move on.
- */
-async function refreshSkills(): Promise<void> {
-  if (!detectSkill(ASTRALE_CLI_SKILL).installed) {
-    log.dim(`  Agent skills not installed — get them with: ${SKILL_INSTALL_HINT}`)
-    return
-  }
-  log.step(`Refreshing the astrale agent skills — ${SKILL_INSTALL_HINT}`)
-  if (await installSkills()) {
-    log.success('astrale agent skills up to date')
-  } else {
-    log.warn(`Skill refresh did not complete — run it later: ${SKILL_INSTALL_HINT}`)
+async function refreshSkills(): Promise<SkillApplyResult> {
+  log.step('Ensuring Astrale agent skills are current and healthy')
+  const result = await syncAstraleSkills()
+  if (result.status === 'unchanged') log.success('Astrale skills already up to date')
+  else if (result.status === 'installed') log.success('Astrale skills installed')
+  else if (result.status === 'updated') log.success('Astrale skills updated')
+  else if (result.status === 'repaired') log.success('Astrale skills repaired and updated')
+  return result
+}
+
+function skillCheckStale(skills: SkillCheckResult): boolean {
+  return skills.status === 'update-available' || skills.status === 'repair-needed'
+}
+
+function printSkillCheck(skills: SkillCheckResult): void {
+  if (skills.status === 'current') log.success('Astrale skills are up to date')
+  else if (skills.status === 'update-available') log.info('Astrale skills update available')
+  else if (skills.status === 'repair-needed') log.warn('Astrale skills need repair')
+  else if (skills.status === 'unavailable') {
+    log.warn(`Could not verify Astrale skills${skills.error ? `: ${skills.error}` : ''}`)
   }
 }
 
@@ -106,9 +111,8 @@ async function refreshSdkDeps(check: boolean, assumeYes = false): Promise<boolea
  * domain-studio polls this on load to drive its "update available" badge. It is
  * unified and NON-THROWING: an explicit package-managed result uses npm release
  * identity, while script-install failures remain script failures in `error`
- * instead of being recategorized. The SDK axis is already best-effort. Skills are
- * intentionally absent — they ride along with `astrale update`, so a stale CLI or
- * SDK is the only signal worth surfacing.
+ * instead of being recategorized. The SDK axis is already best-effort. Skills
+ * report meaningful health/freshness states without exposing installer metadata.
  */
 export type StaleReport = {
   stale: boolean
@@ -120,6 +124,7 @@ export type StaleReport = {
     channel?: string
     error?: string
   }
+  skills: SkillCheckResult
   sdk: { stale: boolean; inProject: boolean; outdated: SdkOutdated[] }
 }
 
@@ -218,7 +223,7 @@ export default {
       default: DEFAULT_UPDATE_CHANNEL,
     },
     { flags: '--version <version>', description: 'Update to an exact version tag' },
-    { flags: '--no-skills', description: 'Skip refreshing the astrale agent skills' },
+    { flags: '--no-skills', description: 'Skip ensuring the Astrale agent skills' },
     { flags: '--no-deps', description: 'Skip checking @astrale-os SDK dependency versions' },
     {
       flags: '--yes',
@@ -231,23 +236,22 @@ Behavior:
   Keeps three things current, in order. (1) The CLI binary: updates official
   script installs only — if Astrale was installed by another package manager this
   command refuses so that manager stays in charge; downloads are checksum-verified
-  before the binary is replaced. (2) The agent skills: if the astrale skills (cli +
-  domain) are already installed, refreshes them to the latest by delegating to
-  "npx skills add astrale-os/cli -g" — the same installer "astrale setup" uses;
-  fresh installs go through "astrale setup". (3) SDK deps: inside a pnpm domain
+  before the binary is replaced. (2) The Astrale agent skills: installs every
+  top-level skill published from astrale-os/cli main, updates healthy older
+  installs, repairs inconsistent installs, and verifies the result before
+  reporting success. (3) SDK deps: inside a pnpm domain
   project, proposes any @astrale-os/* dependency with a newer release and, on
   confirm, runs "pnpm update --latest --lockfile-only" (updates package.json AND
   the lockfile, honoring your registry + supply-chain age policy; run "pnpm
   install" to materialize).
 
   The default release channel is beta; --channel overrides it for one run.
-  --check is a dry run (binary + SDK deps; exit 10 if anything is available) and
+  --check is a dry run (binary + skills + SDK deps; exit 10 if anything is available) and
   never writes. With --json it emits a unified staleness report
-  ({ stale, cli, sdk }) for tooling — non-throwing, skills omitted (they ride
-  along with an update). --yes applies all three non-interactively (no prompts) and
+  ({ stale, cli, skills, sdk }) for tooling. --yes applies all three non-interactively and
   is resilient — a binary that can't self-update (package-managed) warns but never
-  blocks the skills/deps steps; this is what domain-studio's "Update now" runs.
-  --no-skills / --no-deps skip those steps in a real run.
+  blocks the skills/deps steps; a skill failure fails the command rather than
+  claiming a partial success. --no-skills / --no-deps explicitly skip those axes.
 
 Examples:
   $ astrale update
@@ -262,11 +266,18 @@ Examples:
     try {
       // Tooling path: a machine-readable `--check` (e.g. domain-studio's update
       // badge polling `astrale update --check --json`) gets a unified,
-      // non-throwing staleness report — CLI + SDK only — and exits.
+      // non-throwing staleness report and exits.
       if (opts.check && isMachine(opts)) {
         const cli = await cliStale(opts)
+        const skills: SkillCheckResult =
+          opts.skills === false ? { status: 'skipped' } : await checkAstraleSkills()
         const sdk = await sdkStale()
-        const report: StaleReport = { stale: cli.stale || sdk.stale, cli, sdk }
+        const report: StaleReport = {
+          stale: cli.stale || skillCheckStale(skills) || sdk.stale,
+          cli,
+          skills,
+          sdk,
+        }
         output(report, opts)
         if (report.stale) process.exitCode = 10
         return
@@ -316,9 +327,19 @@ Examples:
         log.warn(`CLI self-update skipped: ${error.message}`)
       }
 
-      // Axis B — agent skills. Keep an existing install current with the CLI.
-      // Skip on --check (a dry run) and when the user opted out with --no-skills.
-      if (!opts.check && opts.skills !== false) await refreshSkills()
+      // Axis B — agent skills. A successful real update guarantees a verified
+      // latest cohort; --check remains read-only and reports its status.
+      if (opts.skills !== false) {
+        if (opts.check) {
+          const skills = await checkAstraleSkills()
+          printSkillCheck(skills)
+          if (skillCheckStale(skills)) anyAvailable = true
+        } else {
+          await refreshSkills()
+        }
+      } else if (!opts.check) {
+        log.dim('  Astrale skills skipped (--no-skills)')
+      }
 
       // Axis C — first-party @astrale-os/* deps in the current domain project.
       // Runs on --check too (reports availability); --yes applies without a prompt.
@@ -328,7 +349,7 @@ Examples:
 
       if (opts.check && anyAvailable) process.exitCode = 10
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition