@tapestry-mud/cli 0.8.0 → 0.9.0

package/bin/tapestry.js

@@ -31,6 +31,8 @@ const { distTagSet, distTagList } = require('../src/commands/dist-tag');
 const { presetSet, presetDelete } = require('../src/commands/preset');
 const { trustAdd, trustList, trustRm } = require('../src/commands/trust');
 const { syncArea } = require('../src/commands/sync-area');
+const { harvest } = require('../src/commands/harvest');
+const { status } = require('../src/commands/status');
 
 const program = new Command();
 
@@ -60,7 +62,7 @@ program.configureHelp({
       },
       {
         title: 'Pack Authoring',
-        commands: ['create', 'validate', 'pack', 'publish', 'unpublish', 'sync-area'],
+        commands: ['create', 'validate', 'pack', 'publish', 'unpublish', 'harvest', 'status'],
       },
       {
         title: 'Trusted Publishing',
@@ -361,12 +363,28 @@ program
     }
   });
 
-function runSyncArea(areaRef, opts) {
+program
+  .command('status')
+  .description('Show world state per area (Clean / Edited / Fork / WIP)')
+  .option('--game-root <path>', 'Game root containing data/ (default: current dir)')
+  .action((opts) => {
+    try {
+      status({ cwd: process.cwd(), gameRoot: opts.gameRoot });
+    } catch (e) {
+      console.error(`error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+async function runHarvest(areaRef, opts) {
   try {
-    syncArea(areaRef, {
+    await harvest(areaRef, {
       cwd: process.cwd(),
       gameRoot: opts.gameRoot,
       pack: opts.pack,
+      sink: opts.sink,
+      out: opts.out,
+      name: opts.name,
       force: opts.force,
       keepSidecars: opts.keepSidecars,
       bump: opts.major ? 'major' : opts.minor ? 'minor' : 'patch',
@@ -377,20 +395,38 @@ function runSyncArea(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('--out <path>', '(file sink) where the .tgz lands')
+  .option('--name <name>', '(file 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)')
+  .action(runHarvest);
+
+// Deprecated: sync-area is now harvest --sink git.
 program
   .command('sync-area <areaRef>')
-  .description('Commit a game-root authored area back into its pack (areaRef = namespace:area-id)')
+  .description('(deprecated) alias for harvest --sink git')
   .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 (default: patch)')
   .option('--major', 'Bump the pack major version (default: patch)')
-  .action(runSyncArea);
+  .action((areaRef, opts) => {
+    console.warn('warning: `sync-area` is deprecated; use `harvest <area>` (auto-detects the git sink for an owned repo).');
+    runHarvest(areaRef, Object.assign({ sink: 'git' }, opts));
+  });
 
 program
   .command('export-area <areaRef>', { hidden: true })
-  .description('(deprecated) alias for sync-area')
+  .description('(deprecated) alias for harvest --sink git')
   .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)')
@@ -398,8 +434,8 @@ program
   .option('--minor', 'Bump the pack minor version (default: patch)')
   .option('--major', 'Bump the pack major version (default: patch)')
   .action((areaRef, opts) => {
-    console.warn('warning: `export-area` is deprecated; use `sync-area`.');
-    runSyncArea(areaRef, opts);
+    console.warn('warning: `export-area` is deprecated; use `harvest <area> --sink git`.');
+    runHarvest(areaRef, Object.assign({ sink: 'git' }, opts));
   });
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapestry-mud/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "CLI for the Tapestry MUD engine",
   "repository": {
     "type": "git",

package/src/commands/harvest.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { parseAreaRef, resolvePackDirOrNull } = require('../lib/pack-resolve');
+const { isRepo } = require('../lib/git');
+const { syncArea } = require('./sync-area');
+const { fileSink } = require('../lib/file-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.
+async function harvest(areaRef, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const gameRoot = options.gameRoot || cwd;
+  const { namespace, area } = parseAreaRef(areaRef);
+
+  let sink = options.sink;
+  if (!sink) {
+    const packDir = resolvePackDirOrNull(cwd, namespace, options.pack);
+    sink = (packDir && isRepo(packDir)) ? 'git' : 'file';
+  }
+
+  if (sink === 'git') {
+    // The git sink IS sync-area: render into the real repo, bump, commit, print push, move.
+    return syncArea(areaRef, options);
+  }
+  if (sink === 'file') {
+    // The file sink snapshots at the current version -- it ignores --minor/--major (git-sink only).
+    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'.`);
+}
+
+module.exports = { harvest };

package/src/commands/status.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { computeAreaStates } = require('../lib/world-state');
+
+function status({ cwd = process.cwd(), gameRoot } = {}) {
+  const root = gameRoot || cwd;
+  const rows = computeAreaStates(cwd, root);
+  if (!rows.length) {
+    console.log('No authored areas under data/areas.');
+    return;
+  }
+  console.log('World state (area-level):');
+  for (const r of rows) {
+    const wipTag = r.wip ? ' [WIP]' : '';
+    console.log(`  ${r.state.padEnd(7)} ${r.area} (${r.namespace || '?'}) rooms:${r.roomCount}${wipTag}`);
+  }
+  console.log('');
+  console.log('Clean = shipped; Edited = ready to harvest; Fork = owned by another pack; WIP = hidden from players.');
+  console.log('Strict boot remains the authority; this is a lighter on-host view.');
+}
+
+module.exports = { status };

package/src/commands/sync-area.js

@@ -2,45 +2,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const { readYaml, writeYaml } = require('../util/yaml');
-const { readLinks } = require('../lib/links');
-const { ensureContentGlobs, bumpVersion } = require('../lib/pack-manifest');
+const { readYaml } = require('../util/yaml');
+const { bumpVersion } = require('../lib/pack-manifest');
 const { isRepo, commitAll } = require('../lib/git');
-
-// "@legends/forgotten" -> "legends-forgotten" (mirrors engine PackLoader.PackNamespace)
-function packNamespace(name) {
-  if (name.indexOf('/') === -1) {
-    return name;
-  }
-  return name.replace(/^@/, '').split('/').join('-');
-}
-
-function detectPackDir(cwd, namespace, explicitPack) {
-  if (explicitPack) {
-    return path.isAbsolute(explicitPack) ? explicitPack : path.join(cwd, explicitPack);
-  }
-  const { links } = readLinks(cwd);
-  const matches = [];
-  for (const [name, dir] of Object.entries(links)) {
-    let derivedNs = namespace;
-    try {
-      const manifest = readYaml(path.join(dir, 'pack.yaml')) || {};
-      derivedNs = packNamespace(manifest.name || name);
-    } catch (e) {
-      derivedNs = packNamespace(name);
-    }
-    if (derivedNs === namespace) {
-      matches.push(dir);
-    }
-  }
-  if (matches.length === 1) {
-    return matches[0];
-  }
-  if (matches.length === 0) {
-    throw new Error(`Could not auto-detect a pack for namespace '${namespace}'. Pass --pack <dir>.`);
-  }
-  throw new Error(`Multiple linked packs match namespace '${namespace}'. Pass --pack <dir>.`);
-}
+const { packNamespace, detectPackDir, parseAreaRef } = require('../lib/pack-resolve');
+const { renderArea, removeSideCars, assertNamespaceMatch } = require('../lib/render-core');
 
 function syncArea(areaRef, options) {
   options = options || {};
@@ -50,72 +16,17 @@ function syncArea(areaRef, options) {
   const bumpLevel = options.bump || 'patch';
   const keepSidecars = !!options.keepSidecars;
 
-  const colon = areaRef.indexOf(':');
-  if (colon < 1) {
-    throw new Error('Usage: sync-area <namespace:area-id> [--pack <dir>]');
-  }
-  const namespace = areaRef.slice(0, colon);
-  const area = areaRef.slice(colon + 1);
-
-  const sideCarRooms = path.join(gameRoot, 'data', 'areas', area, 'rooms');
-  if (!fs.existsSync(sideCarRooms)) {
-    throw new Error(`No authored rooms found for area '${area}' at ${sideCarRooms}`);
-  }
-  const files = fs.readdirSync(sideCarRooms).filter((f) => f.endsWith('.yaml'));
-  if (files.length === 0) {
-    throw new Error(`No authored rooms found for area '${area}'`);
-  }
+  const { namespace, area } = parseAreaRef(areaRef);
 
   const packDir = detectPackDir(cwd, namespace, options.pack);
-
   const destManifestPath = path.join(packDir, 'pack.yaml');
   if (!fs.existsSync(destManifestPath)) {
-    throw new Error(`No pack.yaml found in ${packDir}. sync-area targets an existing pack; pass --pack <dir> pointing at one.`);
+    throw new Error(`No pack.yaml found in ${packDir}. harvest --sink git targets an existing pack; pass --pack <dir> pointing at one.`);
   }
   const destManifest = readYaml(destManifestPath) || {};
-  if (!destManifest.name) {
-    throw new Error(`pack.yaml in ${packDir} has no 'name' field.`);
-  }
-  const destNamespace = packNamespace(destManifest.name);
-  if (destNamespace !== namespace) {
-    throw new Error(
-      `Pack namespace '${destNamespace}' does not match area namespace '${namespace}'. ` +
-      'sync-area only commits an area back into its own pack; use link (or a future migrate) for cross-pack moves.'
-    );
-  }
-
-  const targetRooms = path.join(packDir, 'areas', area, 'rooms');
-  fs.mkdirSync(targetRooms, { recursive: true });
-
-  const sideCarAreaYaml = path.join(gameRoot, 'data', 'areas', area, 'area.yaml');
-  const targetAreaYaml = path.join(packDir, 'areas', area, 'area.yaml');
-  if (fs.existsSync(sideCarAreaYaml)) {
-    // Authored area.yaml already carries the full `area:` envelope (Spec A) — copy it home.
-    writeYaml(targetAreaYaml, readYaml(sideCarAreaYaml));
-  } else if (!fs.existsSync(targetAreaYaml)) {
-    // No authored or pack area.yaml — synthesize a minimal valid envelope so it strict-boots.
-    writeYaml(targetAreaYaml, {
-      area: { id: area, name: area, level_range: [1, 99], reset_interval: 300 },
-    });
-  }
-
-  let written = 0;
-  for (const file of files) {
-    const src = path.join(sideCarRooms, file);
-    const dest = path.join(targetRooms, 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);
-    written++;
-  }
+  assertNamespaceMatch(destManifest, namespace, packDir);
 
-  ensureContentGlobs(packDir);
+  const { written, files } = renderArea(packDir, { gameRoot, area, force });
 
   const { old, new: next } = bumpVersion(packDir, bumpLevel);
   let committed = false;
@@ -126,24 +37,8 @@ function syncArea(areaRef, options) {
     console.warn(`warn: ${packDir} is not a git repo; bumped to ${next} but did not commit.`);
   }
 
-  // Move = delete the game-root side-cars now that the content is durably in the pack.
-  // Runs after the write/commit above. In the non-git fallback the content is written
-  // (not committed); deletion is still correct because the pack dir holds the files.
   if (!keepSidecars) {
-    const areaSideCarDir = path.join(gameRoot, 'data', 'areas', area);
-    for (const file of files) {
-      fs.rmSync(path.join(sideCarRooms, file));
-    }
-    if (fs.existsSync(sideCarRooms) && fs.readdirSync(sideCarRooms).length === 0) {
-      fs.rmdirSync(sideCarRooms);
-    }
-    const sideCarAreaYamlToDelete = path.join(areaSideCarDir, 'area.yaml');
-    if (fs.existsSync(sideCarAreaYamlToDelete)) {
-      fs.rmSync(sideCarAreaYamlToDelete);
-    }
-    if (fs.existsSync(areaSideCarDir) && fs.readdirSync(areaSideCarDir).length === 0) {
-      fs.rmdirSync(areaSideCarDir);
-    }
+    removeSideCars(gameRoot, area, files);
   }
 
   console.log(`Synced ${written} room(s) for area '${area}' into ${packDir} (v${old} -> v${next}).`);

package/src/lib/file-sink.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { readYaml, writeYaml } = require('../util/yaml');
+const { resolvePackDirOrNull } = require('./pack-resolve');
+const { renderArea, removeSideCars, assertNamespaceMatch } = require('./render-core');
+const { synthesizeManifest } = require('./pack-manifest');
+const { buildTarball, EXCLUDE } = require('./tarball-builder');
+
+// Reuse tarball-builder's exclusion set (single source of truth) for the temp-dir copy filter.
+function isExcluded(srcPath) {
+  return EXCLUDE.has(path.basename(srcPath)) || srcPath.endsWith('.tgz');
+}
+
+// File sink: render into a temp build dir, tar -> <short>-<version>.tgz. It NEVER bumps -- it
+// captures an exact snapshot at the current manifest version (synthesized = 0.1.0; owned =
+// the pack's current version). A backup/handoff copy, never a claimed source of truth, so a
+// shared version string is safe (a .tgz install is a direct file install, not a registry
+// resolve). Async so the temp dir is cleaned only AFTER the tarball is fully written.
+async function fileSink(areaRef, options) {
+  const { cwd, gameRoot, namespace, area } = options;
+  const force = !!options.force;
+  const keepSidecars = !!options.keepSidecars;
+
+  const packDir = resolvePackDirOrNull(cwd, namespace, options.pack);
+  const tmpBuild = fs.mkdtempSync(path.join(os.tmpdir(), 'tapestry-harvest-'));
+  try {
+    if (packDir) {
+      const manifest = readYaml(path.join(packDir, 'pack.yaml')) || {};
+      assertNamespaceMatch(manifest, namespace, packDir);
+      // Complete-pack copy so the .tgz carries the whole pack (incl. module code), area folded in.
+      fs.cpSync(packDir, tmpBuild, { recursive: true, filter: (src) => !isExcluded(src) });
+    } else {
+      writeYaml(path.join(tmpBuild, 'pack.yaml'), synthesizeManifest(namespace, { name: options.name }));
+    }
+
+    const { files } = renderArea(tmpBuild, { gameRoot, area, force });
+
+    // Snapshot semantics: ship at the current manifest version, never bump.
+    const manifest = readYaml(path.join(tmpBuild, 'pack.yaml'));
+    const version = manifest.version;
+    const shortName = manifest.name.split('/')[1];
+    const outputPath = options.out
+      ? (path.isAbsolute(options.out) ? options.out : path.join(cwd, options.out))
+      : path.join(cwd, `${shortName}-${version}.tgz`);
+
+    await buildTarball(tmpBuild, outputPath);
+
+    if (!keepSidecars) {
+      removeSideCars(gameRoot, area, files);
+    }
+    console.log(`Harvested area '${area}' -> ${outputPath} (v${version}).`);
+    console.log('This .tgz is a portable, installable pack -- back it up, share it, or `tapestry install` it.');
+    return outputPath;
+  } finally {
+    fs.rmSync(tmpBuild, { recursive: true, force: true });
+  }
+}
+
+module.exports = { fileSink };

package/src/lib/pack-manifest.js

@@ -30,6 +30,43 @@ function ensureContentGlobs(packDir, globs = CONTENT_GLOBS) {
   return added;
 }
 
+// Reverse of PackNamespace: split the namespace on its FIRST hyphen -> @scope/package.
+function namespaceToName(namespace) {
+  const dash = namespace.indexOf('-');
+  if (dash < 1 || dash === namespace.length - 1) {
+    throw new Error(
+      `Cannot derive a pack name from namespace '${namespace}'. Pass --name <@scope/pack>.`);
+  }
+  const scope = namespace.slice(0, dash);
+  const pkg = namespace.slice(dash + 1);
+  return `@${scope}/${pkg}`;
+}
+
+function titleCase(s) {
+  return s.split(/[-_]/).filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+// Synthesize a strict-bootable world manifest for the no-pack hobbyist (exemplar B).
+// Content globs are added by renderArea's ensureContentGlobs after content lands.
+function synthesizeManifest(namespace, { name } = {}) {
+  const packName = name || namespaceToName(namespace);
+  const scope = packName.replace(/^@/, '').split('/')[0];
+  const pkgPart = packName.split('/')[1] || namespace;
+  return {
+    name: packName,
+    version: '0.1.0',
+    type: 'world',
+    display_name: titleCase(pkgPart),
+    description: `Harvested world pack for ${namespace}.`,
+    author: scope,
+    license: 'MIT',
+    engine: '>=0.1.0',
+    validation: 'strict',
+  };
+}
+
 // Bump the pack version (patch|minor|major). Returns { old, new }.
 function bumpVersion(packDir, level = 'patch') {
   const manifestPath = path.join(packDir, 'pack.yaml');
@@ -47,4 +84,4 @@ function bumpVersion(packDir, level = 'patch') {
   return { old, new: next };
 }
 
-module.exports = { ensureContentGlobs, bumpVersion, CONTENT_GLOBS };
+module.exports = { ensureContentGlobs, bumpVersion, namespaceToName, synthesizeManifest, CONTENT_GLOBS };

package/src/lib/pack-resolve.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const path = require('path');
+const { readYaml } = require('../util/yaml');
+const { readLinks } = require('./links');
+
+// "namespace:area-id" -> { namespace, area }. Throws on a malformed ref.
+function parseAreaRef(areaRef) {
+  const colon = (areaRef || '').indexOf(':');
+  if (colon < 1) {
+    throw new Error('Usage: <namespace:area-id> (e.g. legends-forgotten:village-green)');
+  }
+  return { namespace: areaRef.slice(0, colon), area: areaRef.slice(colon + 1) };
+}
+
+// "@legends/forgotten" -> "legends-forgotten" (mirrors engine PackLoader.PackNamespace).
+function packNamespace(name) {
+  if (name.indexOf('/') === -1) {
+    return name;
+  }
+  return name.replace(/^@/, '').split('/').join('-');
+}
+
+// All linked pack dirs whose manifest namespace matches `namespace`.
+function findPackMatches(cwd, namespace) {
+  const { links } = readLinks(cwd);
+  const matches = [];
+  for (const [name, dir] of Object.entries(links)) {
+    let derivedNs;
+    try {
+      const manifest = readYaml(path.join(dir, 'pack.yaml')) || {};
+      derivedNs = packNamespace(manifest.name || name);
+    } catch (e) {
+      derivedNs = packNamespace(name);
+    }
+    if (derivedNs === namespace) {
+      matches.push(dir);
+    }
+  }
+  return matches;
+}
+
+// Throwing resolution (git sink: a pack MUST exist).
+function detectPackDir(cwd, namespace, explicitPack) {
+  if (explicitPack) {
+    return path.isAbsolute(explicitPack) ? explicitPack : path.join(cwd, explicitPack);
+  }
+  const matches = findPackMatches(cwd, namespace);
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length === 0) {
+    throw new Error(`Could not auto-detect a pack for namespace '${namespace}'. Pass --pack <dir>.`);
+  }
+  throw new Error(`Multiple linked packs match namespace '${namespace}'. Pass --pack <dir>.`);
+}
+
+// Nullable resolution (file sink: a pack MAY be absent -- hobbyist case).
+function resolvePackDirOrNull(cwd, namespace, explicitPack) {
+  if (explicitPack) {
+    return path.isAbsolute(explicitPack) ? explicitPack : path.join(cwd, explicitPack);
+  }
+  const matches = findPackMatches(cwd, namespace);
+  return matches.length === 1 ? matches[0] : null;
+}
+
+module.exports = { parseAreaRef, packNamespace, findPackMatches, detectPackDir, resolvePackDirOrNull };

package/src/lib/render-core.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { readYaml, writeYaml } = require('../util/yaml');
+const { ensureContentGlobs } = require('./pack-manifest');
+const { packNamespace } = require('./pack-resolve');
+
+// 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.
+function renderArea(targetDir, { gameRoot, area, force = false }) {
+  const sideCarRooms = path.join(gameRoot, 'data', 'areas', area, 'rooms');
+  if (!fs.existsSync(sideCarRooms)) {
+    throw new Error(`No authored rooms found for area '${area}' at ${sideCarRooms}`);
+  }
+  const files = fs.readdirSync(sideCarRooms).filter((f) => f.endsWith('.yaml'));
+  if (files.length === 0) {
+    throw new Error(`No authored rooms found for area '${area}'`);
+  }
+
+  const targetRooms = path.join(targetDir, 'areas', area, 'rooms');
+  fs.mkdirSync(targetRooms, { recursive: true });
+
+  // area.yaml: copy the authored envelope through; else leave the pack's; else synthesize.
+  const sideCarAreaYaml = path.join(gameRoot, 'data', 'areas', area, 'area.yaml');
+  const targetAreaYaml = path.join(targetDir, 'areas', area, 'area.yaml');
+  if (fs.existsSync(sideCarAreaYaml)) {
+    writeYaml(targetAreaYaml, readYaml(sideCarAreaYaml));
+  } else if (!fs.existsSync(targetAreaYaml)) {
+    writeYaml(targetAreaYaml, {
+      area: { id: area, name: area, level_range: [1, 99], reset_interval: 300 },
+    });
+  }
+
+  let written = 0;
+  for (const file of files) {
+    const src = path.join(sideCarRooms, file);
+    const dest = path.join(targetRooms, 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);
+    written++;
+  }
+
+  ensureContentGlobs(targetDir);
+  reconcileDependencies(targetDir, area);
+
+  return { written, files };
+}
+
+// Designed-in seam (design section 6): scan harvested content for cross-pack references and
+// write a `dependencies` block into the target pack.yaml, hard-erroring on the unresolvable.
+// Rooms are self-contained (their only cross-pack edge is the runtime-only `link` seam, which
+// never bakes into the artifact), so this is a deliberate NO-OP until referential side-cars
+// (mobs/items/quests) exist. Wired now so the slice-5 dependency stage slots in, not bolts on.
+function reconcileDependencies(targetDir, area) {
+  return [];
+}
+
+// Move semantics: delete the game-root side-cars for an area once the content is durably
+// promoted. Idempotent; prunes the rooms/ and area dirs when they go empty.
+function removeSideCars(gameRoot, area, files) {
+  const sideCarRooms = path.join(gameRoot, 'data', 'areas', area, 'rooms');
+  const areaSideCarDir = path.join(gameRoot, 'data', 'areas', area);
+  for (const file of files) {
+    const p = path.join(sideCarRooms, file);
+    if (fs.existsSync(p)) {
+      fs.rmSync(p);
+    }
+  }
+  if (fs.existsSync(sideCarRooms) && fs.readdirSync(sideCarRooms).length === 0) {
+    fs.rmdirSync(sideCarRooms);
+  }
+  const areaYaml = path.join(areaSideCarDir, 'area.yaml');
+  if (fs.existsSync(areaYaml)) {
+    fs.rmSync(areaYaml);
+  }
+  if (fs.existsSync(areaSideCarDir) && fs.readdirSync(areaSideCarDir).length === 0) {
+    fs.rmdirSync(areaSideCarDir);
+  }
+}
+
+// Namespace guard: a sink may only fold an area into its OWN pack. Throws on mismatch.
+function assertNamespaceMatch(manifest, namespace, packDir) {
+  if (!manifest.name) {
+    throw new Error(`pack.yaml in ${packDir} has no 'name' field.`);
+  }
+  const destNamespace = packNamespace(manifest.name);
+  if (destNamespace !== namespace) {
+    throw new Error(
+      `Pack namespace '${destNamespace}' does not match area namespace '${namespace}'. ` +
+      'harvest only commits an area back into its own pack; not-owned content forks (a later slice).');
+  }
+}
+
+module.exports = { renderArea, reconcileDependencies, removeSideCars, assertNamespaceMatch };

package/src/lib/tarball-builder.js

@@ -32,4 +32,4 @@ function computeIntegrity(filePath) {
   return `sha256-${hash}`;
 }
 
-module.exports = { buildTarball, computeIntegrity };
+module.exports = { buildTarball, computeIntegrity, EXCLUDE };

package/src/lib/world-state.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { readYaml } = require('../util/yaml');
+const { resolvePackDirOrNull } = require('./pack-resolve');
+
+// The one state vocabulary (design section 7), spec'd here for the CLI view. The in-game
+// `areas` view shows engine provenance tags ([pack]/[authored]/[pack +edits]) plus a WIP
+// tag; both are views of these same on-disk facts. Strict boot stays the authority.
+const STATES = { CLEAN: 'Clean', EDITED: 'Edited', FORK: 'Fork', WIP: 'WIP' };
+const WIP_FLAG = 'wip';
+
+function areaIsWip(areaDir) {
+  const areaYaml = path.join(areaDir, 'area.yaml');
+  if (!fs.existsSync(areaYaml)) {
+    return false;
+  }
+  const env = readYaml(areaYaml) || {};
+  const flags = (env.area && env.area.flags) || [];
+  return Array.isArray(flags) && flags.includes(WIP_FLAG);
+}
+
+// Lighter mirror of in-game `areas`: classify each authored area from side-car facts alone.
+// Never queries the registry or resolves the reference graph.
+function computeAreaStates(cwd, gameRoot) {
+  const areasRoot = path.join(gameRoot, 'data', 'areas');
+  if (!fs.existsSync(areasRoot)) {
+    return [];
+  }
+  const rows = [];
+  for (const area of fs.readdirSync(areasRoot)) {
+    const areaDir = path.join(areasRoot, area);
+    if (!fs.statSync(areaDir).isDirectory()) {
+      continue;
+    }
+    const roomsDir = path.join(areaDir, 'rooms');
+    const roomFiles = fs.existsSync(roomsDir)
+      ? fs.readdirSync(roomsDir).filter((f) => f.endsWith('.yaml'))
+      : [];
+
+    // Namespace is carried in the side-car room ids (ns:key).
+    let namespace = null;
+    if (roomFiles.length) {
+      const first = readYaml(path.join(roomsDir, roomFiles[0])) || {};
+      if (typeof first.id === 'string' && first.id.includes(':')) {
+        namespace = first.id.split(':')[0];
+      }
+    }
+
+    const wip = areaIsWip(areaDir);
+    const packDir = namespace ? resolvePackDirOrNull(cwd, namespace, undefined) : null;
+    const owned = !!packDir;
+
+    let state;
+    if (wip) {
+      state = STATES.WIP;
+    } else if (roomFiles.length === 0) {
+      state = STATES.CLEAN;
+    } else if (!owned) {
+      // Namespace maps to no pack you own (official/foreign) -> a fork target (slice 3).
+      state = STATES.FORK;
+    } else {
+      const edited = roomFiles.some((f) => {
+        const packRoom = path.join(packDir, 'areas', area, 'rooms', f);
+        if (!fs.existsSync(packRoom)) {
+          return true; // new room not yet in the pack
+        }
+        return JSON.stringify(readYaml(packRoom)) !== JSON.stringify(readYaml(path.join(roomsDir, f)));
+      });
+      state = edited ? STATES.EDITED : STATES.CLEAN;
+    }
+
+    rows.push({ area, namespace, state, roomCount: roomFiles.length, wip });
+  }
+  return rows.sort((a, b) => a.area.localeCompare(b.area));
+}
+
+module.exports = { computeAreaStates, STATES, WIP_FLAG };