@tapestry-mud/cli 0.9.0 → 0.12.0

package/specs/pack-lifecycle.md

@@ -0,0 +1,206 @@
+---
+capability: pack-lifecycle
+last-updated: 2026-06-20
+---
+
+# 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
+
+- 2026-06-20 (0.10.0): `pack` and `publish` compile ESM packs (`scripts_format: esm`) via `tsc` before archiving; new `tapestry types` command vendors the engine `.d.ts`. See changes/2026-06-20-pack-esm-build.md.

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/harvest.js

@@ -4,6 +4,7 @@ const { parseAreaRef, resolvePackDirOrNull } = require('../lib/pack-resolve');
 const { isRepo } = require('../lib/git');
 const { syncArea } = require('./sync-area');
 const { fileSink } = require('../lib/file-sink');
+const { registrySink } = require('../lib/registry-sink');
 
 // Umbrella harvest verb. Auto-detects the sink (owned linked pack that is a git repo -> git;
 // else file) unless --sink is explicit. The render core is shared by every sink.
@@ -23,14 +24,23 @@ async function harvest(areaRef, options = {}) {
     return syncArea(areaRef, options);
   }
   if (sink === 'file') {
-    // The file sink snapshots at the current version -- it ignores --minor/--major (git-sink only).
+    // The file sink snapshots at the current version -- it ignores --minor/--major.
     return fileSink(areaRef, {
       cwd, gameRoot, namespace, area,
       force: options.force, keepSidecars: options.keepSidecars,
       out: options.out, name: options.name, pack: options.pack,
     });
   }
-  throw new Error(`Unknown sink '${sink}'. Use 'file' or 'git'.`);
+  if (sink === 'registry') {
+    return registrySink(areaRef, {
+      cwd, gameRoot, namespace, area,
+      force: options.force, keepSidecars: options.keepSidecars,
+      pack: options.pack, name: options.name,
+      bump: options.bump,
+      registryUrl: options.registryUrl,
+    });
+  }
+  throw new Error(`Unknown sink '${sink}'. Use 'file', 'git', or 'registry'.`);
 }
 
 module.exports = { harvest };

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/pack-manifest.js

@@ -7,6 +7,10 @@ const { readYaml, writeYaml } = require('../util/yaml');
 const CONTENT_GLOBS = {
   area_definitions: 'areas/**/area.yaml',
   rooms: 'areas/**/rooms/*.yaml',
+  oracle_tables: 'areas/**/*-oracle-table.yaml',
+  places_oracle: 'areas/**/places-oracle.yaml',
+  mobs: 'areas/**/mobs/*.yaml',
+  items: 'areas/**/items/*.yaml',
 };
 
 // Additively ensure the pack manifest declares the given content globs.

package/src/lib/registry-sink.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const fetch = require('node-fetch');
+const FormData = require('form-data');
+const { readYaml, writeYaml } = require('../util/yaml');
+const { resolvePackDirOrNull } = require('./pack-resolve');
+const { renderArea, removeSideCars, assertNamespaceMatch } = require('./render-core');
+const { synthesizeManifest, bumpVersion } = require('./pack-manifest');
+const { buildTarball, computeIntegrity } = require('./tarball-builder');
+const { isRepo } = require('./git');
+const { requireAccess } = require('./auth');
+const { DEFAULT_REGISTRY, throwIfError } = require('./registry-client');
+
+// Registry sink: render -> tar -> POST /v1/publish.
+// Run where the registry token lives (operator machine or no-git server).
+// Refuses registry-direct when the linked pack is repo-backed (source-of-truth trap).
+//
+// Owned (linked pack, not git repo): mirrors the git sink. Renders into the REAL pack dir
+// so content accumulates in the operator's source of truth across repeated harvests; bumps;
+// tars+POSTs. Edge: if POST fails after render+bump, the real pack holds both - re-running
+// re-renders to a no-op and re-bumps (a registry version gap, accepted, source truth intact).
+//
+// Hobbyist (no linked pack): mirrors the file sink. Synthesizes a manifest, renders into a
+// temp dir, tars+POSTs. No persistent bump. A second publish at 0.1.0 will fail at the
+// registry - the intended signal to set up a real pack.
+async function registrySink(areaRef, options) {
+  const { cwd, gameRoot, namespace, area } = options;
+  const force = !!options.force;
+  const keepSidecars = !!options.keepSidecars;
+  const registryUrl = options.registryUrl || DEFAULT_REGISTRY;
+
+  const packDir = resolvePackDirOrNull(cwd, namespace, options.pack);
+
+  if (packDir && isRepo(packDir)) {
+    throw new Error(
+      `Cannot publish registry-direct: '${packDir}' is a git repo.\n` +
+      `Harvest to file instead: tapestry harvest ${areaRef} --sink file\n` +
+      `Pull the .tgz to the machine that owns the repo, unpack into the repo, commit, push,\n` +
+      `and let CI publish.`
+    );
+  }
+
+  let files;
+  let manifest;
+  let tmpBuild = null;
+  let tmpTgz;
+
+  try {
+    if (packDir) {
+      const existingManifest = readYaml(path.join(packDir, 'pack.yaml')) || {};
+      assertNamespaceMatch(existingManifest, namespace, packDir);
+
+      // Fail loudly on EACCES before any mutation - never silently.
+      try {
+        fs.accessSync(packDir, fs.constants.W_OK);
+      } catch (e) {
+        throw new Error(
+          `Cannot write to pack directory ${packDir}: ${e.message}. ` +
+          `The user running tapestry may not own that directory.`
+        );
+      }
+
+      // Render into the REAL pack dir (content accumulates), then bump.
+      ({ files } = renderArea(packDir, { gameRoot, area, force }));
+      bumpVersion(packDir, options.bump || 'patch');
+      manifest = readYaml(path.join(packDir, 'pack.yaml'));
+    } else {
+      tmpBuild = fs.mkdtempSync(path.join(os.tmpdir(), 'tapestry-harvest-'));
+      manifest = synthesizeManifest(namespace, { name: options.name });
+      writeYaml(path.join(tmpBuild, 'pack.yaml'), manifest);
+      ({ files } = renderArea(tmpBuild, { gameRoot, area, force }));
+      // Re-read after render in case ensureContentGlobs updated the manifest.
+      manifest = readYaml(path.join(tmpBuild, 'pack.yaml'));
+    }
+
+    const buildDir = tmpBuild || packDir;
+    const shortName = manifest.name.split('/')[1];
+    tmpTgz = path.join(os.tmpdir(), `tapestry-publish-${shortName}-${manifest.version}.tgz`);
+
+    await buildTarball(buildDir, tmpTgz);
+    const integrity = computeIntegrity(tmpTgz);
+    const token = await requireAccess();
+
+    const form = new FormData();
+    form.append('tarball', fs.createReadStream(tmpTgz), {
+      filename: `${manifest.version}.tgz`,
+      contentType: 'application/gzip',
+    });
+    form.append('metadata', JSON.stringify({ ...manifest, integrity }));
+
+    const res = await fetch(`${registryUrl}/v1/publish`, {
+      method: 'POST',
+      headers: { ...form.getHeaders(), Authorization: `Bearer ${token}` },
+      body: form,
+    });
+    await throwIfError(res, 'Publish failed');
+    const result = await res.json();
+
+    if (!keepSidecars) {
+      removeSideCars(gameRoot, area, files);
+    }
+    console.log(`Harvested area '${area}' and published ${result.name}@${result.version}.`);
+    console.log('Run `tapestry update` on your game server to pull the new version.');
+  } finally {
+    if (tmpTgz && fs.existsSync(tmpTgz)) {
+      fs.unlinkSync(tmpTgz);
+    }
+    if (tmpBuild) {
+      fs.rmSync(tmpBuild, { recursive: true, force: true });
+    }
+  }
+}
+
+module.exports = { registrySink };