finos / finos/architecture-as-code

Add a portable architecture export command to calm-cli

Open
#3,019 3 comments 0 reactions 0 assignees View on GitHub
cli
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

## Feature Proposal

### Target Project:
`cli` / `@finos/calm-cli`

### Description of Feature:
Add an `export` command to `calm-cli` that packages a CALM architecture and its related local resources into a portable ZIP archive.

The export should include the main architecture file, referenced node and dependency files, building blocks, and optionally additional files selected by the user. The resulting archive should preserve the relevant directory structure and include a manifest describing the bundled files, their original paths, sizes, types, and SHA-256 hashes.

This capability is needed to make CALM architectures easier to share, archive, migrate, and import into other CALM-enabled tools or environments. Users currently need to manually identify and copy all referenced files, which is error-prone and can result in incomplete or unusable architecture packages.

### User Stories:
- As a CALM architect, I want to export an architecture together with its referenced files so that I can share a complete architecture package with another team.
- As a platform engineer, I want to create a portable archive of an architecture and its building blocks so that I can move it between environments without manually reconstructing its dependencies.
- As a governance or audit user, I want to archive an immutable snapshot of an architecture and its supporting resources so that the architecture can be reviewed or reproduced later.
- As a CALM tool developer, I want the exported package to contain a manifest with content hashes so that files can be verified and deduplicated during a future import workflow.
- As a CLI user, I want to include additional documentation or configuration files in the export so that the package contains the context required to understand the architecture.

### Current Limitations:
`calm-cli` does not currently provide a supported command for creating a complete, portable architecture package.

Users must manually locate and copy:

- The primary architecture file.
- Files referenced by nodes or relationships.
- Building blocks.
- Files referenced by interfaces or other dependencies.
- Supporting documentation and configuration files.

Manual packaging can omit dependencies, lose the original directory structure, create filename conflicts, and make it difficult to verify that an exported package is complete.

### Proposed Implementation:
Add a new top-level command:

```bash
calm export -a -o
```

The command should:
* Accept a required architecture file path.
* Accept a required output ZIP path.
* Parse the architecture JSON before creating the archive.
* Discover referenced files from architecture nodes, relationships, interfaces, and building-block references.
* Discover building blocks under the architecture's building-blocks/ directory.
* Support optional additional files or directories through repeatable include patterns, for example:

```bash
calm export \
--architecture architecture.json \
--output architecture-bundle.zip \
--include-pattern "docs/**/*" \
--include-pattern "config/**/*"
```

* Preserve relative directory paths inside the archive.
* Avoid adding the same file more than once.
* Generate a MANIFEST.json containing:
* Manifest format version.
* Export timestamp.
* Main architecture filename.
* Original and archive-relative paths.
* File type.
* File size.
* SHA-256 content hash.
* Aggregate file count and size statistics.
* Provide a verbose logging option consistent with other CLI commands.
* Return a non-zero failure result when the architecture cannot be read or parsed, the output archive cannot be written, or a required dependency cannot be processed.
* Register the command in src/cli.ts and expose it through the packaged calm-cli executable.
* Keep the manifest format extensible for a future import command.

No CALM schema changes or data model changes are expected. The implementation should use existing CLI conventions and the repository's current TypeScript, Commander.js, Vitest, and archive tooling.

### Alternatives Considered:
* Manual file copying: Rejected because it is error-prone and does not reliably identify all transitive dependencies.
* Exporting only the main architecture JSON: Rejected because referenced nodes, building blocks, and supporting files are required to reconstruct or use the architecture.
* Using a workspace bundle as the export format: A workspace is useful for local development, but a self-contained ZIP archive is better suited for sharing, archiving, and transferring an architecture.
* Flattening all files into a single directory: Rejected because it can create filename collisions and removes useful directory context.
* Adding an import command in the same change: Deferred. The manifest should support a future import capability, but export can be delivered independently.

### Testing Strategy:
* Add unit tests for:
* Exporting a basic architecture.
Handling a missing or invalid architecture file.
* Discovering files referenced by nodes and relationships.
* Discovering building blocks.
* Including files supplied through include patterns.
* Avoiding duplicate files.
* Generating valid manifest metadata and SHA-256 hashes.
* Preserving archive-relative paths.
* Handling output and file-system errors.
* Add CLI-level tests confirming:
* The export command is registered.
* Required options are enforced.
* The command creates a valid ZIP archive.
* Verbose mode is accepted.
* Failures return an appropriate non-zero exit status.
* Inspect generated archives in tests to verify that the expected files and MANIFEST.json are present.
* Ensure existing CLI tests continue to pass.

### Documentation Requirements:
* Document the command in the CLI README.
* Add usage examples for:
* Basic export.
* Export with additional files.
* Verbose logging.
* Multiple include patterns.
* Document the archive layout and MANIFEST.json fields.
* Explain which CALM references and directories are automatically discovered.
* Note that import functionality is planned separately.
* Include the command in the CLI help output and command reference documentation.

### Implementation Checklist:
- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed

### Additional Context:
...add any other context, diagrams, mockups, or screenshots about the feature request here...

Contributor guide

Open the contributing guide

Research direction

Start at src/cli.ts and inspect existing CLI command conventions, then review the repository's current TypeScript, Commander.js, Vitest, and archive tooling. Use the stated unit and CLI testing strategy to identify coverage for dependency discovery, ZIP creation, manifests, errors, and include patterns. Done means a registered export command, valid archives with the required manifest, passing tests, and updated CLI README documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli, documentation, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.