@trajectonomics/cli 0.0.0-stage → 0.0.1-bootstrap.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 trajectonomics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# trajectonomics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The trajectonomics command line. The sources are Bun-only; a released binary needs nothing.
+
+## Install
+
+Linux and macOS, one line (verifies the release checksum, installs `traj` to `~/.local/bin`,
+or `$TRAJ_INSTALL_DIR`, and prints what it installed):
+
+```bash
+curl -fsSL https://github.com/trajectonomics/cli/releases/latest/download/install.sh | sh
+```
+
+Windows, one line (installs to `%LOCALAPPDATA%\traj\bin`, adds it to the user `PATH` once,
+and needs a new shell afterwards):
+
+```powershell
+irm https://github.com/trajectonomics/cli/releases/latest/download/install.ps1 | iex
+```
+
+npm, on any machine with Node 20 or later, or with Bun (`npx` needs no Bun; the package
+fetches the release binary on first run and caches it under `~/.traj/bin`):
+
+```bash
+npx @trajectonomics/cli@latest --version
+bunx @trajectonomics/cli@latest --version
+```
+
+Which channel: all three end at the same compiled binary and the same version. Use the
+script for a machine that should keep `traj` on `PATH`, npm when you already have Node or
+Bun and want one command. Pin a release with `TRAJ_VERSION=X.Y.Z` for the script, or
+`@X.Y.Z` for npm.
+
+Uninstall by deleting the one file: `~/.local/bin/traj`, `%LOCALAPPDATA%\traj\bin`,
+`~/.traj/bin` (the download cache), or nothing at all for `npx`.
+
+## Development
+
+```bash
+bun install
+bun run dev -- --help     # run from source
+bun test
+bun run build             # single-file binary at dist/traj
+bun run lint              # Biome, zero warnings
+bun run format            # Biome format + import order, writes files
+bun run check             # lint + typecheck + test + build, what CI runs
+```
+
+From a checkout, run the CLI with `bun run dev -- …`. The npm launcher refuses the
+`0.0.0` a checkout carries, because that version is never a release; set
+`TRAJ_BINARY_PATH` to run a binary you built with `bun run build`.
+
+## Docs
+
+- [`GLOSSARY.md`](GLOSSARY.md): the project's vocabulary.
+- [`docs/adr/`](docs/adr/): design decisions and why.
+- [`docs/runbooks/releasing.md`](docs/runbooks/releasing.md): cutting and repairing a release.
+- [`ROADMAP.md`](ROADMAP.md): phases and recorded next steps.
+
+## Adding a command
+
+Create `src/commands/<name>.ts` (or `src/commands/<group>/<name>.ts` for a
+nested one) with `defineCommand`: a summary, an input schema, an output schema,
+examples, the error codes it raises, and a `run` that returns `ok(data)` or
+`fail(code)`. Register it in `src/commands/index.ts`, inside a `defineGroup` if
+it is nested. Fields of the input schema that are not positionals become flags
+automatically (`fromDate` is `--from-date`). A new failure is a new entry in the
+registry in `src/errors.ts` with its exit class. Commands never format output or
+exit; `traj help <path>` and `traj schema <path>` are generated from the same
+schemas that validate them. Test through `run(argv, io, env)`, which needs no
+process. See ADR 0015.

package/bin/launcher.d.ts

@@ -0,0 +1,9 @@
+/** The launcher's pure module, which runs on Node as plain JavaScript. */
+export declare const RELEASE_BASE: string
+export declare const SUPPORTED: string[]
+export declare function assetName(platform: string, arch: string): string
+export declare function checksumFor(checksums: string, name: string): string
+export declare function sha256(bytes: Uint8Array): string
+export declare function verifyChecksum(checksums: string, name: string, bytes: Uint8Array): string
+export declare function exitStatus(code: number | null, signal: string | null): number
+export declare function releaseUrl(version: string, name: string, base?: string): string

package/bin/launcher.js

@@ -0,0 +1,64 @@
+/** Platform to release asset, checksums and release URLs. Plain JavaScript and `node:` only. */
+import { createHash } from "node:crypto"
+import { constants } from "node:os"
+
+/** The repo's releases root: one release's assets sit under `download/v<version>`. */
+export const RELEASE_BASE = "https://github.com/trajectonomics/cli/releases"
+
+/** `process.platform`-`process.arch` to asset name. */
+const ASSETS = {
+	"darwin-arm64": "traj-darwin-arm64",
+	"darwin-x64": "traj-darwin-x64",
+	"linux-x64": "traj-linux-x64",
+	"linux-arm64": "traj-linux-arm64",
+	"win32-x64": "traj-windows-x64.exe",
+}
+
+/** The `platform/arch` pairs a release has a binary for, in message order. */
+export const SUPPORTED = Object.keys(ASSETS).map((key) => key.replace("-", "/"))
+
+/** The one asset a release has for this platform and architecture. */
+export function assetName(platform, arch) {
+	const asset = ASSETS[`${platform}-${arch}`]
+	if (asset === undefined) {
+		throw new Error(
+			`traj has no build for ${platform}/${arch}. Supported: ${SUPPORTED.join(", ")}.`,
+		)
+	}
+	return asset
+}
+
+/** `"<sha256>  <name>"` per line, as the release job writes it. */
+export function checksumFor(checksums, name) {
+	for (const line of checksums.split("\n")) {
+		const [digest, listed] = line.trim().split(/\s+/)
+		if (listed === name || listed === `*${name}`) return String(digest).toLowerCase()
+	}
+	throw new Error(`checksums.txt has no entry for ${name}.`)
+}
+
+export function sha256(bytes) {
+	return createHash("sha256").update(bytes).digest("hex")
+}
+
+/** The listed digest, after proving it is the digest of these bytes. */
+export function verifyChecksum(checksums, name, bytes) {
+	const listed = checksumFor(checksums, name)
+	const actual = sha256(bytes)
+	if (actual !== listed) {
+		throw new Error(`checksum mismatch for ${name}: expected ${listed}, got ${actual}`)
+	}
+	return actual
+}
+
+/**
+ * What a shell reports for a signalled child: `128 + signal`. A normal exit passes
+ * its own code through.
+ */
+export function exitStatus(code, signal) {
+	return signal === null ? (code ?? 1) : 128 + (constants.signals[signal] ?? 0)
+}
+
+export function releaseUrl(version, name, base = RELEASE_BASE) {
+	return `${base}/download/v${version}/${name}`
+}

package/bin/traj.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/** The npm package's command: install the release binary for this package's version, then run it. */
+import { spawn } from "node:child_process"
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { setTimeout as sleep } from "node:timers/promises"
+import { assetName, exitStatus, releaseUrl, verifyChecksum } from "./launcher.js"
+
+const RETRY_MS = 5 * 60 * 1000
+const MAX_WAIT_MS = 30 * 1000
+const FORWARDED = ["SIGHUP", "SIGINT", "SIGTERM"]
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))
+
+/** A launcher failure is one plain line on stderr and exit 1, never a JSON envelope. */
+function fail(message) {
+	process.stderr.write(`traj: ${message}\n`)
+	process.exitCode = 1
+}
+
+function run(binary, args) {
+	const child = spawn(binary, args, { stdio: "inherit" })
+	child.on("error", (error) => fail(`cannot run ${binary}: ${error.message}`))
+	for (const signal of FORWARDED) process.on(signal, () => child.kill(signal))
+	child.on("exit", (code, signal) => {
+		process.exitCode = exitStatus(code, signal)
+	})
+}
+
+/** One asset's bytes; only a 404 retries, because npm publishes minutes before the assets land. */
+async function download(url) {
+	const deadline = Date.now() + RETRY_MS
+	let said = false
+	for (let wait = 1000; ; wait = Math.min(wait * 2, MAX_WAIT_MS)) {
+		const res = await fetch(url)
+		if (res.ok) return new Uint8Array(await res.arrayBuffer())
+		if (res.status !== 404) throw new Error(`${url} answered ${res.status}`)
+		if (Date.now() + wait > deadline) {
+			throw new Error(`${url} is not there yet; the release may still be building. Retry shortly.`)
+		}
+		if (!said) {
+			said = true
+			process.stderr.write(`traj: ${url} is not there yet; retrying for up to five minutes.\n`)
+		}
+		await sleep(wait)
+	}
+}
+
+/** A complete file at the cache path, never a half-written one: same directory, then a rename. */
+function install(bytes, dest) {
+	mkdirSync(dirname(dest), { recursive: true })
+	const temp = join(dirname(dest), `.traj-${process.pid}-${Date.now()}`)
+	try {
+		writeFileSync(temp, bytes, { mode: 0o755 })
+		chmodSync(temp, 0o755)
+		try {
+			renameSync(temp, dest)
+		} catch (error) {
+			// A concurrent run won the race; its file is complete, so use it and drop ours.
+			if (!existsSync(dest)) throw error
+		}
+	} finally {
+		rmSync(temp, { force: true })
+	}
+}
+
+async function main(args) {
+	const chosen = process.env["TRAJ_BINARY_PATH"]
+	if (chosen !== undefined) return run(chosen, args)
+	if (version === "" || version === "0.0.0") {
+		return fail("this is a checkout, not a release: run `bun run dev --` or set TRAJ_BINARY_PATH.")
+	}
+	const name = assetName(process.platform, process.arch)
+	const home = process.env["TRAJ_HOME"] || join(homedir(), ".traj")
+	const exe = process.platform === "win32" ? ".exe" : ""
+	const dest = join(home, "bin", `traj-${version}${exe}`)
+	if (!existsSync(dest)) {
+		const base = process.env["TRAJ_DOWNLOAD_BASE_URL"] || undefined
+		process.stderr.write(`traj: downloading ${name} v${version} to ${dest} (about 100 MB).\n`)
+		const checksums = new TextDecoder().decode(
+			await download(releaseUrl(version, "checksums.txt", base)),
+		)
+		const bytes = await download(releaseUrl(version, name, base))
+		verifyChecksum(checksums, name, bytes)
+		install(bytes, dest)
+	}
+	run(dest, args)
+}
+
+await main(process.argv.slice(2)).catch((error) => {
+	fail(error instanceof Error ? error.message : String(error))
+})

package/package.json

@@ -1,6 +1,47 @@
 {
-  "name": "@trajectonomics/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@trajectonomics/cli",
+	"version": "0.0.1-bootstrap.0",
+	"description": "trajectonomics command line",
+	"license": "MIT",
+	"type": "module",
+	"packageManager": "bun@1.4.4",
+	"bin": {
+		"traj": "./bin/traj.js"
+	},
+	"files": [
+		"bin/"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/trajectonomics/cli.git"
+	},
+	"homepage": "https://github.com/trajectonomics/cli#readme",
+	"bugs": {
+		"url": "https://github.com/trajectonomics/cli/issues"
+	},
+	"scripts": {
+		"dev": "bun run src/index.ts",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome ci --error-on-warnings .",
+		"format": "biome check --write .",
+		"build": "bun build src/index.ts --compile --outfile dist/traj",
+		"check": "bun run lint && bun run typecheck && bun test && bun run build",
+		"update:skills": "bunx skills@latest update -p -y"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.6.3",
+		"@trajectonomics/ledger": "0.1.0-alpha.0",
+		"@trajectonomics/sim": "0.1.0",
+		"@trajectonomics/tooling": "1.1.0",
+		"@types/bun": "^1.4.4",
+		"typescript": "^7.0.2",
+		"zod": "^4.6.7"
+	}
+}