zuke.tools.npm

class NpmAccessSettings(NpmSettings)

• list_packages(owner: str | None=None, pkg: str | None=None) -> Self

  List the packages a user, scope, or team can reach (access list packages).

• list_collaborators(pkg: str | None=None, user: str | None=None) -> Self

  List a package's collaborators (access list collaborators).

• get_status(pkg: str | None=None) -> Self

  Read whether a package is public or private (access get status), the default.

• set_status(level: Literal['public', 'private'], pkg: str | None=None) -> Self

  Set a package public or private (access set status=<level>).

• set_mfa(mode: Literal['none', 'publish', 'automation'], pkg: str | None=None) -> Self

  Require two-factor auth for publishing (access set mfa=<mode>).

• grant(permission: Literal['read-only', 'read-write'], team: str, pkg: str | None=None) -> Self

  Give a team access (access grant <permission> <scope:team>).

• revoke(team: str, pkg: str | None=None) -> Self

  Take a team's access away (access revoke <scope:team>).

• otp(code: str) -> Self

  Provide a one-time password. Carried in npm_config_otp rather than on the command line — see NpmSettings.applyOtp for why.

class NpmAuditSettings(NpmWorkspaceSettings)

• fix() -> Self

  Install compatible updates for what it finds (npm audit fix).

• signatures() -> Self

  Verify the registry signatures of what is installed (npm audit signatures).

• audit_level(level: Literal['info', 'low', 'moderate', 'high', 'critical', 'none']) -> Self

  The severity at which the command fails (--audit-level=<info|low|moderate|high|critical|none>).

• omit(*types: Literal['dev', 'optional', 'peer']) -> Self

  Skip a dependency group (--omit=<group>); repeatable.

• include(*types: Literal['prod', 'dev', 'optional', 'peer']) -> Self

  Keep a dependency group npm would otherwise omit (--include=<group>); repeatable.

• package_lock_only() -> Self

  Audit the lockfile without touching node_modules (--package-lock-only).

• dry_run() -> Self

  Report what a fix would change without changing it (--dry-run).

class NpmCacheSettings(NpmSettings)

• add(*specs: str) -> Self

  Add a package to the cache (cache add <spec>).

• clean(key: str | None=None) -> Self

  Empty the cache (cache clean). npm refuses this without --force, so pair it with force — see the error this reports otherwise.

• ls(*specs: str) -> Self

  List what the cache holds (cache ls).

• verify() -> Self

  Check and compact the cache (cache verify), the default.

• cache(path: str) -> Self

  Use a specific cache directory (--cache=<path>).

• force() -> Self

  Confirm a clean npm would otherwise refuse (--force).

class NpmCiSettings(NpmDependencySettings)

• no_audit() -> Self

  Skip the audit npm runs after installing (--no-audit).

• no_fund() -> Self

  Skip the funding message (--no-fund).

class NpmConfigSettings(NpmSettings)

• get(*keys: str) -> Self

  Read config keys (config get <key>...).

• set(*assignments: str) -> Self

  Write config keys (config set <key>=<value>...).

• delete_keys(*keys: str) -> Self

  Remove config keys (config delete <key>...).

• list() -> Self

  List the effective configuration (config list).

• fix() -> Self

  Repair invalid config entries (config fix).

• location(where: Literal['global', 'user', 'project']) -> Self

  Which file to read or write (--location=<global|user|project>).

• long() -> Self

  Include defaults in a listing (--long).

class NpmDedupeSettings(NpmDependencySettings)

• dry_run() -> Self

  Report what would move without changing the tree (--dry-run).

class NpmDependencySettings(NpmWorkspaceSettings)

• packages(*specs: str) -> Self

  Package specs the command operates on (positional); repeatable.

• omit(*types: Literal['dev', 'optional', 'peer']) -> Self

  Skip a dependency group (--omit=<group>); repeatable.

• include(*types: Literal['prod', 'dev', 'optional', 'peer']) -> Self

  Keep a dependency group npm would otherwise omit (--include=<group>); repeatable.

• ignore_scripts() -> Self

  Do not run lifecycle scripts (--ignore-scripts).

• foreground_scripts() -> Self

  Show lifecycle-script output as it runs (--foreground-scripts).

class NpmDeprecateSettings(NpmSettings)

• spec(value: str) -> Self

  The package spec to deprecate, e.g. app@<2 (required).

• message(text: str) -> Self

  The warning installers will see (required). An empty message is how npm *un*-deprecates a version, so it must be given deliberately rather than by omission.

• otp(code: str) -> Self

  Provide a one-time password. Carried in npm_config_otp rather than on the command line — see NpmSettings.applyOtp for why.

class NpmDistTagSettings(NpmWorkspaceSettings)

• add(spec: str, tag: str | None=None) -> Self

  Point a tag at a published version (dist-tag add <pkg@version> [<tag>]). The spec must carry the version; a tag cannot point at a range. With no tag npm uses latest, as it does on the command line.

• rm(spec: str, tag: str) -> Self

  Remove a tag (dist-tag rm <pkg> <tag>).

• ls(spec: str | None=None) -> Self

  List a package's tags (dist-tag ls [<pkg>]), the default.

class NpmExecSettings(NpmWorkspaceSettings)

• command(name: str) -> Self

  The command to execute (required).

• package(spec: str) -> Self

  The package providing the command (--package=).

• yes() -> Self

  Skip the install prompt (--yes).

• no() -> Self

  Refuse to install anything (--no), so the command runs only if it is already present — what a hermetic CI step wants instead of a silent fetch.

• exec_args(*args: str | float) -> Self

  Arguments forwarded to the command (after --).

class NpmInitSettings(NpmWorkspaceSettings)

• initializer(spec: str) -> Self

  The initializer package to run, e.g. vite for npm init vite (positional). With none, npm writes a package.json itself.

• yes() -> Self

  Accept the defaults instead of prompting (--yes).

• scope(name: str) -> Self

  Scope the created package (--scope=<@scope>).

• init_args(*args: str | float) -> Self

  Arguments forwarded to the initializer (after --).

class NpmInstallSettings(NpmDependencySettings)

• save_dev() -> Self

  Save to devDependencies (--save-dev).

• save_optional() -> Self

  Save to optionalDependencies (--save-optional).

• save_peer() -> Self

  Save to peerDependencies (--save-peer).

• save_exact() -> Self

  Pin exact versions (--save-exact).

• no_save() -> Self

  Install without recording the dependency (--no-save).

• install_strategy(strategy: Literal['hoisted', 'nested', 'shallow', 'linked']) -> Self

  How npm lays out the tree (--install-strategy=<strategy>).

• no_audit() -> Self

  Skip the audit npm runs after installing (--no-audit).

• no_fund() -> Self

  Skip the funding message (--no-fund).

class NpmLinkSettings(NpmDependencySettings)

• save_dev() -> Self

  Record the linked package in devDependencies (--save-dev).

class NpmLsSettings(NpmWorkspaceSettings)

• spec(value: str) -> Self

  Limit the listing to one package spec (positional).

• depth(levels: float) -> Self

  How deep to walk the tree (--depth=<n>); 0 lists direct dependencies.

• all() -> Self

  Show every dependency, not just the top level (--all).

• long() -> Self

  Include extended information (--long).

• parseable() -> Self

  Emit one line per package, tab-separated (--parseable).

• omit(*types: Literal['dev', 'optional', 'peer']) -> Self

  Skip a dependency group (--omit=<group>); repeatable.

class NpmOutdatedSettings(NpmWorkspaceSettings)

• packages(*specs: str) -> Self

  Limit the report to these package specs (positional); repeatable.

• all() -> Self

  Report transitive dependencies too (--all).

• long() -> Self

  Include the package type and homepage (--long).

class NpmOwnerSettings(NpmWorkspaceSettings)

• add(user: str, pkg: str) -> Self

  Add a maintainer (owner add <user> <pkg>).

• rm(user: str, pkg: str) -> Self

  Remove a maintainer (owner rm <user> <pkg>).

• ls(pkg: str) -> Self

  List a package's maintainers (owner ls <pkg>).

• otp(code: str) -> Self

  Provide a one-time password. Carried in npm_config_otp rather than on the command line — see NpmSettings.applyOtp for why.

class NpmPackSettings(NpmWorkspaceSettings)

• packages(*specs: str) -> Self

  Package specs to pack (positional); defaults to the current project.

• pack_destination(dir: str) -> Self

  Where to write the tarball (--pack-destination=<dir>).

• dry_run() -> Self

  Report what would be packed without writing a tarball (--dry-run).

class NpmPingSettings(NpmSettings)

class NpmPkgSettings(NpmWorkspaceSettings)

• get(*keys: str) -> Self

  Read one or more package.json fields (pkg get <key>...).

• set(*assignments: str) -> Self

  Write fields (pkg set <key>=<value>...). Each argument is npm's own key=value form, which is also how it addresses arrays and nested keys.

• delete_keys(*keys: str) -> Self

  Remove fields (pkg delete <key>...).

• fix() -> Self

  Repair what npm can correct automatically (pkg fix).

• force() -> Self

  Skip npm's confirmation for a destructive edit (--force).

class NpmPruneSettings(NpmDependencySettings)

• dry_run() -> Self

  Report what would be removed without removing it (--dry-run).

class NpmPublishSettings(NpmWorkspaceSettings)

• tag(name: str) -> Self

  Publish under a dist-tag (--tag=).

• access(level: Literal['public', 'restricted']) -> Self

  Set the package access level (--access=).

• dry_run() -> Self

  Report what would be published without uploading (--dry-run).

• otp(code: str) -> Self

  Provide a one-time password. Carried in npm_config_otp rather than on the command line — see NpmSettings.applyOtp for why.

• provenance() -> Self

  Publish with a provenance attestation (--provenance), which npm can generate from a trusted CI run — the supply-chain signal a consumer can verify against the workflow that built the tarball.

class NpmRebuildSettings(NpmDependencySettings)

• no_bin_links() -> Self

  Do not create the .bin symlinks (--no-bin-links).

class NpmRunSettings(NpmWorkspaceSettings)

• script(name: str) -> Self

  The package.json script to run (required).

• if_present() -> Self

  Do not fail when the script is missing (--if-present).

• script_args(*args: str | float) -> Self

  Arguments forwarded to the script (after --).

class NpmSbomSettings(NpmWorkspaceSettings)

• sbom_format(format: Literal['cyclonedx', 'spdx']) -> Self

  Which document to emit (--sbom-format=<cyclonedx|spdx>), required by npm.

• sbom_type(type_: Literal['library', 'application', 'framework']) -> Self

  What the project is (--sbom-type=<library|application|framework>).

• omit(*types: Literal['dev', 'optional', 'peer']) -> Self

  Skip a dependency group (--omit=<group>); repeatable.

• package_lock_only() -> Self

  Build the document from the lockfile alone (--package-lock-only).

class NpmSettings(ToolSettings)

• registry(url: str) -> Self

  Use a specific registry (--registry=<url>).

• json() -> Self

  Emit JSON (--json). The value-returning tasks set this themselves; a caller reaches for it to parse output the wrapper does not yet model.

• log_level(level: Literal['silent', 'error', 'warn', 'notice', 'http', 'info', 'verbose', 'silly']) -> Self

  How much npm prints (--loglevel=<level>).

• global_() -> Self

  Operate on the global install rather than the project (--global).

• prefix(path: str) -> Self

  Run as if npm were started in this directory (--prefix=<path>).

• userconfig(path: str) -> Self

  Read this user config file rather than ~/.npmrc (--userconfig=<path>).

class NpmTasks

• static async install(ctx: ServiceContext, configure: Callable[[NpmInstallSettings], NpmInstallSettings] | None=None) -> ExecResult

  Install dependencies: npm install.

• static async ci(ctx: ServiceContext, configure: Callable[[NpmCiSettings], NpmCiSettings] | None=None) -> ExecResult

  Clean install from the lockfile: npm ci.

• static async uninstall(ctx: ServiceContext, configure: Callable[[NpmUninstallSettings], NpmUninstallSettings] | None=None) -> ExecResult

  Remove dependencies: npm uninstall.

• static async update(ctx: ServiceContext, configure: Callable[[NpmUpdateSettings], NpmUpdateSettings] | None=None) -> ExecResult

  Update dependencies within their ranges: npm update.

• static async dedupe(ctx: ServiceContext, configure: Callable[[NpmDedupeSettings], NpmDedupeSettings] | None=None) -> ExecResult

  Flatten duplicated packages: npm dedupe.

• static async prune(ctx: ServiceContext, configure: Callable[[NpmPruneSettings], NpmPruneSettings] | None=None) -> ExecResult

  Remove packages nothing depends on: npm prune.

• static async rebuild(ctx: ServiceContext, configure: Callable[[NpmRebuildSettings], NpmRebuildSettings] | None=None) -> ExecResult

  Rebuild native packages: npm rebuild.

• static async link(ctx: ServiceContext, configure: Callable[[NpmLinkSettings], NpmLinkSettings] | None=None) -> ExecResult

  Symlink a package for local development: npm link.

• static async run(ctx: ServiceContext, configure: Callable[[NpmRunSettings], NpmRunSettings] | None=None) -> ExecResult

  Run a package.json script: npm run.

• static async test(ctx: ServiceContext, configure: Callable[[NpmTestSettings], NpmTestSettings] | None=None) -> ExecResult

  Run the project's test script: npm test.

• static async exec(ctx: ServiceContext, configure: Callable[[NpmExecSettings], NpmExecSettings] | None=None) -> ExecResult

  Execute a package binary: npm exec.

• static async publish(ctx: ServiceContext, configure: Callable[[NpmPublishSettings], NpmPublishSettings] | None=None) -> ExecResult

  Publish the package: npm publish.

• static async pack(ctx: ServiceContext, configure: Callable[[NpmPackSettings], NpmPackSettings] | None=None) -> ExecResult

  Build a tarball without publishing it: npm pack.

• static async version(ctx: ServiceContext, configure: Callable[[NpmVersionSettings], NpmVersionSettings] | None=None) -> ExecResult

  Bump the package version: npm version.

• static async unpublish(ctx: ServiceContext, configure: Callable[[NpmUnpublishSettings], NpmUnpublishSettings] | None=None) -> ExecResult

  Remove a published version: npm unpublish.

• static async deprecate(ctx: ServiceContext, configure: Callable[[NpmDeprecateSettings], NpmDeprecateSettings] | None=None) -> ExecResult

  Warn installers off a version: npm deprecate.

• static async dist_tag(ctx: ServiceContext, configure: Callable[[NpmDistTagSettings], NpmDistTagSettings] | None=None) -> ExecResult

  Manage dist-tags: npm dist-tag add|rm|ls.

• static async view(ctx: ServiceContext, configure: Callable[[NpmViewSettings], NpmViewSettings] | None=None) -> ExecResult

  Read registry metadata: npm view.

• static async ping(ctx: ServiceContext, configure: Callable[[NpmPingSettings], NpmPingSettings] | None=None) -> ExecResult

  Check the registry is reachable: npm ping.

• static async whoami(ctx: ServiceContext, configure: Callable[[NpmWhoamiSettings], NpmWhoamiSettings] | None=None) -> ExecResult

  Print the authenticated user: npm whoami.

• static async whoami_name(ctx: ServiceContext, configure: Callable[[NpmWhoamiSettings], NpmWhoamiSettings] | None=None) -> object

  The authenticated user's name, or undefined when this machine is not logged in — an answer a release target can act on, rather than the non-zero exit npm reports.

• static async access(ctx: ServiceContext, configure: Callable[[NpmAccessSettings], NpmAccessSettings] | None=None) -> ExecResult

  Manage package access: npm access.

• static async owner(ctx: ServiceContext, configure: Callable[[NpmOwnerSettings], NpmOwnerSettings] | None=None) -> ExecResult

  Manage package maintainers: npm owner add|rm|ls.

• static async token(ctx: ServiceContext, configure: Callable[[NpmTokenSettings], NpmTokenSettings] | None=None) -> ExecResult

  Manage registry tokens: npm token list|create|revoke.

• static async ls(ctx: ServiceContext, configure: Callable[[NpmLsSettings], NpmLsSettings] | None=None) -> ExecResult

  List the installed tree: npm ls.

• static async outdated(ctx: ServiceContext, configure: Callable[[NpmOutdatedSettings], NpmOutdatedSettings] | None=None) -> ExecResult

  Report dependencies behind their latest: npm outdated.

• static async outdated_entries(ctx: ServiceContext, configure: Callable[[NpmOutdatedSettings], NpmOutdatedSettings] | None=None) -> object

  The outdated dependencies as parsed NpmOutdatedEntry values. npm exits non-zero *because* something is outdated, so this reads that as the answer rather than as a failure; an empty array means everything is current.

• static async audit(ctx: ServiceContext, configure: Callable[[NpmAuditSettings], NpmAuditSettings] | None=None) -> ExecResult

  Audit dependencies for vulnerabilities: npm audit.

• static async audit_summary(ctx: ServiceContext, configure: Callable[[NpmAuditSettings], NpmAuditSettings] | None=None) -> object

  The audit's vulnerability counts by severity, so a target decides for itself what is worth failing on. npm's non-zero exit is the finding, not an error.

• static async sbom(ctx: ServiceContext, configure: Callable[[NpmSbomSettings], NpmSbomSettings] | None=None) -> ExecResult

  Emit a software bill of materials: npm sbom.

• static async init(ctx: ServiceContext, configure: Callable[[NpmInitSettings], NpmInitSettings] | None=None) -> ExecResult

  Create a package or run an initializer: npm init.

• static async pkg(ctx: ServiceContext, configure: Callable[[NpmPkgSettings], NpmPkgSettings] | None=None) -> ExecResult

  Read or write package.json fields: npm pkg get|set|delete|fix.

• static async pkg_get(ctx: ServiceContext, key: str, configure: Callable[[NpmPkgSettings], NpmPkgSettings] | None=None) -> object

  One package.json field as a string, or undefined when it is unset or is not a scalar — how a build reads its own version without parsing the manifest or guessing where it lives.

• static async config(ctx: ServiceContext, configure: Callable[[NpmConfigSettings], NpmConfigSettings] | None=None) -> ExecResult

  Read or write npm configuration: npm config get|set|delete|list|fix.

• static async cache(ctx: ServiceContext, configure: Callable[[NpmCacheSettings], NpmCacheSettings] | None=None) -> ExecResult

  Maintain the package cache: npm cache add|clean|ls|verify.

class NpmTestSettings(NpmWorkspaceSettings)

• test_args(*args: str | float) -> Self

  Arguments forwarded to the test script (after --).

class NpmTokenSettings(NpmSettings)

• list() -> Self

  List this account's tokens (token list), the default.

• create() -> Self

  Create a token (token create).

• revoke(id_or_token: str) -> Self

  Revoke a token by id or value (token revoke <id|token>). npm takes this positionally, with no environment route, so the value reaches the child's argv either way. It is registered with the run's redactor so every *rendering* of the command masks it; the process table is not something the wrapper can do anything about here. Masked whichever it is, because the two are indistinguishable from here — npm accepts the id or the token itself, and nothing in the string says which. Masking an id costs a [redacted] in this run's output; not masking a token puts a live credential in it.

• read_only() -> Self

  Create a token that cannot publish (--read-only).

• cidr(*ranges: str) -> Self

  Restrict a created token to these ranges (--cidr=<range>); repeatable.

• otp(code: str) -> Self

  Provide a one-time password. Carried in npm_config_otp rather than on the command line — see NpmSettings.applyOtp for why.

class NpmUninstallSettings(NpmDependencySettings)

• no_save() -> Self

  Remove the package without updating package.json (--no-save).

class NpmUnpublishSettings(NpmWorkspaceSettings)

• spec(value: str) -> Self

  The package spec to remove, e.g. app@1.2.3 (positional).

• force() -> Self

  Confirm an unpublish npm would otherwise refuse (--force) — removing a whole package, or a version outside the 72-hour window.

• dry_run() -> Self

  Report what would be removed without removing it (--dry-run).

class NpmUpdateSettings(NpmDependencySettings)

• save() -> Self

  Write the updated ranges back to package.json (--save).

class NpmVersionSettings(NpmWorkspaceSettings)

• bump(value: str) -> Self

  The bump: patch | minor | major or an explicit semver (required).

• message(text: str) -> Self

  Commit message; %s expands to the new version (--message).

• no_git_tag_version() -> Self

  Do not create a git commit and tag (--no-git-tag-version).

• preid(id: str) -> Self

  The prerelease identifier for a pre* bump (--preid=<id>), e.g. rc.

• allow_same_version() -> Self

  Accept a bump to the version already set (--allow-same-version).

class NpmViewSettings(NpmWorkspaceSettings)

• spec(value: str) -> Self

  The package spec to read, e.g. react@18 (positional).

• field(*names: str) -> Self

  A field of the registry metadata to print, e.g. version or dist-tags.latest (positional); repeatable. With none, npm prints the whole record.

class NpmWhoamiSettings(NpmSettings)

class NpmWorkspaceSettings(NpmSettings)

• workspace(*names: str) -> Self

  Run in this workspace (--workspace=<name>); repeatable.

• workspaces() -> Self

  Run in every workspace (--workspaces). Mutually exclusive with workspace — setting both is a build error.

• include_workspace_root() -> Self

  Include the root project alongside the workspaces (--include-workspace-root).