Skip to main content

Supply Chain Rules

The Maya workspace keeps supply-chain checks static and offline. The verifier intentionally avoids package installation, registry lookups, browser runs, and network requests.

Package Metadata​

Every apps/*/package.json and projects/*/package.json package must declare:

  • description;
  • license;
  • homepage and bugs.url for publishable packages;
  • repository.type;
  • repository.url;
  • repository.directory;
  • keywords.

Publishable public packages must use a valid SPDX license and must not combine publishConfig.access: "public" with UNLICENSED. The current public package set is @maya/assistant-composition, @maya/assistant-protocol, and @maya/assistant-ui; all use MIT, backed by the root LICENSE file. Private workspace-only packages may remain UNLICENSED.

Package classification is machine-readable in tools/workspace-package-registry.mjs. npmPublishable controls npm release workflow participation. publicAbiSnapshot controls public declaration contract snapshots. These are separate axes: @maya/claude-workspace and @maya/data-lab-module have ABI snapshots for workspace-private validation, but they are not npm publishable in v0 and do not imply a plugin marketplace.

Publishable package homepage values point to the canonical .docs/packages/* consumption guide for that package. Package-root README files are still disallowed so there is no duplicate truth.

Workspace Configuration​

pnpm-workspace.yaml is part of the supply-chain allowlist. The packages list must stay approved as ["apps/*", "projects/*"], and allowBuilds must stay limited to reviewed native build packages. The current approved build allowlist is esbuild: true and core-js: true.

Dependency Specs​

Dependency ranges must stay registry or workspace scoped. The static verifier uses an allowlist instead of a denylist: it allows workspace: ranges, ordinary registry semver/range/tag specs, and npm aliases such as npm:<package>@<semver-or-tag>.

workspace:* is allowed for internal package links. Local path specs, including relative paths, absolute paths, Windows paths, file:, and link:, are not allowed. Any other protocol-like spec is rejected because it bypasses the normal lockfile and registry review path.

Lifecycle Scripts​

Project packages may keep local build, typecheck, dev, start, preview, prepack, and pack-check scripts. Install-time scripts such as postinstall, preinstall, install, and prepare are rejected in project package manifests because they execute during dependency installation.

Package Contents​

Publishable packages keep "files": ["dist", "LICENSE"]. Canonical package docs live under .docs; package-root README.md, dist/docs/*, and docs/* are not allowed as package documentation sources because they create duplicate truth. Package tarball smokes also reject those duplicate documentation files.

Run:

pnpm security:supply-chain
node tools/smoke-consumer.mjs --pack-only

pnpm security:supply-chain is the manual supply-chain entry point. It also writes .tmp/reports/supply-chain.json for CI artifact upload.

Root release, security, changelog, and ownership governance lives in .docs/release-governance.md, SECURITY.md, CHANGELOG.md, and .github/CODEOWNERS. Those files describe repository process and incident handling; they must not replace or duplicate the package consumption guides under .docs/packages.

Workflow Actions​

GitHub Actions must be pinned to commit SHAs in .github/workflows/*.yml and .github/workflows/*.yaml. Keep a short comment with the human version tag as the previous non-empty comment above each pinned external action so upgrades are reviewable without reintroducing tag drift.

CI reads the Node runtime from .node-version. npm publish is manual, protected by the npm-publish environment, and guarded to main or semver v* tags. A semver tag must match every package with npmPublishable: true in tools/workspace-package-registry.mjs before the workflow can publish. The publish workflow must run pnpm release:gate for the exact commit before any dry-run or real publish step. It grants id-token: write for npm provenance and publishes pnpm-packed tarballs so the release path matches pnpm pack:dry-run and pnpm smoke:consumer. Dry-run steps use npm publish "$tarball" --access public --provenance --dry-run; real publish steps use npm publish "$tarball" --access public --provenance only when the manual dry_run input is disabled.