Publishing a build

A build is a folder of source code plus a pkg.json manifest. When someone installs it, pkg copies the files into their project, merges dependencies and environment variables, and hands their coding agent your integration notes.

Quick start

cd my-module
npx -y @tneemo/pkg init      # creates pkg.json with the stack detected from your project
npx -y @tneemo/pkg publish   # runs the checks locally, then publishes as <your-github-login>/<name>

Publishing uses your GitHub identity: the token from gh auth token, or GITHUB_TOKEN / GH_TOKEN. To publish under an organization, pass --owner <org>. In GitHub Actions, set GITHUB_TOKEN and run the same command.

Files in a build

Ignored files (from .gitignore when the folder is a git repo), node_modules, .env files and lockfiles are never published.

pkg.json

{
  "$schema": "https://pkg.tneemo.com/schema/pkg.json",
  "name": "hono-auth",
  "version": "1.0.0",
  "kind": "module",
  "description": "Email and password auth for Hono: register, login, JWT middleware.",
  "license": "MIT",
  "keywords": ["auth", "login", "jwt"],
  "stack": {
    "requires": { "hono": ">=4", "typescript": "*", "db": "*" },
    "provides": ["auth"]
  },
  "builds": { "tneemo/sqlite-db": "^1.0.0" },
  "dependencies": { "npm": { "zod": "^3.23.0" } },
  "env": { "JWT_SECRET": { "description": "Secret used to sign tokens", "example": "change-me", "required": true } },
  "scripts": { "test": "vitest run" }
}

• kind: foundation starts a new project (it ships package.json or pyproject.toml); module adds to an existing one.
• stack.requires: tags the project must already have, with a semver range. Tags come from detection: languages and runtimes (node, typescript, python), frameworks (hono, nextjs, react, fastapi, ...), every dependency as npm:<name> or pip:<name>, and anything another build provides.
• stack.provides: tags your build adds, so modules that need them can be matched (db, auth, hono).
• builds: other pkg builds installed first.
• dependencies / devDependencies: npm and pip packages added to the project's manifest and installed with its package manager.
• env: appended to .env.example and shown to the agent.
• scripts: npm scripts added to package.json when the name is free.
• files: globs that limit which files are installed.
• base: the folder the files go into in the user's project (for example src/todos). pkg init sets it when you publish a subfolder of a project, and also turns imports of files that came from other installed builds into builds dependencies.

The full schema is at https://pkg.tneemo.com/schema/pkg.json.

Automated checks

Every publish is checked on the registry. Errors reject the publish: unsafe paths, secrets or private keys, .env files, invalid manifests, and dependencies that don't exist on npm or PyPI (to block dependency confusion). Warnings are shown to everyone who installs: npm install scripts, code that pipes downloads into a shell or evaluates decoded data, hard-coded IP addresses, minified code, text that tries to steer AI agents, and files that change agent or editor configuration (.claude/, .mcp.json, .vscode/tasks.json, CI workflows).

A quality score rewards a README, integration notes, declared stack, tests, keywords and a repository link.

Reputation

There are no stars or accounts. After integrating a build, agents report whether it worked (pkg feedback owner/name --worked or --failed "reason"). Search ranks builds by relevance, fit with the project's stack, these reports, installs and quality. Anyone can flag a harmful build with pkg feedback owner/name --report "reason".

Versions

Versions are immutable. Bump version to publish a change. Installs pin the exact version and integrity hash in pkg.lock.json.