# Migration

> |

- **Type:** Skill
- **Install:** `agentstack add skill-cumulocity-iot-cumulocity-skills-migration`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Cumulocity-IoT](https://agentstack.voostack.com/s/cumulocity-iot)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Cumulocity-IoT](https://github.com/Cumulocity-IoT)
- **Source:** https://github.com/Cumulocity-IoT/cumulocity-skills/tree/main/skills/migration

## Install

```sh
agentstack add skill-cumulocity-iot-cumulocity-skills-migration
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Cumulocity Web SDK Migration Skill

## Overview

This skill guides you through a full migration of a Cumulocity Web SDK application from
one version to another. It combines three tools into a single repeatable workflow:

1. **[ui-breaking-changes-cli](https://github.com/Cumulocity-IoT/ui-breaking-changes-cli)** — detect every breaking change between the two SDK versions
2. **`new-app` skill** — scaffold a clean reference project at the target version
3. **`code-quality-analysis` skill** — verify the migrated code meets quality standards

---

## Prerequisites

Before starting, identify:

| Variable | Description | Example |
|---|---|---|
| `FROM_VERSION` | Your current `@c8y/ngx-components` version | `y2025-lts`, `1021.22.50` |
| `TO_VERSION` | The target SDK version | `y2026-lts`, `cd` |
| `PROJECT_ROOT` | Absolute path to the app you are migrating | `/home/user/my-c8y-app` |

To find your current version:

```bash
cat package.json | grep '@c8y/ngx-components'
```

---

## Step 1 — Detect Breaking Changes

Use the `ui-breaking-changes-cli` to get a full report of everything that changed between
your current and target versions.

### Install the CLI

Download the latest `.tgz` from the
[GitHub Releases](https://github.com/Cumulocity-IoT/ui-breaking-changes-cli/releases) page,
then extract and run it directly — no global install required:

```bash
tar -xzf c8y-breaking-changes-cli-v*.*.*.tgz
```

Alternatively, build from source:

```bash
git clone https://github.com/Cumulocity-IoT/ui-breaking-changes-cli.git
cd ui-breaking-changes-cli
pnpm install
pnpm build
```

### Run the report

The CLI accepts several version alias formats for `--from` and `--to`:

| Format | Examples |
|---|---|
| LTS alias | `y2025-lts`, `y2026-lts` |
| Year alias | `y2025`, `y2026` |
| Minor / stable line | `1021`, `1023`, `1021.22` |
| Full patch version | `1021.22.145`, `1023.13.2` |
| Continuous delivery | `cd` — resolves to the current latest tag on npm |

> **Version format**: use the `y`-prefixed dist-tag form (`y2026-lts`) — this is what
> `npm dist-tags @c8y/websdk` will show and what the breaking-changes-cli resolves against.
> The un-prefixed form (`2026-lts`) is also accepted by the CLI but is not a real npm tag.

```bash
# Human-readable overview
node index.js --from  --to 

# Markdown output — paste into a PR or issue for tracking
node index.js --from  --to  --format markdown

# Breaking changes only (suppress NOTABLE / INFO noise)
node index.js --from  --to  --breaking-only

# Angular-specific breaking changes only
node index.js --from  --to  --breaking-only --category angular

# Generate grep patterns to locate affected symbols in your codebase
node index.js --from  --to  --show-grep
```

### Process the report

For each item in the report:

1. Note the **severity** (`BREAKING`, `NOTABLE`, `INFO`) and **category** (`angular`,
   `websdk-ui`, `rest-api`, `security`, `migration`).
2. Use the grep patterns from `--show-grep` to find affected usages in the project:
   ```bash
   grep -rn "" /src
   ```
3. Create a tracking list of all `BREAKING` items — these must be resolved before the app
   will compile or run correctly.

---

## Step 2 — Scaffold a Reference App at the Target Version

Read and follow the **`new-app` skill** (`skills/new-app/SKILL.md`) to generate a fresh
application at `TO_VERSION`. Use a temporary directory so it does not interfere with the
project being migrated:

```bash
mkdir /tmp/c8y-reference-app
cd /tmp/c8y-reference-app
# … follow new-app skill steps with ng add @c8y/websdk@ (e.g. y2026-lts)
```

The reference app provides the canonical shape of every generated file at the target
version — use it as the ground truth for the comparison in Step 3.

---

## Step 3 — Compare Configuration Files

Diff the following files between the **reference app** (target version) and your
**project** (current version). For each file, apply the changes needed to align your
project with the new structure.

### Files to compare

| File | What to look for |
|---|---|
| `src/app/app.ts` | `ApplicationOptions`, feature flags, `runTime` / `buildTime` changes |
| `src/bootstrap.ts` | Bootstrap function signature, standalone vs. module-based setup |
| `angular.json` | `builder` targets, `styles` array, `assets` paths, budget thresholds |
| `package.json` | `@c8y/*` package versions, peer dependency constraints, scripts |
| `src/app/app.module.ts` | Module imports, lazy-loaded routes, removed / replaced modules |
| `src/app/app-routing.module.ts` | Route guards, lazy chunk syntax changes |
| `tsconfig.json` / `tsconfig.app.json` | `target`, `lib`, `strictTemplates`, decorator metadata |

### How to diff

Use VS Code's built-in diff, or run:

```bash
diff -u / /tmp/c8y-reference-app/
```

Or with `git diff` for colour output:

```bash
git diff --no-index / /tmp/c8y-reference-app/
```

### Applying changes

For each diffed file:

1. Copy new config keys / builder options that are missing from your project.
2. Remove keys that no longer exist in the reference app (they may have been renamed or
   deprecated).
3. Cross-reference with the breaking-changes report from Step 1 to confirm each change
   is intentional.
4. Do **not** blindly overwrite — preserve any project-specific customisations (app name,
   branding, custom routes, environment files).

---

## Step 4 — Apply Breaking-Change Fixes in Source Code

For each `BREAKING` item identified in Step 1:

1. Use the grep pattern to find all occurrences in `src/`.
2. Apply the fix described in the breaking-change entry (rename, API replacement,
   import path change, removed option, etc.).
3. After each fix, run the TypeScript compiler to catch regressions:
   ```bash
   npx tsc --noEmit
   ```
4. Optionally run the Angular build to surface template errors:
   ```bash
   ng build --configuration development
   ```

Repeat until `tsc --noEmit` and `ng build` both succeed without errors.

---

## Step 5 — Code Quality Review

Read and follow the **`code-quality-analysis` skill** (`skills/code-quality-analysis/SKILL.md`)
to run a full quality pass over the migrated source code.

Pay special attention to:

- **AP-01** — replace any leftover `*ngIf` / `*ngFor` / `*ngSwitch` with Angular's new
  control flow syntax (`@if`, `@for`, `@switch`) if the target version supports it.
- **AP-02** — excessive logic in components that should be moved to services.
- Any Cumulocity-specific anti-patterns flagged by the `mcp_c8y-docs_query-codex` queries
  (MCP server: `https://c8y-codex-mcp.schplitt.workers.dev/` — see `AGENTS.md` for setup).

Address all `BREAKING` and `HIGH` severity findings before considering the migration done.

---

## Checklist

Use this checklist to track migration progress:

- [ ] `FROM_VERSION` and `TO_VERSION` identified
- [ ] Breaking-changes report generated (`--format markdown` saved for reference)
- [ ] All `BREAKING` items catalogued
- [ ] Reference app scaffolded at `TO_VERSION`
- [ ] `app.ts` compared and updated
- [ ] `bootstrap.ts` compared and updated
- [ ] `angular.json` compared and updated
- [ ] `package.json` `@c8y/*` versions bumped and peer deps resolved
- [ ] `app.module.ts` / routing compared and updated
- [ ] `tsconfig.json` compared and updated
- [ ] All `BREAKING` source-code fixes applied
- [ ] `tsc --noEmit` passes
- [ ] `ng build` passes
- [ ] Code quality analysis completed
- [ ] All `HIGH` quality findings resolved

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Cumulocity-IoT](https://github.com/Cumulocity-IoT)
- **Source:** [Cumulocity-IoT/cumulocity-skills](https://github.com/Cumulocity-IoT/cumulocity-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cumulocity-iot-cumulocity-skills-migration
- Seller: https://agentstack.voostack.com/s/cumulocity-iot
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.