0.1.4

Overview — main story

This release (0.1.4) adds a migration utility to the CLI that helps move repository-style entity files from slug-based identifiers to UUID-based identifiers. The new subcommand is protokoll migrate entities. The release also bumps the package version to 0.1.4 and wires the migrate command into the main CLI entrypoint.

The key purpose is to provide a safe dry-run and an executable migration path to convert existing YAML entity files to UUID ids and new filenames while preserving the old slug value.

What changed

• New command: protokoll migrate entities
  • Location: src/commands/migrate.ts (153 new lines)
  • Registered with the CLI in src/main.ts
• package.json version set to 0.1.4
• Minor changes to vitest config (non-functional for runtime users)

What the new migrate command does

• Scans a context directory (default: current working directory) for entity folders:
  • people, projects, companies, terms, ignored
• For each YAML file in those directories:
  • If the entity already has a UUID-like id, it is skipped.
  • Otherwise it:
    • Generates a new UUID
    • Sets entity.id to the new UUID
    • Adds entity.slug containing the old id (preserves the slug)
    • Writes the entity to a new file named {uuid-prefix}-{slug}.yaml (uuid prefix = first 10 chars of the UUID)
    • Removes the old file (only when executing, not on dry-run)
• Dry-run is the default behavior: it prints a full migration plan without changing files
• To perform changes, run with --execute
• The command prints a grouped migration plan summary (by entity type) showing old ID, new ID and new filename for each file

Example usage:

• Dry run (default):
  • protokoll migrate entities --context ~/path/to/context
• Execute:
  • protokoll migrate entities --context ~/path/to/context --execute

Problems this release solves

• Provides a tool to safely upgrade repository entities from slug-based identifiers to UUIDs.
• Makes it easy to preview the impact of the migration (dry-run) and then perform it.
• Preserves old slug values in the newly added slug field so references using slugs can be reconciled.

Impact on users and developers

• Users:
  • New CLI functionality for migrating content stores to UUID-based ids. This is especially useful when multiple entities might have non-unique or collision-prone slugs and you want stable, globally unique identifiers.
  • Default behavior is non-destructive (dry-run). Running the command without --execute will not modify files.
  • When run with --execute, files will be renamed and old files deleted. Back up your context directory before executing a migration.
• Developers:
  • A new module (src/commands/migrate.ts) implementing the migration logic. It uses js-yaml and fs/promises; js-yaml is already in dependencies.
  • The CLI bootstrapping in src/main.ts now imports and registers the migrate commands.
  • No changes to public programmatic APIs were made beyond adding the CLI command; there are no changes to exported SDKs or network protocols in this release.

Breaking changes and important considerations

• There are no breaking changes to programmatic APIs or to how the CLI arguments work elsewhere.
• The migration operation itself is destructive when executed:
  • When you run with --execute the script writes new files and deletes the old ones. If you have other tooling that expects filenames or ids in the old slug format, those tools will need to be updated to use the new UUID ids or to read the new slug field.
  • The new filename format is {uuidPrefix}-{oldSlug}.yaml (uuidPrefix = first 10 characters of the UUID). Any external references to filenames must be updated accordingly.
• Recommendation: always run the command in dry-run mode first (default) to review the generated migration plan. Back up your context directory prior to running with --execute.
• The migration logic detects existing UUIDs by a regex and skips files that already appear to use UUIDs, so repeated runs will not re-migrate files that already contain UUID ids.

Files/areas changed (high level)

• src/commands/migrate.ts — New migration implementation and CLI action (primary change)
• src/main.ts — Register new migrate commands with the CLI
• package.json — Version bumped to 0.1.4 and dependency/dev-dependency updates persisted in the same commit
• vitest.config.ts — minor non-functional change

Notes for maintainers

• The migration function returns a MigrationPlan[] (used to produce the dry-run report). The function signature and interface are new and used internally in the CLI command.
• The command uses Node 24+ APIs (fs/promises, crypto.randomUUID) — consistent with the package engines constraint (node >= 24.0.0).
• Consider adding integration tests for migrate command behavior (dry-run vs execute) and a safety/backup prompt if you want additional guardrails before destructive operations.

Summary

Version 0.1.4 introduces a practical migration tool to convert slug-based entity files to UUID-based ids with a safe dry-run mode and an executable migration path. No programmatic breaking API changes were introduced, but running the migration with --execute will rename and remove files and therefore requires caution and backups.