tapid install

Syntax

tapid install [PACKAGE] [OPTIONS]

The install command can add one package or install the dependencies already declared in package.json. By default, it resolves the supported npm-compatible subset, requires registry-declared integrity, writes tapid.lock, stores verified package trees, and activates managed node_modules.

$ tapid install is-char
$ tapid i is-char
$ tapid install

Package arguments support unscoped names, scoped names, exact versions, and the npm: and jsr: prefixes where the underlying registry metadata satisfies tapid's current trust and compatibility requirements.

What an online install changes

Without --offline or --frozen, tapid:

1. reads and validates the root package.json;
2. adds the requested package to dependencies when a package argument is present;
3. resolves the supported dependency graph from registry metadata;
4. downloads and verifies package archives using registry-declared SHA-512 integrity;
5. writes a canonical tapid.lock and stores verified package trees; and
6. activates managed node_modules only after the inputs validate.

The command prints Installed N package(s) on success. Dependency lifecycle scripts do not run. If installation fails after a package argument updates package.json, tapid restores the original manifest and rolls back the lockfile replacement instead of treating a partial install as successful.

When a package argument is present, it cannot be combined with --offline or --frozen. Those modes replay an existing project and do not resolve a new package.

Project replay

Use offline or frozen mode to replay an existing project lockfile without network resolution:

$ tapid install --offline --frozen --project-dir ./example

The project must provide a valid package.json, a compatible tapid.lock, and the verified store inputs required by the lockfile. tapid validates these inputs before activating managed node_modules.

The repository fixture verifies deterministic replay, managed files, executable metadata, root-script behavior, argument forwarding, exit-code propagation, and dependency lifecycle suppression.

Install modes

• The default online mode resolves metadata and retrieves artifacts. It requires registry-declared artifact integrity unless the explicit compatibility exception is enabled.
• --offline reads the existing lockfile and verified store without network resolution. It requires the lockfile, a matching root manifest digest, and all verified package trees.
• --frozen follows the current replay path without network resolution and rejects changed manifest or unverified lockfile inputs. It is not a claim of full npm frozen-lockfile compatibility.

Options

--offline
--frozen
--project-dir PATH
--store-dir PATH
--registry-fixture PATH
--allow-unverified-registry-artifacts

--registry-fixture is for tests and air-gapped development. It is not a production registry mirror or authentication feature.

--allow-unverified-registry-artifacts is an explicit compatibility escape hatch. It emits a warning, records locally computed integrity provenance, cannot be combined with --offline or --frozen, and produces a lockfile that frozen replay rejects.

--project-dir selects the project directory and defaults to the current directory. --store-dir selects the verified package store instead of the platform default. --registry-fixture supplies a local JSON registry fixture for tests and air-gapped development; it is not a registry mirror or authentication mechanism.

Common failures

• A missing or invalid package.json stops the install before dependency work begins.
• Missing registry-declared integrity fails the default online path unless the compatibility exception is explicit.
• An offline or frozen install fails when tapid.lock, the matching manifest digest, or verified store content is missing.
• A changed manifest is rejected during replay rather than silently updating the lockfile.
• Unsupported package specifications, registry metadata, or dependency graph shapes fail closed instead of being guessed.

Current limits

tapid does not yet implement full npm compatibility. Tags, aliases, peers, workspaces, private registry authentication, several semver forms, and parts of optional dependency handling remain incomplete. JSR installation remains fail-closed unless metadata provides an HTTPS npm artifact and valid SHA-512 integrity. A successful install also does not imply that dependency code is safe. tapid verifies identity and integrity but does not sandbox imported code.