Cockpit Package Manager Development

This skill guides development of a Cockpit-based package manager using PackageKit, React 18, TypeScript, and PatternFly 6.

Project Scope

⚠️ **THESE RULES ONLY APPLY TO FILES IN /cockpit-package-manager/**

This is a web-based package manager interface for Cockpit, inspired by Raspberry Pi's Add/Remove Software.

Architecture Overview

Tech Stack

Key Components

1. **packagekit.ts**: TypeScript wrapper around PackageKit D-Bus API

- Type-safe transaction handling

- Progress reporting

- Error handling

- All PackageKit methods (search, install, remove, dependencies)

2. **types.ts**: TypeScript type definitions

- PackageInfo, PackageDetails interfaces

- DebianSection structure

- ProgressData for operations

- ViewState for navigation

3. **Main UI Components** (to be implemented):

- `packagemanager.tsx`: Root component with routing

- `section-list.tsx`: Browse by Debian section

- `package-list.tsx`: List packages in section

- `package-details.tsx`: Detailed package view

PackageKit Integration

The wrapper provides these operations:

```typescript

// Search

searchNames(query): Promise<PackageInfo[]>

searchDetails(query): Promise<PackageInfo[]>

// Package information

getPackages(filter): Promise<PackageInfo[]>

getDetails(packageIds): Promise<PackageDetails[]>

// Operations

installPackage(name, progressCb): Promise<void>

removePackage(name, progressCb): Promise<void>

// Dependencies

getDependencies(packageId): Promise<string[]>

getReverseDependencies(packageId): Promise<string[]>

getFiles(packageId): Promise<string[]>

// Utilities

resolve(name): Promise<string>

refreshCache(progressCb): Promise<void>

detect(): Promise<boolean>

```

Development Workflow

Build Commands

```bash

Development build with watch

npm run watch

Production build

NODE_ENV=production npm run build

Type checking

npm run typecheck

```

esbuild Configuration

Code Patterns to Follow

Follow these patterns from cockpit codebase:

1. **Component Structure**: Functional components with hooks

2. **Type Safety**: Strict TypeScript, no `any` types

3. **Error Handling**: Try-catch with user-friendly messages

4. **Progress Reporting**: Show progress for long operations

5. **Accessibility**: ARIA labels, keyboard navigation

Example: PackageKit Transaction

```typescript

import * as PK from './packagekit';

// Search packages

const packages = await PK.searchNames('nginx', (progress) => {

console.log(`Progress: ${progress.percentage}%`);

if (progress.cancel) {

// User can cancel

}

});

// Install package

await PK.installPackage('nginx', (progress) => {

setProgress(progress.percentage);

});

```

Example: Error Handling

```typescript

try {

await PK.installPackage(name, setProgress);

} catch (error) {

if (error instanceof TransactionError) {

showError(`Failed to install: ${error.detail}`);

}

}

```

Testing Workflow

Manual testing steps:

1. Build: `npm run build`

2. Copy to Cockpit: `sudo cp -r packagemanager /usr/share/cockpit/`

3. Test in Cockpit: http://localhost:9090

4. Check browser console for errors

5. Test with different package states

Common Issues

**PackageKit not available**: Check `systemctl status packagekit`

**Permission errors**: Ensure cockpit superuser mode is enabled

**Build errors**: Check Node.js version (needs >= 18)

**Type errors**: Run `npm run typecheck` to see all type issues

Git Workflow

**IMPORTANT**: Always ask before:

Local commits and branch operations are fine.

Git Add Specificity

Always list specific files instead of using `git add .` to avoid accidentally including unwanted changes.

Commit Message Format

Follow conventional commit format:

```

feat(section): add section browsing

fix(install): handle permission errors

docs: update README

```

Implementation Status

**Current status**: Phase 1 complete (Project setup & infrastructure)

**Next phases**:

See `IMPLEMENTATION_PLAN.md` for the full roadmap.

Local Configuration

For environment-specific instructions and configurations, check `CLAUDE.local.md` (not committed to version control).

References

Key Constraints

1. Only modify files within `/cockpit-package-manager/`

2. Maintain strict TypeScript typing

3. Use PatternFly 6 components for UI consistency

4. Handle all PackageKit operations asynchronously with progress callbacks

5. Always ask before git push or destructive remote operations

6. Require Node.js >= 18