CPM — Cpyte Package Manager

A compiler-pipeline dependency resolver and installer for the Cpyte programming language.

import @std.json
          ↓
Resolve → Lower → Optimize → Execute

Install

pip install cpyte-cpm

Note: CPM uses the Cpyte package registry at https://cypackage.5gnew.io.vn/ as the default package source for Cpyte packages. The default registry is configured in pyproject.toml.

Quick Start

cpm init                        # create cpytoml
cpm add @std/json@^2.0          # add a dependency
cpm install                     # install all from manifest

Commands

Global Flags

-v, --verbose        Verbose output
-q, --quiet          Suppress output
-y, --yes            Auto-confirm prompts
--offline            Offline mode (skip network)
--no-cache           Disable cache
--config <path>      Custom config / repo URL
--target <platform>  Target platform (e.g. linux/x86_64)
--llvm-version <V>   LLVM version for prebuilt packages

Manifest (cpytoml)

[cpm]
name = "my-app"
version = "1.0"
prebuilt = false
llvm_version = "18.1.0"

[cpm.target]
os = "linux"
arch = "x86_64"
features = ["gui", "ssl"]

[cpm.dependencies]
"@std/json" = "^2.0"
"@std/http" = "1.0"
"package_a" = "latest"

Claims System

Packages declare platform support; CPM filters based on your target.

Package metadata (registry):

{
  "name": "win32-api",
  "claims": { "os": ["windows"], "arch": ["x86_64"] }
}

Resolution:

Auto-detects from current platform when no target is specified.

Prebuilt Mode

When the registry serves precompiled LLVM IR:

[cpm]
prebuilt = true
llvm_version = "18.1.0"

CPM fetches .ll artifacts from metadata/prebuilt/... and skips source packages with incompatible LLVM versions (major version must match).

Lockfile (cpm.lock)

Auto-generated. Pins exact versions for reproducible builds.

[[package]]
name = "@std/json"
version = "2.0.3"
resolved = "https://repo.example.com/group/std/json/2.0.3.tar.gz"
checksum = "sha256:abc123..."
dependencies = ["@std/encoding@1.2.0"]
llvm_version = "18.1.0"
cpyte_version = "2.6.0"

Prebuilt packages are also filtered by the Cpyte compiler version: a prebuilt artifact whose cpyte_version differs in major version from the detected compiler is skipped during resolution.

Toolchain Integration

CPM is a compiler-pipeline package manager: it feeds the Cpyte compiler.

• cpm build compiles your project through the Cpyte compiler toolchain (cpy binary, falling back to python -m cpyte) rather than an internal build script.
• cpm exec <file.cpy> JIT-runs any .cpy file through the compiler.
• cpm run <script> resolves <script>.cpy scripts through the compiler JIT before falling back to plain Python.
• cpm publish validates package.json with the compiler's own ManifestParser / ManifestValidator before uploading, and auto-pins the detected compiler version for prebuilt artifacts.
• Prebuilt dependency resolution checks the compiler version (major must match).
• cpm doctor reports the detected compiler, module path, LLVM version, and project state in a single panel.
• Installed extension packages are auto-discovered by the compiler from .cpm/modules/, including scoped packages like @std/json.

cpm doctor

┌─ Toolchain Diagnostics ──────────────┐
│  detected   : yes                    │
│  version    : 2.6.0                  │
│  binary     : /…/.venv/bin/cpy       │
│  module     : /…/site-packages/cpyte │
│  llvm       : 18.1.8                 │
└──────────────────────────────────────┘
┌─ Project ────────────────────────────┐
│  name       : my-app                 │
│  manifest   : /…/cpytoml             │
│  .cpm dir   : present                │
└──────────────────────────────────────┘
✓ Toolchain looks good

Terminal Effects

CPM ships a pure-ANSI effect layer (cpyte_cpm.cli.style) with TTY detection and NO_COLOR / FORCE_COLOR support:

• Gradient banner (cpm with no command) — ASCII-art logo in a blue→green gradient
• Pipeline diagram — Resolve ▸ Lower ▸ Optimize ▸ Execute
• Animated spinner — threaded ◐ ◓ ◑ ◒ animation for long operations
• Inline progress bar — ████████░░░░░ 5/10 installing
• Box panels — bordered diagnostic panels (cpm doctor)
• Gradient text, rainbow, pulse effects plus the full status glyph set (✓ ✗ ⚠ ▸ ●)

All effects disable automatically on non-TTY output, --quiet, or NO_COLOR.

Directory Layout

~/.cpm/
├── cache/<name>/<version>/     # downloaded archives
└── modules/<name>/<version>/   # extracted packages

Additional Commands

Package Information

cpm info @std/json          # Show package metadata and details

Displays:

• Package version and URL
• Platform claims (OS, architecture, features)
• Dependencies
• Installation status

List Installed Packages

cpm list                    # List all installed packages in current project

Shows installed packages with versions from the lockfile, with status indicators.

Validate Project

cpm validate                # Validate manifest and lockfile

Checks:

• Manifest TOML syntax
• Required fields (name, version)
• Dependency declarations
• Lockfile presence and consistency
• Target platform configuration

Search Packages

cpm search json             # Search for packages matching a query

Searches both local installed packages and remote registry.

Extension Packages

CPM supports extension packages that extend the Cpyte compiler with custom syntax, keywords, operators, and compiler hooks. Extension packages use a package.json manifest to declare their capabilities.

Extension Package Structure

.cpm/modules/
├── package_name/                    # unscoped packages
│   └── version/
│       ├── package.json             # Extension manifest
│       ├── parser_hooks.py          # Custom syntax parsing
│       ├── semantic_hooks.py        # Type checking extensions
│       ├── codegen_hooks.py         # LLVM IR generation
│       ├── runtime_hooks.py         # Runtime code injection
│       ├── *.cpy                    # Main entry point (optional)
│       └── *.ll                     # Prebuilt LLVM IR (optional)
└── @scope/                          # scoped packages (e.g. @std)
    └── name/                        # e.g. json
        └── version/
            └── package.json

package.json Format

{
  "name": "package_name",
  "version": "1.0.0",
  "capabilities": {
    "keywords": ["async", "await", "defer"],
    "operators": ["~~"],
    "tags": ["@async", "@callback"],
    "macros": ["async_def"],
    "custom_types": ["Promise", "Future"]
  },
  "extensions": {
    "parser_hooks": ["parser_hooks.py"],
    "semantic_hooks": ["semantic_hooks.py"],
    "codegen_hooks": ["codegen_hooks.py"],
    "runtime_hooks": ["runtime_hooks.py"]
  },
  "dependencies": [],
  "metadata": {
    "description": "Package description",
    "author": "Author name",
    "license": "MIT"
  }
}

Extension Capabilities

• Keywords: Custom language keywords that extend the lexer
• Operators: Custom operators for expressions
• Tags: Custom tags for annotations and metadata
• Macros: Compile-time macro definitions
• Custom Types: New type definitions

Extension Hooks

• Parser Hooks: Extend the parser with custom syntax rules
• Semantic Hooks: Add custom type checking and analysis rules
• Codegen Hooks: Extend LLVM IR generation
• Runtime Hooks: Inject runtime code and libraries

Extension-Only Packages

Packages can provide only extensions without any .cpy or .ll files. These packages:

• Provide keywords, operators, and compiler hooks
• Can be imported successfully by the compiler
• Are useful for language feature extensions

Viewing Extension Capabilities

cpm info package_name      # Shows extension capabilities if available

The cpm info command displays extension capabilities for installed packages:

Extension Capabilities:
  Keywords: async, await, defer
  Operators: ~~
  Tags: @async, @callback
  Custom Types: Promise, Future
  Extension Hooks:
    Parser: parser_hooks.py
    Semantic: semantic_hooks.py
    Codegen: codegen_hooks.py
    Runtime: runtime_hooks.py

Package Discovery

Extension packages are discovered automatically by the Cpyte compiler:

• Pre-loaded before compilation from .cpm/modules/
• Keywords registered during lexing
• Hooks loaded during appropriate compilation phases
• No CPM configuration required

License

MIT