@tapestry-mud/cli 0.9.0 → 0.10.0

package/specs/pack-lifecycle.md

@@ -0,0 +1,206 @@
+---
+capability: pack-lifecycle
+last-updated: 2026-06-13
+---
+
+# pack-lifecycle
+
+Capability spec for project scaffolding, pack installation and removal, boot-order management,
+local development linking, tarball building, and publishing to the registry.
+
+## Overview
+
+pack-lifecycle covers the full lifecycle a user exercises to create a game project and manage
+its installed packs: scaffolding a new project (`tapestry init`), installing and removing
+packs from the registry, updating to newer compatible versions, toggling packs in or out of
+the engine boot order, attaching a local working copy for development (`link`), building a
+pack tarball for inspection, and publishing or unpublishing a pack on the registry.
+
+Supporting commands `create pack`, `list`, and `outdated` are also in this boundary.
+
+The project manifest is `tapestry.yaml`; the lock file is `tapestry-lock.yaml`; the boot
+order file is `tapestry-boot.yaml`; links are tracked in `tapestry-links.yaml`.
+
+## Behavior
+
+### init
+
+- Aborts if `tapestry.yaml` already exists in the target directory.
+  (src/commands/init.js:127-129)
+- Fetches the preset list from the registry (`/v1/presets`). If the list endpoint returns 404,
+  falls back to fetching the `starter` preset directly. If exactly one preset is available it
+  is selected automatically; if multiple exist, the user is prompted to choose.
+  (src/commands/init.js:133-151)
+- With `--yes`, skips all interactive prompts and uses directory name as game name, handle
+  `admin`, email `admin@localhost`, password `changeme`, telemetry off; prints a warning about
+  default credentials. (src/commands/init.js:166-175)
+- Writes `tapestry.yaml` with the preset's engine version and channel, and dependency ranges
+  pinned with a `^` prefix from the preset's pack versions. (src/commands/init.js:157-161)
+  (src/commands/init.js:226-227)
+- Writes `server.yaml` with server name, telnet port 4000, websocket port 4001, admin handle
+  and email, and telemetry block (commented out unless telemetry was selected).
+  (src/commands/init.js:228-229)
+- Creates a `packs/` directory and a `.gitignore` excluding `packs/`, `.tapestry-engine/`,
+  `tapestry-links.yaml`, and `data/`. (src/commands/init.js:238-241)
+- Warns if no `.git` directory is found. (src/commands/init.js:263-266)
+- `buildManifest` and `buildServerYaml` are exported for test injection.
+  (src/commands/init.js:269)
+
+### install
+
+- Requires `tapestry.yaml`; throws if absent. (src/commands/install.js:83-86)
+- With no argument, skips all linked packs, then checks whether the lock file is current
+  (deps_hash matches a SHA-256 of the sorted `name@range` dependency entries). If current,
+  installs from the lock; otherwise resolves freshly via the registry.
+  (src/commands/install.js:107-122) (src/lib/lock-file.js:10-13)
+- With a package argument, adds or updates the entry in `tapestry.yaml` dependencies, then
+  resolves and installs. A bare `@scope/name` (no range) is resolved and the entry is pinned
+  at `^<resolvedVersion>`; an explicit `@scope/name@range` writes the supplied range as-is and
+  is not re-pinned to the resolved version. (src/commands/install.js:92-105)
+  (src/commands/install.js:101-103)
+- Skips a package entirely if it is already linked (local working copy takes precedence).
+  (src/commands/install.js:37-41)
+- Skips a package if the installed version already matches the resolved version.
+  (src/commands/install.js:50-54)
+- Downloads each tarball to a temp file, verifies its `sha256-` integrity hash, extracts into
+  `packs/<scope>/<name>/`, then removes the temp file. (src/commands/install.js:64-75)
+- After installing, calls `addPackageToBoot` to register the pack (and any module entry)
+  in `tapestry-boot.yaml`. (src/commands/install.js:77-78)
+- Writes the lock file with `lockfile_version: 1`, `deps_hash`, and the full resolved map.
+  (src/commands/install.js:128)
+
+### uninstall
+
+- Requires `tapestry.yaml` and that the package appears in `dependencies`; throws otherwise.
+  (src/commands/uninstall.js:14-22)
+- Deletes `packs/<scope>/<name>/` if present. (src/commands/uninstall.js:24-28)
+- Removes the entry from `tapestry.yaml` and from `lock.resolved`, then writes both files.
+  (src/commands/uninstall.js:29-39)
+- Removes the pack (and its module entry) from `tapestry-boot.yaml`.
+  (src/commands/uninstall.js:40)
+- Transitive dependencies are NOT automatically removed; a note to run `tapestry install` is
+  printed. (src/commands/uninstall.js:43)
+
+### update
+
+- Resolves fresh versions for all dependencies (or one if a package name is given), bypassing
+  the lock file. Merges with the existing lock so packages not being updated keep their pinned
+  entries. (src/commands/update.js:36-43)
+- Does NOT pass an auth token to the resolver (update.js:39 calls `resolve(deps, url)` with
+  no token, unlike install which passes `loadAccess()`). UNVERIFIED: whether this prevents
+  updating private packs; the install path always loads the token.
+- Deletes the old install directory before downloading the new version.
+  (src/commands/update.js:54-62)
+- Updates `tapestry-boot.yaml` for the new version via `addPackageToBoot`.
+  (src/commands/update.js:80-81)
+- Reports "up to date" and skips download when the resolved version matches what the lock
+  already has. (src/commands/update.js:46-49)
+
+### enable / disable
+
+- Both require `tapestry.yaml`. (src/commands/enable.js:4-9) (src/commands/disable.js:1-16)
+- Delegate to `enablePackage` / `disablePackage` in boot.js, which set `enabled: true/false`
+  on the pack entry and on every module entry for that package in `tapestry-boot.yaml`.
+  (src/lib/boot.js:51-76)
+- Throw if the package is not in `tapestry-boot.yaml`. (src/lib/boot.js:56) (src/lib/boot.js:68)
+
+### link / unlink
+
+- `link` requires `tapestry.yaml` and an existing path. (src/commands/link.js:33-38)
+- Reads the target's `pack.yaml`, records the name-to-absolute-path mapping in
+  `tapestry-links.yaml`, and adds the pack to `tapestry-boot.yaml`. (src/commands/link.js:45-47)
+- Appends `tapestry-links.yaml` to `.gitignore` if not already present.
+  (src/commands/link.js:22-30)
+- Warns if `active: false` is set in the linked pack's manifest. (src/commands/link.js:49-52)
+- With `--skip-install`, skips dependency resolution and prints warnings for any missing deps
+  instead. (src/commands/link.js:53-58)
+- Without `--skip-install`, resolves and installs only the deps of the linked pack that are not
+  already on disk. Rolls back all changes (link record, boot entry, any newly installed deps)
+  on resolution failure. (src/commands/link.js:62-109)
+- `unlink` removes the link record from `tapestry-links.yaml`, deletes any materialized copy
+  from `packs/`, and removes the pack and its module from `tapestry-boot.yaml`.
+  (src/commands/link.js:112-121)
+- `link --list` (or `link` with no path) prints each linked name and absolute path, flagging
+  missing paths with `(MISSING)`. (src/commands/link.js:123-133)
+
+### Boot-order management
+
+- `tapestry-boot.yaml` has two keys: `modules` (list of module class entries) and `packs`
+  (map of pack name to `{ enabled }` flag). (src/lib/boot.js:9-14)
+- `addPackageToBoot` writes the pack entry (always `enabled: true`) and, if the manifest has a
+  `module.class`, appends a module entry then topologically sorts all modules.
+  (src/lib/boot.js:22-41)
+- `removePackageFromBoot` deletes the pack entry and all module entries for that package.
+  (src/lib/boot.js:44-49)
+- Topological sort honors `module.after` to order .NET classes that depend on each other.
+  Cycles throw. (src/lib/boot.js:79-110)
+
+### Dependency resolution
+
+- Resolution is a breadth-first queue over `name@range` pairs, fetching package metadata from
+  `/v1/packages/<name>`. (src/lib/semver-resolver.js:21-79)
+- Dist-tag names (all lowercase letters) are resolved to a version range via `meta.dist_tags`
+  before semver selection. (src/lib/semver-resolver.js:39-44)
+- Picks the maximum semver version satisfying the range. Conflicts (same package, incompatible
+  ranges from different requirers) throw with a descriptive message.
+  (src/lib/semver-resolver.js:24-32) (src/lib/semver-resolver.js:46-51)
+- Transitive dependencies are queued from the resolved manifest's `dependencies` field; peer
+  dependencies emit a warning if not present but do not block resolution.
+  (src/lib/semver-resolver.js:69-79)
+- Package names must match `@scope/name` format; path traversal (`..`, `//`) is rejected at
+  the HTTP layer. (src/lib/registry-client.js:7-16)
+
+### pack (build tarball)
+
+- Runs `validate` first; aborts on validation failure. (src/commands/pack.js:7)
+- For ESM packs (`scripts_format: esm`), compiles `scripts/**/*.ts` to `dist/scripts/**/*.js`
+  using the bundled `tsc` and the pack's `tsconfig.json`; legacy packs are a no-op.
+  (src/commands/pack.js:14) (src/lib/ts-build.js:8-20)
+- Builds a `.tgz` under a `package/` prefix in the current directory named
+  `<shortName>-<version>.tgz`. (src/commands/pack.js:16) (src/lib/tarball-builder.js:16-26)
+- Excludes `.git`, `node_modules`, `.DS_Store`, and `.tgz` files from the archive.
+  (src/lib/tarball-builder.js:7-12)
+- Prints the `sha256-<base64>` integrity hash of the output file.
+  (src/commands/pack.js:22) (src/lib/tarball-builder.js:29-33)
+
+### publish
+
+- Runs `validate` first; aborts on validation failure. (src/commands/publish.js:18)
+- For ESM packs (`scripts_format: esm`), compiles `scripts/**/*.ts` to `dist/scripts/**/*.js`
+  using the bundled `tsc` and the pack's `tsconfig.json` before any network or auth work;
+  legacy packs are a no-op. (src/commands/publish.js:21) (src/lib/ts-build.js:8-20)
+- In a GitHub Actions OIDC environment (both `ACTIONS_ID_TOKEN_REQUEST_URL` and
+  `ACTIONS_ID_TOKEN_REQUEST_TOKEN` set), fetches a GitHub id-token and exchanges it for a
+  scoped access token; also sets a `tag: stable` field on the form.
+  (src/commands/publish.js:26-30)
+- Otherwise, requires an existing authenticated session. (src/commands/publish.js:31)
+- Builds the tarball to a temp file, computes integrity, POSTs a multipart form with the
+  tarball and JSON metadata (manifest fields plus integrity) to `/v1/publish`.
+  (src/commands/publish.js:40-65)
+- Deletes the temp file in a `finally` block. (src/commands/publish.js:71-73)
+
+### create pack (scaffold)
+
+- Accepts `@scope/name` (used as-is) or a plain name (scope defaults to `@todo`).
+  (src/commands/create-pack.js:8-18)
+- Creates a subdirectory named after the short name in the current directory; throws if it
+  already exists. (src/commands/create-pack.js:41-46)
+- Writes the scaffold files from `generatePackFiles` and prints each one.
+  (src/commands/create-pack.js:48-57) (src/scaffold/templates.js)
+
+### list
+
+- Reads the lock file and boot file; prints package name, resolved version, type (from the
+  installed `pack.yaml`), and enabled/disabled status.
+  (src/commands/list.js:17-48)
+- If no packages are installed, prints "No packages installed." (src/commands/list.js:46-48)
+- Also prints linked packs below the installed list, flagging missing paths.
+  (src/commands/list.js:50-58)
+
+## Rejected and Reverted
+
+- None on record.
+
+## Change Log
+
+- None on record.

package/specs/registry-auth.md

@@ -0,0 +1,127 @@
+---
+capability: registry-auth
+last-updated: 2026-06-13
+---
+
+# registry-auth
+
+Capability spec for user identity, session management, and OIDC trusted publishing.
+
+## Overview
+
+registry-auth covers everything the CLI does on behalf of a user's identity: password-based
+login that exchanges credentials for an access/refresh token pair; silent proactive token
+refresh before expiry; logout with best-effort server-side revocation; account registration
+and password change; and the OIDC trusted-publishing path that lets a GitHub Actions workflow
+publish a pack without stored credentials.
+
+Trust binding management (`tapestry trust add/list/rm`) is in this boundary because it
+configures the OIDC flow on the registry side.
+
+## Behavior
+
+### Session storage
+
+- The session file lives at `~/.tapestryrc` (resolved via `os.homedir()`).
+  (src/lib/auth.js:9)
+- Written with mode `0o600` (user-read/write only). (src/lib/auth.js:28)
+- Contains four YAML keys: `registry` (the registry URL), `access` (the access JWT),
+  `access_exp` (the JWT `exp` claim decoded as a Unix timestamp), and `refresh` (the refresh
+  token string). (src/lib/auth.js:24-29)
+- `decodeExp` extracts `exp` from the JWT payload by base64url-decoding the second segment.
+  Returns null on any parse error. (src/lib/auth.js:38-45)
+- `readSession` returns null if the file is absent or unparseable.
+  (src/lib/auth.js:13-20)
+- `clearSession` deletes the file if it exists; does nothing otherwise.
+  (src/lib/auth.js:32-36)
+
+### Token refresh
+
+- `loadAccess` returns the stored access token if `access_exp` is present and the token will
+  not expire within the next 60 seconds (`REFRESH_SKEW_SECONDS`). (src/lib/auth.js:52-54)
+- If the access token is expired or near expiry, `loadAccess` silently POSTs the refresh
+  token to `<registry>/v1/auth/refresh` and saves the new access and refresh tokens.
+  (src/lib/auth.js:58-68)
+- If the refresh request fails, the session is cleared and `loadAccess` returns null (treated
+  as "not logged in" by callers). (src/lib/auth.js:63-65)
+- `requireAccess` wraps `loadAccess` and throws "Not logged in. Run: tapestry login" if the
+  result is null. (src/lib/auth.js:72-77)
+- Sessions that have an `access` token but no `refresh` token (legacy format) are treated as
+  absent by `loadAccess`. (src/lib/auth.js:48-50)
+
+### login
+
+- Prompts for email and password interactively unless both are passed programmatically.
+  (src/commands/login.js:8-16) (src/commands/login.js:19-21)
+- POSTs `{ email, password }` to `<registry>/v1/auth/login`. (src/commands/login.js:23-28)
+- On success, saves the returned `access_token`, its decoded `exp`, and `refresh_token` to
+  `~/.tapestryrc`. Prints "Logged in." (src/commands/login.js:33-34)
+- The registry URL defaults to `TAPESTRY_REGISTRY` env var or
+  `https://registry.tapestryengine.com`. (src/lib/registry-client.js:5)
+
+### logout
+
+- Reads the current session. If a refresh token is present, attempts a server-side revocation
+  by POSTing the refresh token to `<registry>/v1/auth/logout`. Server errors are swallowed;
+  the local session is always cleared regardless. (src/commands/logout.js:6-17)
+- Deletes `~/.tapestryrc`. Prints "Logged out." (src/commands/logout.js:14-16)
+
+### register
+
+- Prompts for handle, email, and password unless all three are passed programmatically.
+  (src/commands/register.js:8-18)
+- POSTs `{ handle, email, password }` to `<registry>/v1/auth/register`. On success, saves
+  the returned token pair and prints "Registered as <handle>. Logged in."
+  (src/commands/register.js:24-36)
+
+### change-password
+
+- Requires an active session (`requireAccess`); throws if not logged in.
+  (src/commands/change-password.js:9)
+- Prompts for current password, new password, and confirmation; throws if the two new-password
+  entries do not match. (src/commands/change-password.js:10-17)
+- POSTs `{ currentPassword, newPassword }` to `<registry>/v1/auth/change-password` with a
+  Bearer token. Prints "Password changed." on success. (src/commands/change-password.js:18-24)
+
+### OIDC trusted publishing
+
+- CI mode is detected when both `ACTIONS_ID_TOKEN_REQUEST_URL` and
+  `ACTIONS_ID_TOKEN_REQUEST_TOKEN` environment variables are set. (src/lib/oidc.js:7-9)
+- `fetchGitHubIdToken` fetches the GitHub OIDC id-token by GETting
+  `$ACTIONS_ID_TOKEN_REQUEST_URL&audience=<audience>` with the request token in the
+  Authorization header. The audience constant is `https://registry.tapestryengine.com`.
+  (src/lib/oidc.js:5) (src/lib/oidc.js:11-24)
+- `exchangeOIDCForAccess` POSTs the id-token (as a Bearer token) and the target scope to
+  `<registry>/v1/token`, returning the `access_token` from the response.
+  (src/lib/registry-client.js:169-178)
+- `publish` uses OIDC in CI mode and also appends `tag: stable` to the publish form;
+  in interactive mode it uses the standard session access token.
+  (src/commands/publish.js:22-30)
+
+### Trust binding management
+
+Trust bindings authorize a GitHub repository to publish packs to a scope via OIDC without
+stored credentials. All three sub-commands require an active session.
+
+- `trust add <scope> <repo>` POSTs `{ scope, repo }` (plus optional `ref` and `environment`)
+  to `<registry>/v1/trusted-publishers`. Prints the assigned id on success.
+  (src/lib/registry-client.js:141-149) (src/commands/trust.js:13-19)
+- `trust list` GETs `/v1/trusted-publishers` (optionally filtered with `?scope=`).
+  Prints each binding as `#<id>  @<scope> <- <repo>  (ref=... env=...)`.
+  (src/lib/registry-client.js:151-158) (src/commands/trust.js:22-33)
+- `trust rm <id>` DELETEs `/v1/trusted-publishers/<id>`.
+  (src/lib/registry-client.js:160-167) (src/commands/trust.js:36-40)
+
+### Rate limiting
+
+- HTTP 429 responses are detected before any other error handling. If the response includes a
+  `retry-after` header (in seconds), the error message includes a "Try again in N min." hint.
+  (src/lib/registry-client.js:20-24)
+
+## Rejected and Reverted
+
+- None on record.
+
+## Change Log
+
+- None on record.

package/specs/validate.md

@@ -0,0 +1,70 @@
+---
+capability: validate
+last-updated: 2026-06-13
+---
+
+# validate
+
+Capability spec for offline pack manifest validation.
+
+## Overview
+
+`tapestry validate` reads `pack.yaml` from the current directory and checks it against the
+Zod schema that defines a valid pack manifest. No network calls are made; no registry is
+consulted. The command is also called internally by `pack` and `publish` before they proceed.
+
+## Behavior
+
+- Looks for `pack.yaml` (the constant `PACK_MANIFEST`) in the current working directory.
+  (src/lib/manifest.js:3) (src/commands/validate.js:10-11)
+- If `pack.yaml` is absent but `tapestry.yaml` is present, throws a specific error explaining
+  that the file found is a server manifest, not a pack manifest.
+  (src/commands/validate.js:13-20)
+- If neither file is present, throws "No pack.yaml found in current directory".
+  (src/commands/validate.js:21)
+- Runs `validatePackageManifest` which calls Zod's `safeParse` on the YAML-parsed data.
+  (src/commands/validate.js:25-26) (src/schema/manifest.js:58-60)
+- On success, prints "OK  <name> v<version>" with two leading spaces. (src/commands/validate.js:38-39)
+- On failure, iterates Zod issues and prints each as "  error: <fieldPath> - <message>".
+  The field path is the dot-joined `issue.path`, or "root" if the path is empty.
+  (src/commands/validate.js:29-36)
+- For an `engine` field that is an object (the server manifest format) in a document being
+  validated as a pack manifest, appends a hint that `engine` must be a version constraint
+  string in pack manifests. (src/commands/validate.js:31-35)
+- Throws with a count of validation errors so callers (`pack`, `publish`) can abort.
+  (src/commands/validate.js:37)
+
+### Pack manifest schema
+
+Required fields (src/schema/manifest.js:7-39):
+
+- `name` -- string matching `@scope/package-name` (lowercase letters, digits, hyphens only).
+- `version` -- non-empty string (no semver enforcement at this layer).
+- `type` -- one of `core`, `module`, `world`.
+- `display_name` -- non-empty string.
+- `description` -- non-empty string.
+- `author` -- non-empty string.
+- `license` -- non-empty string.
+- `engine` -- non-empty string (a version constraint, e.g. `>=0.0.1`).
+- `validation` -- one of `strict`, `lenient`.
+
+Optional fields (src/schema/manifest.js:17-38):
+
+- `dependencies` -- record of package name to version range string.
+- `peerDependencies` -- record of package name to version range string.
+- `provides` -- array of strings.
+- `tags` -- string.
+- `module` -- object with required `assembly`, `class`, `implements`; optional `after`.
+- `content` -- record of glob key to glob pattern string.
+- `client` -- object with `manifest`, `assets`, `min_client_version`.
+- `meta` -- object with optional `commands` (string array), `properties` (number), `keywords`
+  (string array).
+- `private` -- boolean.
+
+## Rejected and Reverted
+
+- None on record.
+
+## Change Log
+
+- None on record.

package/src/commands/pack.js

@@ -5,11 +5,14 @@ const { readYaml } = require('../util/yaml');
 const { buildTarball, computeIntegrity } = require('../lib/tarball-builder');
 const { PACK_MANIFEST } = require('../lib/manifest');
 const { validate } = require('./validate');
+const { buildTypeScript } = require('../lib/ts-build');
 
 async function pack({ cwd = process.cwd() } = {}) {
   validate({ cwd });
 
   const manifest = readYaml(path.join(cwd, PACK_MANIFEST));
+  buildTypeScript(cwd, manifest);
+
   const shortName = manifest.name.split('/')[1];
   const outputPath = path.join(cwd, `${shortName}-${manifest.version}.tgz`);
 

package/src/commands/publish.js

@@ -12,11 +12,13 @@ const { PACK_MANIFEST } = require('../lib/manifest');
 const { requireAccess } = require('../lib/auth');
 const { DEFAULT_REGISTRY, throwIfError, exchangeOIDCForAccess } = require('../lib/registry-client');
 const { detectCI, fetchGitHubIdToken, AUDIENCE } = require('../lib/oidc');
+const { buildTypeScript } = require('../lib/ts-build');
 
 async function publish({ cwd = process.cwd(), registryUrl = DEFAULT_REGISTRY } = {}) {
   validate({ cwd });
 
   const manifest = readYaml(path.join(cwd, PACK_MANIFEST));
+  buildTypeScript(cwd, manifest);
 
   const scope = manifest.name.match(/^@([^/]+)\//)[1];
   const ciMode = detectCI();

package/src/commands/types.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function types({ cwd = process.cwd() } = {}) {
+  const src = path.join(__dirname, '..', '..', 'types', 'tapestry-engine.d.ts');
+  const destDir = path.join(cwd, 'types');
+  fs.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, 'tapestry-engine.d.ts');
+  fs.copyFileSync(src, dest);
+  console.log(`Wrote ${path.relative(cwd, dest)}`);
+}
+
+module.exports = { types };

package/src/lib/ts-build.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Compiles an ESM pack's TypeScript (scripts/**/*.ts -> dist/scripts/**/*.js) using the
+// bundled tsc and the pack's tsconfig.json. No-op for legacy packs (raw .js, no build).
+function buildTypeScript(cwd, manifest) {
+  const format = manifest && manifest.content && manifest.content.scripts_format;
+  if (format !== 'esm') {
+    return;
+  }
+  const tsc = require.resolve('typescript/bin/tsc');
+  const tsconfig = path.join(cwd, 'tsconfig.json');
+  console.log('Compiling TypeScript (tsc)...');
+  const res = spawnSync(process.execPath, [tsc, '-p', tsconfig], { cwd, stdio: 'inherit' });
+  if (res.status !== 0) {
+    throw new Error('TypeScript compile failed');
+  }
+}
+
+module.exports = { buildTypeScript };