feat(cli): add install progress reporting and improve add install feedback (#8)

* feat: update

* fix(cli): tighten install progress reporter behavior

Author: SoonIter

packages/skills-package-manager/src/commands/add.ts

@@ -96,7 +96,9 @@ export async function addCommand(options: AddCommandOptions) {
       const skillPath = found?.path ?? `/${skill}`
       const gitSpecifier = buildGitHubSpecifier(owner, repo, skillPath)
       const result = await addSingleSkill(cwd, gitSpecifier)
+      spinner.start('Installing skills...')
       await installSkills(cwd)
+      spinner.stop('Installed skills')
       p.outro(`Added ${pc.cyan(result.skillName)}`)
       return result
     }
@@ -127,13 +129,18 @@ export async function addCommand(options: AddCommandOptions) {
       p.log.success(`Added ${pc.cyan(result.skillName)}`)
     }
 
+    spinner.start('Installing skills...')
     await installSkills(cwd)
+    spinner.stop('Installed skills')
     p.outro('Done')
     return results.length === 1 ? results[0] : results
   }
 
   // Protocol specifier (file:, npm:, git URL with fragment, etc.) — direct add
   const result = await addSingleSkill(cwd, specifier)
+  const spinner = p.spinner()
+  spinner.start('Installing skills...')
   await installSkills(cwd)
+  spinner.stop('Installed skills')
   return result
 }

packages/skills-package-manager/src/commands/install.ts

@@ -6,6 +6,7 @@ import type { InstallCommandOptions } from '../config/types'
 import { writeSkillsLock } from '../config/writeSkillsLock'
 import { ErrorCode, ManifestError } from '../errors'
 import { fetchSkillsFromLock, linkSkillsFromLock } from '../install/installSkills'
+import { createInstallProgressReporter } from '../install/progressReporter'
 
 export async function installCommand(options: InstallCommandOptions) {
   const manifest = await readSkillsManifest(options.cwd)
@@ -18,39 +19,68 @@ export async function installCommand(options: InstallCommandOptions) {
   }
 
   const currentLock = await readSkillsLock(options.cwd)
+  const totalSkills = Object.keys(manifest.skills).length
+  const reporter = createInstallProgressReporter()
+  const onProgress = (event: Parameters<typeof reporter.onProgress>[0]) =>
+    reporter.onProgress(event)
+  let started = false
 
-  if (options.frozenLockfile) {
-    // Frozen mode: lock must exist and be in sync
-    if (!currentLock) {
-      throw new ManifestError({
-        code: ErrorCode.LOCKFILE_NOT_FOUND,
-        filePath: `${options.cwd}/skills-lock.yaml`,
-        message: 'Lockfile is required in frozen mode but none was found. Run "spm install" first.',
-      })
-    }
-    if (!isLockInSync(manifest, currentLock)) {
-      throw new ManifestError({
-        code: ErrorCode.LOCKFILE_OUTDATED,
-        filePath: `${options.cwd}/skills-lock.yaml`,
-        message:
-          'Lockfile is out of sync with manifest. Run install without --frozen-lockfile to update.',
-      })
-    }
+  try {
+    if (options.frozenLockfile) {
+      // Frozen mode: lock must exist and be in sync
+      if (!currentLock) {
+        throw new ManifestError({
+          code: ErrorCode.LOCKFILE_NOT_FOUND,
+          filePath: `${options.cwd}/skills-lock.yaml`,
+          message:
+            'Lockfile is required in frozen mode but none was found. Run "spm install" first.',
+        })
+      }
+      if (!isLockInSync(manifest, currentLock)) {
+        throw new ManifestError({
+          code: ErrorCode.LOCKFILE_OUTDATED,
+          filePath: `${options.cwd}/skills-lock.yaml`,
+          message:
+            'Lockfile is out of sync with manifest. Run install without --frozen-lockfile to update.',
+        })
+      }
 
-    await fetchSkillsFromLock(options.cwd, manifest, currentLock)
-    await linkSkillsFromLock(options.cwd, manifest, currentLock)
+      reporter.start(totalSkills)
+      started = true
+      for (const skillName of Object.keys(currentLock.skills)) {
+        onProgress({ type: 'resolved', skillName })
+      }
 
-    return { status: 'installed', installed: Object.keys(currentLock.skills) } as const
-  }
+      reporter.setPhase('fetching')
+      await fetchSkillsFromLock(options.cwd, manifest, currentLock, { onProgress })
+      reporter.setPhase('linking')
+      await linkSkillsFromLock(options.cwd, manifest, currentLock, { onProgress })
+      reporter.setPhase('finalizing')
+      reporter.complete()
 
-  // Normal mode: sync lock with manifest (may trigger network requests)
-  const lockfile = await syncSkillsLock(options.cwd, manifest, currentLock)
+      return { status: 'installed', installed: Object.keys(currentLock.skills) } as const
+    }
 
-  await fetchSkillsFromLock(options.cwd, manifest, lockfile)
-  await linkSkillsFromLock(options.cwd, manifest, lockfile)
+    // Normal mode: sync lock with manifest (may trigger network requests)
+    reporter.start(totalSkills)
+    started = true
+    const lockfile = await syncSkillsLock(options.cwd, manifest, currentLock, { onProgress })
 
-  // Write lockfile only after all operations succeed (atomicity)
-  await writeSkillsLock(options.cwd, lockfile)
+    reporter.setPhase('fetching')
+    await fetchSkillsFromLock(options.cwd, manifest, lockfile, { onProgress })
+    reporter.setPhase('linking')
+    await linkSkillsFromLock(options.cwd, manifest, lockfile, { onProgress })
 
-  return { status: 'installed', installed: Object.keys(lockfile.skills) } as const
+    // Write lockfile only after all operations succeed (atomicity)
+    reporter.setPhase('finalizing')
+    await writeSkillsLock(options.cwd, lockfile)
+    reporter.complete()
+
+    return { status: 'installed', installed: Object.keys(lockfile.skills) } as const
+  } catch (error) {
+    if (started) {
+      reporter.fail()
+    }
+    throw error
+  }
 }

packages/skills-package-manager/src/config/syncSkillsLock.ts

@@ -6,7 +6,7 @@ import { promisify } from 'node:util'
 import { ErrorCode, GitError, ParseError } from '../errors'
 import { normalizeSpecifier } from '../specifiers/normalizeSpecifier'
 import { sha256 } from '../utils/hash'
-import type { SkillsLock, SkillsLockEntry, SkillsManifest } from './types'
+import type { InstallProgressListener, SkillsLock, SkillsLockEntry, SkillsManifest } from './types'
 
 const execFileAsync = promisify(execFile)
 
@@ -132,10 +132,14 @@ export async function syncSkillsLock(
   cwd: string,
   manifest: SkillsManifest,
   _existingLock: SkillsLock | null,
+  options?: {
+    onProgress?: InstallProgressListener
+  },
 ): Promise<SkillsLock> {
   const entries = await Promise.all(
     Object.entries(manifest.skills).map(async ([skillName, specifier]) => {
       const { skillName: resolvedName, entry } = await resolveLockEntry(cwd, specifier, skillName)
+      options?.onProgress?.({ type: 'resolved', skillName: resolvedName })
       return [resolvedName, entry] as const
     }),
   )

packages/skills-package-manager/src/config/types.ts

@@ -58,3 +58,10 @@ export type InstallCommandOptions = {
   cwd: string
   frozenLockfile?: boolean
 }
+
+export type InstallProgressEvent =
+  | { type: 'resolved'; skillName: string }
+  | { type: 'added'; skillName: string }
+  | { type: 'installed'; skillName: string }
+
+export type InstallProgressListener = (event: InstallProgressEvent) => void

packages/skills-package-manager/src/index.ts

@@ -15,6 +15,8 @@ export type {
   AddCommandOptions,
   InitCommandOptions,
   InstallCommandOptions,
+  InstallProgressEvent,
+  InstallProgressListener,
   NormalizedSpecifier,
   SkillsLock,
   SkillsLockEntry,
@@ -56,6 +58,7 @@ export {
   installStageHooks,
   linkSkillsFromLock,
 } from './install/installSkills'
+export { createInstallProgressReporter } from './install/progressReporter'
 // Specifiers
 export { normalizeSpecifier } from './specifiers/normalizeSpecifier'
 export { parseSpecifier } from './specifiers/parseSpecifier'

packages/skills-package-manager/src/install/installSkills.ts

@@ -3,7 +3,7 @@ import { isLockInSync } from '../config/compareSkillsLock'
 import { readSkillsLock } from '../config/readSkillsLock'
 import { readSkillsManifest } from '../config/readSkillsManifest'
 import { syncSkillsLock } from '../config/syncSkillsLock'
-import type { SkillsLock, SkillsManifest } from '../config/types'
+import type { InstallProgressListener, SkillsLock, SkillsManifest } from '../config/types'
 import { writeSkillsLock } from '../config/writeSkillsLock'
 import { sha256 } from '../utils/hash'
 import { readInstallState, writeInstallState } from './installState'
@@ -29,6 +29,9 @@ export async function fetchSkillsFromLock(
   rootDir: string,
   manifest: SkillsManifest,
   lockfile: SkillsLock,
+  options?: {
+    onProgress?: InstallProgressListener
+  },
 ) {
   await installStageHooks.beforeFetch(rootDir, manifest, lockfile)
 
@@ -52,6 +55,7 @@ export async function fetchSkillsFromLock(
         extractSkillPath(entry.specifier, skillName),
         installDir,
       )
+      options?.onProgress?.({ type: 'added', skillName })
       continue
     }
 
@@ -64,6 +68,7 @@ export async function fetchSkillsFromLock(
         entry.resolution.path,
         installDir,
       )
+      options?.onProgress?.({ type: 'added', skillName })
       continue
     }
 
@@ -85,6 +90,9 @@ export async function linkSkillsFromLock(
   rootDir: string,
   manifest: SkillsManifest,
   lockfile: SkillsLock,
+  options?: {
+    onProgress?: InstallProgressListener
+  },
 ) {
   const installDir = manifest.installDir ?? '.agents/skills'
   const linkTargets = manifest.linkTargets ?? []
@@ -93,12 +101,16 @@ export async function linkSkillsFromLock(
     for (const linkTarget of linkTargets) {
       await linkSkill(rootDir, installDir, linkTarget, skillName)
     }
+    options?.onProgress?.({ type: 'installed', skillName })
   }
 
   return { status: 'linked', linked: Object.keys(lockfile.skills) } as const
 }
 
-export async function installSkills(rootDir: string, options?: { frozenLockfile?: boolean }) {
+export async function installSkills(
+  rootDir: string,
+  options?: { frozenLockfile?: boolean; onProgress?: InstallProgressListener },
+) {
   const manifest = await readSkillsManifest(rootDir)
   if (!manifest) {
     return { status: 'skipped', reason: 'manifest-missing' } as const
@@ -119,13 +131,18 @@ export async function installSkills(rootDir: string, options?: { frozenLockfile?
       )
     }
     lockfile = currentLock
+    for (const skillName of Object.keys(lockfile.skills)) {
+      options?.onProgress?.({ type: 'resolved', skillName })
+    }
   } else {
     // Normal mode: sync lock with manifest (may trigger network requests)
-    lockfile = await syncSkillsLock(rootDir, manifest, currentLock)
+    lockfile = await syncSkillsLock(rootDir, manifest, currentLock, {
+      onProgress: options?.onProgress,
+    })
   }
 
-  await fetchSkillsFromLock(rootDir, manifest, lockfile)
-  await linkSkillsFromLock(rootDir, manifest, lockfile)
+  await fetchSkillsFromLock(rootDir, manifest, lockfile, { onProgress: options?.onProgress })
+  await linkSkillsFromLock(rootDir, manifest, lockfile, { onProgress: options?.onProgress })
 
   // Write lockfile only after all operations succeed (atomicity)
   if (!options?.frozenLockfile) {