@tapestry-mud/cli 0.10.0 → 0.12.0

package/bin/tapestry.js

@@ -411,15 +411,15 @@ async function runHarvest(areaRef, opts) {
 program
   .command('harvest <areaRef>')
   .description('Harvest an authored area into a portable pack (areaRef = namespace:area-id)')
-  .option('--sink <sink>', 'Output sink: file | git (auto-detected by default)')
+  .option('--sink <sink>', 'Output sink: file | git | registry (auto-detected by default)')
   .option('--out <path>', '(file sink) where the .tgz lands')
-  .option('--name <name>', '(file sink) override the synthesized pack name (@scope/pack)')
+  .option('--name <name>', '(file/registry sink) override the synthesized pack name (@scope/pack)')
   .option('--pack <dir>', 'Target pack directory (auto-detected from linked packs by default)')
   .option('--game-root <path>', 'Game root containing data/ (default: current dir)')
   .option('--keep-sidecars', 'Copy instead of move (leave the game-root side-cars in place)')
   .option('--force', 'Overwrite pack files that diverge from the side-car')
-  .option('--minor', 'Bump the pack minor version (git sink only; default: patch)')
-  .option('--major', 'Bump the pack major version (git sink only; default: patch)')
+  .option('--minor', 'Bump the pack minor version (git/registry sink, owned pack only; default: patch)')
+  .option('--major', 'Bump the pack major version (git/registry sink, owned pack only; default: patch)')
   .action(runHarvest);
 
 // Deprecated: sync-area is now harvest --sink git.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapestry-mud/cli",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "CLI for the Tapestry MUD engine",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "commander": "11.1.0",
-    "form-data": "4.0.5",
+    "form-data": "4.0.6",
     "inquirer": "8.2.7",
     "js-yaml": "4.1.1",
     "node-fetch": "2.7.0",

package/specs/README.md

@@ -9,7 +9,7 @@ behave?" from the relevant file alone.
 
 | Capability | File | Last Updated |
 |------------|------|--------------|
-| pack-lifecycle | [pack-lifecycle.md](pack-lifecycle.md) | 2026-06-13 |
+| pack-lifecycle | [pack-lifecycle.md](pack-lifecycle.md) | 2026-06-20 |
 | validate | [validate.md](validate.md) | 2026-06-13 |
 | harvest | [harvest.md](harvest.md) | 2026-06-13 |
 | registry-auth | [registry-auth.md](registry-auth.md) | 2026-06-13 |

package/specs/changes/2026-06-20-pack-esm-build.md

@@ -0,0 +1,28 @@
+---
+release: 0.10.0
+specs: [pack-lifecycle.md]
+---
+
+# Pack ESM Build
+
+## Why
+
+Packs are authored in TypeScript and ship native ES modules, but the CLI had no
+build step: `pack` and `publish` archived whatever was on disk. An ESM pack
+declares `content.scripts_format: esm` and points `content.scripts` at compiled
+output under `dist/scripts/`, which is gitignored - so without a compile the
+tarball shipped no runnable scripts. Pack authors also had no typed surface for
+the engine API they call, so editors could not check `tapestry.*` usage.
+
+## What
+
+- `pack` and `publish` compile an ESM pack's `scripts/**/*.ts` to
+  `dist/scripts/**/*.js` with the bundled `tsc` and the pack's `tsconfig.json`
+  before building the tarball. The compile runs before any network or auth work
+  in `publish`. Legacy packs (no `scripts_format: esm`) are a no-op, so the step
+  is backward compatible.
+- New `tapestry types` command vendors the `@tapestry/engine` type definitions
+  into a project's `types/` so `tsc` and editors can type-check pack scripts
+  against the engine API surface the pack calls.
+- `typescript` is pinned exactly as a CLI dependency (no caret) so the compile is
+  reproducible.

package/specs/harvest.md

@@ -133,12 +133,20 @@ current version. (src/lib/file-sink.js:19-21)
 - Without `--force`: throws if a room file in the target differs from the incoming side-car.
   (src/lib/render-core.js:41-45)
 - With `--force`: overwrites divergent room files silently. (src/lib/render-core.js:40-49)
-- After writing, calls `ensureContentGlobs` to additively add `area_definitions` and `rooms`
-  glob entries to `pack.yaml` if not already present. (src/lib/render-core.js:52)
-  (src/lib/pack-manifest.js:7-31)
+- After writing rooms, copies oracle side-car files: `places-oracle.yaml` at the area root and
+  any `*-oracle-table.yaml` files anywhere under the area tree (including inside `mobs/` and
+  `items/` subdirectories). The same divergence guard (throw without `--force`, overwrite with
+  `--force`) applies. (src/lib/render-core.js) (src/lib/pack-manifest.js)
+- After copying oracle side-cars, copies all `*.yaml` files from `mobs/` and `items/` under the
+  area side-car tree into the corresponding `areas/<area>/mobs/` and `areas/<area>/items/`
+  directories in the target pack, including any `*-oracle-table.yaml` files in those directories.
+  The same divergence guard applies. (src/lib/render-core.js)
+- After writing, calls `ensureContentGlobs` to additively add `area_definitions`, `rooms`,
+  `oracle_tables`, `places_oracle`, `mobs`, and `items` glob entries to `pack.yaml` if not
+  already present. (src/lib/render-core.js) (src/lib/pack-manifest.js)
 - `reconcileDependencies` is a deliberate no-op: rooms are self-contained; the seam is wired
   for a future slice that will scan for cross-pack references in mobs/items/quests.
-  (src/lib/render-core.js:63-65)
+  (src/lib/render-core.js)
 
 ### Side-car removal (default behavior)
 
@@ -156,4 +164,6 @@ empty. `area.yaml` in the game root is also deleted. (src/lib/render-core.js:69-
 
 ## Change Log
 
-- None on record.
+- 2026-06-23 (0.11.0): renderArea carries oracle table side-cars (places-oracle.yaml, *-oracle-table.yaml)
+  and mints mob/item instance files (mobs/*.yaml, items/*.yaml) into the target pack alongside
+  area.yaml and rooms/. CONTENT_GLOBS gains oracle_tables, places_oracle, mobs, items.

package/specs/pack-lifecycle.md

@@ -1,6 +1,6 @@
 ---
 capability: pack-lifecycle
-last-updated: 2026-06-13
+last-updated: 2026-06-20
 ---
 
 # pack-lifecycle
@@ -203,4 +203,4 @@ order file is `tapestry-boot.yaml`; links are tracked in `tapestry-links.yaml`.
 
 ## Change Log
 
-- None on record.
+- 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/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/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 };

package/src/lib/render-core.js

@@ -6,6 +6,44 @@ const { readYaml, writeYaml } = require('../util/yaml');
 const { ensureContentGlobs } = require('./pack-manifest');
 const { packNamespace } = require('./pack-resolve');
 
+// Recursively collect files matching a name predicate under a directory.
+// Returns absolute paths.
+function collectFiles(dir, predicate, results = []) {
+  if (!fs.existsSync(dir)) {
+    return results;
+  }
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      collectFiles(path.join(dir, entry.name), predicate, results);
+    } else if (predicate(entry.name)) {
+      results.push(path.join(dir, entry.name));
+    }
+  }
+  return results;
+}
+
+// Copy oracle side-car yaml files from the area source root into the area dest root,
+// preserving relative paths and applying the divergence guard.
+function copyOracleSideCars(areaSrcRoot, areaDestRoot, force) {
+  const oracleFiles = collectFiles(areaSrcRoot, (name) => {
+    return name === 'places-oracle.yaml' || name.endsWith('-oracle-table.yaml');
+  });
+  for (const src of oracleFiles) {
+    const rel = path.relative(areaSrcRoot, src);
+    const dest = path.join(areaDestRoot, rel);
+    const incoming = readYaml(src);
+    if (fs.existsSync(dest) && !force) {
+      const existing = readYaml(dest);
+      if (JSON.stringify(existing) !== JSON.stringify(incoming)) {
+        throw new Error(
+          `Pack file ${dest} diverges from the side-car. Review the diff and re-run with --force to overwrite.`);
+      }
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    writeYaml(dest, incoming);
+  }
+}
+
 // Fold one area's authored side-cars into a target pack directory. Setup-independent:
 // it does not know whether targetDir is a real repo or a temp build dir.
 // Returns { written, files }. Throws if there is nothing to render or a pack file diverges.
@@ -49,6 +87,35 @@ function renderArea(targetDir, { gameRoot, area, force = false }) {
     written++;
   }
 
+  // Copy oracle table side-cars: places-oracle.yaml at the area root,
+  // and any *-oracle-table.yaml files in subdirectories (mobs/, items/, etc.).
+  const areaSrcRoot = path.join(gameRoot, 'data', 'areas', area);
+  const areaDestRoot = path.join(targetDir, 'areas', area);
+  copyOracleSideCars(areaSrcRoot, areaDestRoot, force);
+
+  // Copy minted mob and item instance files (including their *-oracle-table.yaml).
+  for (const sub of ['mobs', 'items']) {
+    const srcDir = path.join(gameRoot, 'data', 'areas', area, sub);
+    if (fs.existsSync(srcDir)) {
+      const subFiles = fs.readdirSync(srcDir).filter((f) => f.endsWith('.yaml'));
+      const destDir = path.join(targetDir, 'areas', area, sub);
+      fs.mkdirSync(destDir, { recursive: true });
+      for (const file of subFiles) {
+        const src = path.join(srcDir, file);
+        const dest = path.join(destDir, file);
+        const incoming = readYaml(src);
+        if (fs.existsSync(dest) && !force) {
+          const existing = readYaml(dest);
+          if (JSON.stringify(existing) !== JSON.stringify(incoming)) {
+            throw new Error(
+              `Pack file ${dest} diverges from the side-car. Review the diff and re-run with --force to overwrite.`);
+          }
+        }
+        writeYaml(dest, incoming);
+      }
+    }
+  }
+
   ensureContentGlobs(targetDir);
   reconcileDependencies(targetDir, area);