semantu-cli

@semantu/cli — command line tools for Semantu. Run semantu help (or smtu help) for the command list.

npx @semantu/cli help

Developer setup: the npm token

Most @semantu/* packages are private on npm (@semantu/create-now and @semantu/execution-gateway both 404 for an anonymous client). Without a token, npm install or yarn install in any repo that depends on one fails with 401 Unauthorized — that is the symptom you will actually hit, and it does not mention authentication in an obvious way.

Get the shared read-only token from the architect, then:

npm config set //registry.npmjs.org/:_authToken=<token>
npm whoami   # should print your npm username — that verifies it

npm config set writes to ~/.npmrc (your home directory). That is the only place the token belongs.

Never put the token in a repo — not in .npmrc, not in .env, not in .env.json, not in a workflow file you commit. This is not a hypothetical: a token was committed to this repo in .env.json and, because .npmignore did not list it, shipped in plaintext inside every published 1.2.x tarball. It has since been rotated and .env.json is now in both .gitignore and .npmignore — keep it that way.

@semantu/cli itself is published public, so installing this package needs no token. You still need one to publish it, and to install the private packages above.

@semantu/multicore is optional (2.0.2)

semantu start can run a cluster primary with N worker processes when an app sets server.multiCore in linked.config.js. @semantu/multicore supplies those two server shapes, and it is declared here as an optional peer dependency, so a normal install does not get it.

That declaration is the whole point of 2.0.2: multicore pulls in lincd-server and with it the legacy lincd tree. Measured on npm 11.19.1, installing this package into an empty app:

| | lockfile entries matching lincd | foaf | packages | node_modules | |---|---|---|---|---| | @semantu/[email protected] (hard dependency) | 30 | 9 | 1629 | 576 MB | | @semantu/[email protected] (optional peer) | 0 | 0 | 864 | 202 MB |

optionalDependencies does not achieve this — the tree is still resolved and written to the lockfile, merely flagged "optional": true. A plain peerDependencies entry is worse still: npm tries to install it and the whole install dies on lincd-cli's husky postinstall (code 127: husky: command not found). Only peerDependenciesMeta.optional keeps it out. See docs/backlog/070-multicore.md in create_now for the full measurement.

This shipped as a patch (2.0.2), not a major. Strictly it is a breaking change for anyone who relied on @semantu/multicore arriving transitively: after 2.0.2 it does not, and an app with server.multiCore set will refuse to start until it is installed explicitly. That is a deliberate call by the maintainer — nothing in the fleet sets server.multiCore, and the package was inert everywhere it was being installed — so the fix is shipped where consumers will actually pick it up rather than behind a major they would have to opt into. If you need multicore, install it.

To use multicore, install it in the app alongside this package:

npm install @semantu/multicore

It hoists to the app's root node_modules, where @semantu/cli's dynamic import() finds it — verified end to end: the primary forks its workers as before. If server.multiCore is set and the package is absent, semantu start prints an install instruction and exits 1. It does not fall back to the single-process server: silently running a different topology than the config asks for is worse than stopping. (Before 2.0.2 the advertised fallback did not exist either — the catch left LincdServer undefined and then called new LincdServer().)

Releasing

This package is released manually. It is the exception in the fleet: every @_linked/* package publishes from CI via changesets, with the version bump and CHANGELOG.md generated automatically. Here there is no CI, no changesets and no CHANGELOG — the version in package.json is bumped by hand and the publish is run from a developer machine.

yarn build
yarn test
npm publish --ignore-scripts

--ignore-scripts is required: prepack runs yarn version patch, which would bump the version you just set, mid-pack. Because it also skips the prepack build, run yarn build yourself first.

Before publishing, check the tarball:

npm pack --ignore-scripts && tar tzf semantu-cli-*.tgz | grep -i env   # must print nothing

CI is deferred rather than ruled out — see the note at the end of this file.

Setting up a LINCD app

npx @semantu/cli setup-workspace

Why there is no CI here

The @_linked/* fleet shares two reusable workflows in linked-fw/.github (pr.yml and publish.yml, pinned at the hand-moved @v1 tag), which each package calls from a thin stub. That repo is public, so a repo in the Semantu org can call it — the cross-org restriction applies to private/internal source repos only.

What is missing is the credentials: the reusable publish.yml requires NPM_TOKEN, RELEASE_APP_ID and RELEASE_APP_PRIVATE_KEY. Those are org secrets in linked-fw with visibility: all, which does not extend to the Semantu org. Semantu has NPM_AUTH_TOKEN; it has no release GitHub App. Adopting the shared CI would also mean introducing changesets here, which this package does not use. Manual publishing for now.