Package Registry

The MetaScript Package Registry at pkg.metascriptlang.org hosts packages for the MetaScript ecosystem.

Overview

Feature	Description
URL	pkg.metascriptlang.org
Auth	GitHub OAuth
Scopes	Personal (`@user`) and Organization (`@org`)
Access	Public (free) and Private (paid)
API	REST + GraphQL

Installing Packages

Add a Package

msc add @author/package
msc add @author/package@1.2.3    # Specific version
msc add @author/package@^1.0.0   # Version range

Remove a Package

msc remove @author/package

Update Packages

msc update                       # Update all
msc update @author/package       # Update one

Package Resolution

Version Ranges

Syntax	Meaning
`1.2.3`	Exact version
`^1.2.3`	Compatible with 1.2.3 (>=1.2.3 <2.0.0)
`~1.2.3`	Approximately 1.2.3 (>=1.2.3 <1.3.0)
`>=1.2.3`	Greater or equal
`*`	Any version

Lock File

ms.lock ensures reproducible builds:

msc install          # Uses lock file
msc install --fresh  # Ignores lock file

Publishing

Prerequisites

GitHub account
Logged in: msc login
Valid package.json

Publish Command

msc publish

Version Management

msc version patch    # 1.0.0 -> 1.0.1
msc version minor    # 1.0.0 -> 1.1.0
msc version major    # 1.0.0 -> 2.0.0
msc version 2.0.0    # Set explicit version

Pre-release Versions

msc version prerelease --preid=alpha   # 1.0.0-alpha.0
msc version prerelease --preid=beta    # 1.0.0-beta.0
msc version prerelease --preid=rc      # 1.0.0-rc.0

Package Manifest

Required Fields

{
  "name": "@scope/package",
  "version": "1.0.0",
  "metascript": {
    "entry": "src/index.ms",
    "targets": ["js"]
  }
}

Optional Fields

{
  "description": "What the package does",
  "keywords": ["utility", "helper"],
  "author": "Name <email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo"
  },
  "homepage": "https://docs.example.com",
  "bugs": "https://github.com/user/repo/issues"
}

MetaScript Config

{
  "metascript": {
    "entry": "src/index.ms",
    "targets": ["js", "c", "erlang"],
    "exports": {
      ".": "./src/index.ms",
      "./utils": "./src/utils.ms"
    },
    "backends": {
      "c": {
        "optimize": "size"
      },
      "js": {
        "module": "esm"
      }
    }
  }
}

Organizations

Create Organization

Visit pkg.metascriptlang.org/orgs/new or:

msc org create myorg

Manage Members

msc org add myorg username --role=member
msc org add myorg username --role=admin
msc org remove myorg username
msc org list myorg

Roles

Role	Permissions
Owner	Full control, billing, delete org
Admin	Manage members, publish, settings
Member	Publish packages

Profiles & Identity

Your Public Profile

Every user has a public profile at pkg.metascriptlang.org/@username:

@username
├── Avatar (from GitHub)
├── Display name
├── Bio
├── Links (GitHub, website, Twitter)
├── Published packages
├── Organizations
└── Followers count

Edit Profile

Update your profile at pkg.metascriptlang.org/account/settings or via CLI:

msc profile set --bio "Building cool stuff"
msc profile set --website "https://example.com"
msc profile set --twitter "@username"

Following

Follow packages and users to stay updated on new releases.

Follow a Package

msc follow @author/package

Or click "Follow" on any package page.

Follow a User

msc follow @username

Get notified when they publish new packages.

Unfollow

msc unfollow @author/package
msc unfollow @username

Release Notifications

When packages you follow release new versions, you'll be notified via:

Channel	Description
Email digest	Weekly summary of releases (configurable)
Discord feed	Real-time notifications in your server
RSS feed	`pkg.metascriptlang.org/@username/feed.xml`

Configure notifications at pkg.metascriptlang.org/account/notifications.

Package pages display:

Followers count - How many users follow this package
Used by - Public projects depending on this package
Maintainers - Who maintains the package

@author/json
├── 1,234 followers
├── Used by 567 packages
└── Maintained by @author, @contributor

This helps developers evaluate package adoption and trustworthiness.

API Keys

Generate API keys for CI/CD automation:

msc token create --name "github-actions" --expires 90d

Manage keys at pkg.metascriptlang.org/account/tokens.

Scope	Permission
`read`	Download packages, view profiles
`publish`	Upload new versions
`admin`	Manage org members, settings

Access Control

Public Packages

Default. Anyone can install.

msc publish --access=public

Private Packages

Restricted to organization members.

msc publish --access=restricted

Requires paid organization plan.

Deprecation

Mark a package as deprecated:

msc deprecate @scope/package "Use @scope/new-package instead"

Remove deprecation:

msc deprecate @scope/package --undo

Security

Package Signing

All packages are signed with the publisher's key:

msc verify @scope/package

Vulnerability Reports

Report security issues:

Email: security@metascriptlang.org
GPG key available at metascriptlang.org/security

Audit

Check for known vulnerabilities:

msc audit
msc audit --fix  # Auto-update vulnerable packages

API

REST API

Base URL: https://api.pkg.metascriptlang.org/v1

# Get package info
GET /packages/@scope/name

# Get specific version
GET /packages/@scope/name/1.0.0

# Search packages
GET /search?q=query&limit=20

# Download tarball
GET /packages/@scope/name/-/name-1.0.0.tgz

Authentication

Authorization: Bearer <token>

Get token: msc token create

GraphQL API

Endpoint: https://api.pkg.metascriptlang.org/graphql

query {
  package(name: "@scope/name") {
    name
    description
    versions {
      version
      publishedAt
      downloads
    }
    maintainers {
      username
    }
  }
}

Mirrors

Configure Mirror

msc config set registry https://mirror.example.com

Reset to Default

msc config delete registry

Policies

Naming

Lowercase only
No spaces (use hyphens)
Scoped names required for new packages
No trademark infringement

Retention

Published versions are immutable
Unpublish allowed within 72 hours
After 72 hours, contact support

Rate Limits

Action	Limit
Install	1000/hour
Publish	100/day
Search	100/minute
API	5000/hour

Troubleshooting

Common Errors

401 Unauthorized

msc login  # Re-authenticate

403 Forbidden

# Check package access
msc access list @scope/package

409 Version Exists

# Bump version
msc version patch
msc publish

413 Package Too Large

Maximum package size: 100MB
Check .npmignore or files in package.json

Next Steps

Ship a package in 5 minutes - Step-by-step guide
CLI Reference - All msc commands
MetaScript Build - Project configuration