Package Manager

The pkg command manages package.json, installs JSH packages, and runs package scripts. It is intended for JSH applications that keep their dependencies in a project directory such as /work.

Overview

The pkg command supports these tasks:

• Create a new package.json
• Install dependencies into node_modules
• Maintain package-lock.json
• Run commands defined in package.json scripts

package.json

A minimal package manifest looks like this.

{
  "name": "demo-app",
  "version": "1.0.0",
  "scripts": {
    "start": "./main.js"
  },
  "dependencies": {
    "generic-pkg": "^1.2.0",
    "github.com/acme/demo": "v1.1.0"
  }
}

Common fields used by pkg are:

pkg init

Creates a new package.json in the current project directory.

Syntax

pkg init [options] <name>

Options

• -C, --dir <dir> use the given project directory instead of the current working directory
• -h, --help show help

Usage example

/work > pkg init demo-app
Created /work/package.json

The generated file includes empty scripts and dependencies objects.

{
  "name": "demo-app",
  "version": "1.0.0",
  "scripts": {},
  "dependencies": {}
}

pkg install

Installs dependencies from package.json, or installs a single package request and updates both package.json and package-lock.json.

Syntax

pkg install [options] [name]

Options

• -C, --dir <dir> use the given project directory instead of the current working directory
• -h, --help show help

If name is omitted, pkg install installs the dependencies already declared in package.json.

npm packages

If the package name is not a GitHub repository path, pkg installs it from the npm registry.

/work > pkg install generic-pkg
Installed generic-pkg@1.2.0

This adds the dependency to package.json with the resolved npm version range.

{
  "dependencies": {
    "generic-pkg": "^1.2.0"
  }
}

GitHub repository packages

If the package name matches github.com/<org>/<repo>, pkg installs the repository contents directly from GitHub.

Supported forms are:

• github.com/<org>/<repo>
• github.com/<org>/<repo>@<tag>

Behavior:

• If @<tag> is specified, that tag is used.
• If no tag is specified and the repository has tags, the latest tag returned by the GitHub tags API is used.
• If no tag is specified and the repository has no tags, the repository default_branch is used.

Usage example: latest tag

/work > pkg install github.com/acme/demo
Installed github.com/acme/demo@v1.1.0

Usage example: explicit tag

/work > pkg install github.com/acme/demo@v1.0.0
Installed github.com/acme/demo@v1.0.0

Usage example: default branch fallback

If the repository has no tags, the default branch is used.

/work > pkg install github.com/acme/notags
Installed github.com/acme/notags@main

Installation target

Installed packages are copied into the project node_modules directory. For example:

• generic-pkg -> node_modules/generic-pkg
• github.com/acme/demo -> node_modules/github.com/acme/demo

Lock file behavior

pkg writes package-lock.json and stores the resolved source for reproducible installs. For GitHub packages, the resolved source includes whether the install used a tag or a branch.

Examples:

• github.com/acme/demo#tag=v1.1.0
• github.com/acme/notags#branch=main

When a lock file is present, pkg install reuses the locked GitHub ref instead of resolving a new one.

Error reporting

If pkg cannot determine a GitHub ref, it reports both resolution steps. For example, it can report a tags lookup failure together with a default branch lookup failure.

pkg run

Runs a named entry from package.json scripts.

Syntax

pkg run [options] <key> [...args]

Options

• -C, --dir <dir> use the given project directory instead of the current working directory
• -h, --help show help

pkg run changes the current working directory to the selected project directory before executing the script. This means relative command paths such as ./main.js are resolved from the package directory.

Usage example

Given this manifest:

{
  "scripts": {
    "start": "./main.js --mode prod"
  }
}

Run it with:

/work > pkg run start

Extra arguments are appended after the script command line.

/work > pkg run start --verbose

The effective command line becomes:

./main.js --mode prod --verbose

Typical workflow

/work > pkg init demo-app
/work > pkg install github.com/acme/demo
/work > pkg install generic-pkg
/work > pkg run start

Notes

• pkg expects a valid package.json for install without an explicit package name and for run.
• pkg run executes the script line through JSH command resolution, not through a POSIX shell.
• Relative script commands such as ./tool.js are recommended for project-local executables.
• GitHub repository installs require the downloaded repository contents to include a valid package.json.