Cockpit Package Manager Development

Expert development assistant for the Cockpit Package Manager project - a web-based package management interface using PackageKit D-Bus API, React 18, TypeScript, and PatternFly 6.

Scope & Context

**Critical**: These rules ONLY apply when working with files in `/cockpit-package-manager/` directory. Always verify you're in the correct project context before applying these guidelines.

This skill provides specialized knowledge for:

Architecture Overview

Tech Stack Components

1. **Frontend Layer**

- React 18 with functional components and hooks

- TypeScript in strict mode (no `any` types)

- PatternFly 6 for UI components

- cockpit.js for system integration

2. **Build Pipeline**

- esbuild for bundling (TypeScript → JavaScript)

- External cockpit.js (provided by Cockpit runtime)

- Development: watch mode with sourcemaps

- Production: minified single-file output

3. **Backend Integration**

- PackageKit D-Bus API (via `packagekit.ts` wrapper)

- Type-safe transaction handling

- Progress callbacks for long operations

- Error handling with TransactionError

Key Files Structure

Development Workflow

Build Commands

When building the project, use:

```bash

Development with auto-rebuild

npm run watch

Production build

NODE_ENV=production npm run build

Type checking only

npm run typecheck

```

Manual Testing Cycle

1. Build the project: `npm run build`

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

3. Access via browser: `http://localhost:9090`

4. Open browser console to check for errors

5. Test different package states (installed, available, updates)

Troubleshooting Common Issues

**PackageKit not responding**: Verify service status with `systemctl status packagekit`

**Permission denied errors**: Enable Cockpit superuser mode in the UI

**Build failures**: Confirm Node.js version is 18 or higher

**TypeScript errors**: Run `npm run typecheck` for full type error report

Code Patterns & Standards

PackageKit Transaction Pattern

```typescript

import * as PK from './packagekit';

// Search for packages

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

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

// Progress object includes cancel flag for user cancellation

});

// Install package with progress tracking

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

setProgress(progress.percentage);

});

```

Error Handling Pattern

```typescript

try {

await PK.installPackage(packageName, setProgress);

} catch (error) {

if (error instanceof TransactionError) {

showError(`Installation failed: ${error.detail}`);

} else {

showError('Unexpected error occurred');

}

}

```

Component Structure Pattern

Follow Cockpit codebase conventions:

1. Functional components with React hooks

2. Strict TypeScript - no `any` types allowed

3. Try-catch blocks with user-friendly error messages

4. Progress callbacks for long-running operations

5. ARIA labels and keyboard navigation for accessibility

PackageKit API Reference

The `packagekit.ts` wrapper provides these methods:

**Search Operations**:

**Package Operations**:

**Dependency Analysis**:

**System Operations**:

All async operations return Promises and support progress callbacks.

Git Workflow Rules

**CRITICAL**: Always ask the user before:

Local operations (commits, branch creation) are safe to perform without asking.

Staging Changes

**Never use `git add .`** - Always specify files explicitly:

```bash

Good

git add src/packagekit.ts src/types.ts

Bad

git add .

```

Commit Message Format

Use conventional commit format:

Implementation Status

**Current Status**: Phase 1 complete (project setup & infrastructure)

See `IMPLEMENTATION_PLAN.md` for full roadmap.

**Next Phases**:

Local Configuration

For environment-specific instructions and configurations (local paths, test environments, custom setups), refer to `CLAUDE.local.md` - this file is gitignored and not committed to version control.

References & Resources

Important Constraints

1. **File scope**: These guidelines only apply to `/cockpit-package-manager/` files

2. **Type safety**: No `any` types - use proper TypeScript interfaces

3. **Cockpit integration**: Must use cockpit.js for all system interactions

4. **Build output**: Single-file bundle with externalized cockpit.js

5. **Testing**: Manual testing in Cockpit UI required before committing

6. **Git hygiene**: Explicit file staging, conventional commits, ask before pushing