point add

Summary

point add declares dependencies in point.json and regenerates point.lock with pinned paths. Project-wide check, build, and related commands resolve use <package>.<module> imports through the lockfile — no manual path wiring in every file.

Manifest and lockfile

Every Point project has a point.json manifest:

{
  "name": "point",
  "version": "0.0.5",
  "dependencies": {
    "std": "workspace:std"
  }
}

point.lock pins resolved packages with schemaVersion: "point.lock.v1":

{
  "schemaVersion": "point.lock.v1",
  "packages": {
    "point": {
      "version": "0.0.5",
      "dependencies": {
        "std": "workspace:std"
      }
    },
    "std": {
      "version": "workspace",
      "path": "std"
    }
  }
}

The lockfile is JSON on purpose — agents and CI can inspect and update it safely. Do not hand-edit paths unless you know what you are doing; prefer point add to keep manifest and lock in sync.

The add command

point add <name> <spec>

The command updates point.json dependencies, resolves paths relative to the project root, and writes a fresh point.lock. On success it prints which files changed.

Invalid names, missing point.json, unknown spec prefixes, or paths that do not exist exit with code 1 and a clear error message.

Dependency specs

### workspace: — monorepo packages

Use when the dependency lives in the same repository or workspace layout:

point add std workspace:std

The locator is a directory path (relative to the project root) that contains a point.json or .point modules. After resolution, point.lock stores the normalized relative path and version: "workspace".

In this repository, the root project depends on the shared std library this way:

"dependencies": {
  "std": "workspace:std"
}

Then use std.text resolves to std/text.point via the lockfile entry for std.

### file: — local packages on disk

Use for sibling directories, vendored packages, or paths outside a workspace convention:

point add logic file:packages/point-logic

The locator is any existing directory relative to the project root. Resolution pins version: "file" and the normalized path in point.lock. If the directory has its own point.json, nested package metadata is recorded under the nested package name.

### npm: — registry packages

Install published Point packages from any npm-compatible registry (public npm, GitHub Packages, or a private mirror). The CLI runs `bun add --no-save` (falls back to npm install --no-save), locates point.json or src/*.point in the package, and pins the path under node_modules/ in point.lock:

point add logic npm:@hatchingpoint/point-logic
point add logic npm:@hatchingpoint/point-logic@0.0.2

Then use logic.store-readiness resolves through the lockfile.

Note: Packages that ship only emitted JavaScript in dist/ (no .point source in the tarball) cannot be typechecked via point add. Prefer packages that include Point source, or import emitted JS directly for runtime-only use.

#### Registry configuration

point add does not implement a separate Point registry protocol. It delegates to npm for download and path resolution. Configure the registry the same way you would for any scoped package:

GitHub Packages (consumer) — in the consuming project root, add .npmrc (commit for teams, or use CI secrets locally):

@your-org:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Then install as usual:

export GITHUB_TOKEN=ghp_...   # classic PAT with read:packages, or Actions GITHUB_TOKEN
point add logic npm:@your-org/point-logic
point check-all

Registry clients honor .npmrc, so point.lock pins the same node_modules/@your-org/point-logic path whether the tarball came from npmjs or GitHub.

GitHub Packages (publisher) — see npm packages — Publish workflow for package.json publishConfig and CI token setup.

Resolution at check and build

After dependencies are locked:

• use <package>.<module> without a from path resolves through point.lock (e.g. use std.http → std/http.point).
• Relative imports such as use Module from "./module.point" still work alongside lockfile packages.
• check-all, build-all, and related project commands load point.lock from the project root when building the module graph.

If a package name is missing from the lockfile, check/build report an error that includes the suggested point add command.

Publish → consume workflow

End-to-end flow for a Point library team:

Author .point  →  point check / point build  →  npm publish  →  point add npm:  →  use pkg.module

Reference implementation: @hatchingpoint/point-logic in packages/point-logic/ (monorepo) — same layout works in a standalone repository.

Hosted package index: There is no first-party Point registry service yet. Discovery is via npm search, GitHub repo README, or an internal catalog you maintain manually. Installation still uses point add … npm:… against whichever npm registry hosts the tarball.

Examples

Monorepo std library (this repository):

point add std workspace:std

Local logic package before publish:

point add logic file:packages/point-logic

Registry dependency (public npm):

point add logic npm:@hatchingpoint/point-logic

Registry dependency (GitHub Packages, after `.npmrc` is configured):

point add logic npm:@your-org/point-logic@1.0.0

Common mistakes

• Using npm: on packages that ship only dist/ JS — they won't resolve for point check; use packages with .point source or file: for local copies.
• Adding a dependency name that does not match how you use it — the lockfile alias must match the prefix in use std.text, use logic.store, etc.
• Expecting point add to install JavaScript npm deps for external blocks — those still belong in package.json; point add is for Point package modules only.
• Editing point.lock paths by hand after moving directories — re-run point add or regenerate the lock from the manifest.
• Publishing or consuming GitHub Packages without a scoped .npmrc — npm defaults to registry.npmjs.org and point add npm:@your-org/... will 404.
• Forgetting to include src/*.point and point.json in the published tarball — consumers cannot point check against your package.

See also

• CLI reference — add exit codes and project commands
• npm packages — @hatchingpoint/point, publishing, and external interop
• Authoring vs runtime — manifest vs emitted artifacts