@tapestry-mud/cli 0.3.3 → 0.3.5

package/README.md

@@ -1,6 +1,6 @@
 # @tapestry-mud/cli
 
-CLI for the [Tapestry MUD engine](https://github.com/tapestry-mud/tapestry). Create, manage, and publish content packs.
+CLI for the [Tapestry MUD engine](https://github.com/tapestry-mud/tapestry). Create game projects, install content packs, manage the engine, and publish packs to the registry.
 
 ## Install
 
@@ -8,52 +8,152 @@ CLI for the [Tapestry MUD engine](https://github.com/tapestry-mud/tapestry). Cre
 npm install -g @tapestry-mud/cli
 ```
 
-## Commands
+## Quick Start
 
-### Pack Development
+Three commands from zero to a running game:
 
-| Command | Description |
-|---------|-------------|
-| `tapestry init` | Create a new pack project with scaffold |
-| `tapestry create-pack [name]` | Generate a pack from a template |
-| `tapestry validate` | Validate pack.yaml and content files |
-| `tapestry pack` | Bundle a pack into a tarball for publishing |
+```bash
+tapestry init
+tapestry install
+tapestry start
+```
+
+`tapestry init` scaffolds a project directory with a manifest, server config, and starter packs. `tapestry install` resolves dependencies from the registry and downloads them. `tapestry start` pulls the engine (if needed) and launches the server.
+
+Connect with `telnet localhost 4000`.
+
+**Requirements:** [Docker](https://www.docker.com/) must be installed and running. The default engine mode pulls a Docker image. Binary and source modes are also available (.NET runtime required for source mode -- coming soon).
 
-### Pack Management
+## Admin Account
+
+`tapestry init` generates a `server.yaml` with a seed admin block:
+
+```yaml
+admin:
+  handle: TODO    # your admin character name
+  password: changeme
+```
+
+Set your handle before starting the server. On first boot, the engine creates the admin account with the `admin` role. Log in and change your password immediately.
+
+## Project Structure
+
+After `tapestry init`, your project looks like this:
+
+```
+my-game/
+  tapestry.yaml     # project manifest (dependencies, engine config)
+  server.yaml       # engine config (port, admin seed, settings)
+  packs/            # installed packs (managed by tapestry install)
+  data/             # game data -- players, saves (persists across restarts)
+  .tapestry-engine/ # engine artifacts (docker images, binaries, source)
+  .gitignore        # excludes packs/, data/, .tapestry-engine/
+```
+
+## Commands
+
+### Game Project
 
 | Command | Description |
 |---------|-------------|
-| `tapestry install [pack]` | Install a pack from the registry |
+| `tapestry init` | Scaffold a new game project from the starter preset |
+| `tapestry install [pack]` | Install all dependencies, or add a specific pack |
 | `tapestry uninstall [pack]` | Remove an installed pack |
-| `tapestry update [pack]` | Update a pack to the latest version |
-| `tapestry list` | List installed packs |
-| `tapestry enable [pack]` | Enable a disabled pack |
-| `tapestry disable [pack]` | Disable a pack without removing it |
+| `tapestry update [pack]` | Update one or all packs to latest compatible versions |
+| `tapestry list` | List installed packs with version and status |
+| `tapestry enable [pack]` | Activate a disabled pack |
+| `tapestry disable [pack]` | Disable a pack without removing files |
 | `tapestry outdated` | Check for newer versions of installed packs |
-| `tapestry info [pack]` | Show pack metadata from the registry |
-| `tapestry search [query]` | Search the registry for packs |
 
 ### Engine
 
 | Command | Description |
 |---------|-------------|
-| `tapestry start` | Start the Tapestry server |
-| `tapestry stop` | Stop the Tapestry server |
-| `tapestry engine` | Show engine version and status |
+| `tapestry start` | Launch the engine (auto-pulls Docker image if needed) |
+| `tapestry stop` | Stop the running engine |
+| `tapestry engine install` | Explicitly pull/download the engine artifact |
+| `tapestry engine update` | Update the engine to the configured version |
+| `tapestry engine info` | Show engine version, mode, and image/path |
+| `tapestry engine versions` | List available engine channels from the registry |
 
-### Registry Account
+### Registry
 
 | Command | Description |
 |---------|-------------|
+| `tapestry search [query]` | Search the registry by keyword |
+| `tapestry info [pack]` | Show pack metadata from the registry |
 | `tapestry register` | Create a registry account |
-| `tapestry login` | Log in to the registry |
-| `tapestry publish` | Publish a pack to the registry |
-| `tapestry unpublish [pack]` | Remove a pack from the registry |
+| `tapestry login` | Authenticate with the registry |
 | `tapestry change-password` | Change your registry password |
 
+### Pack Authoring
+
+| Command | Description |
+|---------|-------------|
+| `tapestry create pack [name]` | Scaffold a new pack with annotated examples |
+| `tapestry validate` | Validate the pack manifest and content files |
+| `tapestry pack` | Build a tarball for local inspection |
+| `tapestry publish` | Build and upload the pack to the registry |
+| `tapestry unpublish [pack]` | Remove a pack from the registry |
+
+### Admin
+
+| Command | Description |
+|---------|-------------|
+| `tapestry dist-tag set [pack] [tag] [version]` | Set a dist-tag on a pack version |
+| `tapestry dist-tag list [pack]` | List dist-tags for a pack |
+| `tapestry preset set [name] [version] [channel] [packs]` | Update a registry preset |
+
+## Publishing a Pack
+
+### 1. Create an account
+
+```bash
+tapestry register
+```
+
+### 2. Scaffold and build your pack
+
+```bash
+tapestry create pack @yourscope/my-pack
+cd my-pack
+# edit areas, mobs, items, scripts...
+tapestry validate
+```
+
+### 3. Publish
+
+```bash
+tapestry login
+tapestry publish
+```
+
+The registry validates your manifest, bundles the content, and makes it available for `tapestry install`.
+
+### 4. Tag a stable release (admin)
+
+After verifying a published version works:
+
+```bash
+tapestry dist-tag set @yourscope/my-pack stable 0.1.0
+```
+
+Players using `tapestry init` with a preset that references your pack will resolve to the tagged version.
+
+### CI Publishing
+
+For automated pipelines, use token-based auth:
+
+```bash
+tapestry login --token $REGISTRY_CI_TOKEN
+tapestry publish
+```
+
+The CI token is a JWT issued by the registry bootstrap script. Store it as a secret in your CI environment.
+
 ## Registry
 
-Packs are published to [registry.tapestryengine.com](https://registry.tapestryengine.com).
+Browse published packs at [tapestryengine.com/packages.html](https://tapestryengine.com/packages.html).
 
 ## Development
 

package/bin/tapestry.js

@@ -20,10 +20,13 @@ const { info } = require('../src/commands/info');
 const { list } = require('../src/commands/list');
 const { outdated } = require('../src/commands/outdated');
 const { engineInstall, engineUpdate, engineInfo } = require('../src/commands/engine');
+const { engineVersions } = require('../src/commands/engine-versions');
 const { startCmd } = require('../src/commands/start');
 const { stopCmd } = require('../src/commands/stop');
 const { changePassword } = require('../src/commands/change-password');
 const { unpublish } = require('../src/commands/unpublish');
+const { distTagSet, distTagList } = require('../src/commands/dist-tag');
+const { presetSet } = require('../src/commands/preset');
 
 const program = new Command();
 
@@ -32,19 +35,84 @@ program
   .description('Tapestry Package Manager')
   .version(version);
 
+program.configureHelp({
+  formatHelp(cmd, helper) {
+    const groups = [
+      {
+        title: 'Pack Management',
+        commands: ['uninstall', 'update', 'list', 'enable', 'disable', 'outdated'],
+      },
+      {
+        title: 'Engine',
+        commands: ['engine'],
+      },
+      {
+        title: 'Registry',
+        commands: ['search', 'info'],
+      },
+      {
+        title: 'Account',
+        commands: ['register', 'login', 'change-password'],
+      },
+      {
+        title: 'Pack Authoring',
+        commands: ['create', 'validate', 'pack', 'publish', 'unpublish'],
+      },
+      {
+        title: 'Admin',
+        commands: ['dist-tag', 'preset'],
+      },
+    ];
+
+    const cmdMap = new Map();
+    for (const sub of cmd.commands) {
+      cmdMap.set(sub.name(), sub);
+    }
+
+    const pad = 28;
+    let out = `Usage: ${helper.commandUsage(cmd)}\n\n`;
+    out += 'Tapestry Package Manager\n\n';
+    out += 'Quick start:\n';
+    out += `  ${'init'.padEnd(pad)}Scaffold a new game project\n`;
+    out += `  ${'install'.padEnd(pad)}Install packs from the registry\n`;
+    out += `  ${'start'.padEnd(pad)}Launch the engine (auto-pulls if needed)\n`;
+    out += `  ${'stop'.padEnd(pad)}Stop the running engine\n`;
+    out += '  telnet localhost 4000\n\n';
+
+    for (const group of groups) {
+      out += `${group.title}:\n`;
+      for (const name of group.commands) {
+        const sub = cmdMap.get(name);
+        if (sub) {
+          const usage = sub.options.length ? `${name} [options]` : name;
+          out += `  ${usage.padEnd(pad)}${sub.description()}\n`;
+        }
+      }
+      out += '\n';
+    }
+
+    out += 'Options:\n';
+    for (const opt of helper.visibleOptions(cmd)) {
+      out += `  ${helper.optionTerm(opt).padEnd(pad)}${helper.optionDescription(opt)}\n`;
+    }
+
+    return out;
+  },
+});
+
 program
   .command('init')
   .description('Initialize a new Tapestry game project in the current directory')
-  .action(() => {
+  .action(async () => {
     try {
-      init();
+      await init();
     } catch (e) {
       console.error(`error: ${e.message}`);
       process.exit(1);
     }
   });
 
-const createCmd = program.command('create');
+const createCmd = program.command('create').description('Scaffold new content');
 
 createCmd
   .command('pack <name>')
@@ -58,6 +126,47 @@ createCmd
     }
   });
 
+const distTagCmd = program.command('dist-tag').description('Manage dist-tags for a registry package');
+
+distTagCmd
+  .command('set <pack> <tag> <version>')
+  .description('Set a dist-tag on a pack version (owner or admin only)')
+  .action(async (pack, tag, version) => {
+    try {
+      await distTagSet(pack, tag, version);
+    } catch (e) {
+      console.error(`error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+distTagCmd
+  .command('list <pack>')
+  .description('List all dist-tags for a pack')
+  .action(async (pack) => {
+    try {
+      await distTagList(pack);
+    } catch (e) {
+      console.error(`error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+const presetCmd = program.command('preset').description('Manage registry presets (admin only)');
+
+presetCmd
+  .command('set <name> <version> <engine-channel> <packs>')
+  .description('Update a preset with pinned pack versions (packs: JSON string)')
+  .action(async (name, version, engineChannel, packsJson) => {
+    try {
+      const packs = JSON.parse(packsJson);
+      await presetSet(name, version, engineChannel, packs);
+    } catch (e) {
+      console.error(`error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
 program
   .command('install [package]')
   .description('Install a package or all dependencies from tapestry.yaml')
@@ -121,9 +230,10 @@ program
 program
   .command('login')
   .description('Authenticate with the registry and store token in ~/.tapestryrc')
-  .action(async () => {
+  .option('--token <token>', 'Save a raw token directly (for CI use, skips interactive login)')
+  .action(async (options) => {
     try {
-      await login();
+      await login({}, { token: options.token });
     } catch (e) {
       console.error(`error: ${e.message}`);
       process.exit(1);
@@ -264,6 +374,18 @@ engineCmd
     }
   });
 
+engineCmd
+  .command('versions')
+  .description('List available engine channels from the registry')
+  .action(async () => {
+    try {
+      await engineVersions();
+    } catch (e) {
+      console.error(`error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
 program
   .command('start')
   .description('Launch the Tapestry engine')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapestry-mud/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "CLI for the Tapestry MUD engine",
   "bin": {
     "tapestry": "./bin/tapestry.js"

package/src/commands/dist-tag.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { requireToken } = require('../lib/auth');
+const { patchDistTag, listDistTags, DEFAULT_REGISTRY } = require('../lib/registry-client');
+
+async function distTagSet(packName, tag, version, { registryUrl = DEFAULT_REGISTRY } = {}) {
+  const token = requireToken();
+  await patchDistTag(packName, tag, version, token, registryUrl);
+  console.log(`  ${packName}  ${tag} -> ${version}`);
+  console.log('Done.');
+}
+
+async function distTagList(packName, { registryUrl = DEFAULT_REGISTRY } = {}) {
+  const tags = await listDistTags(packName, registryUrl);
+  const entries = Object.entries(tags);
+  if (entries.length === 0) {
+    console.log(`No tags set for ${packName}`);
+    return;
+  }
+  for (const [tag, version] of entries) {
+    console.log(`  ${tag}: ${version}`);
+  }
+}
+
+module.exports = { distTagSet, distTagList };

package/src/commands/engine-versions.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const fetch = require('node-fetch');
+const { DEFAULT_REGISTRY } = require('../lib/registry-client');
+
+async function engineVersions() {
+  const res = await fetch(`${DEFAULT_REGISTRY}/v1/engine-channels`);
+  if (!res.ok) {
+    throw new Error(`Registry error ${res.status}`);
+  }
+  const channels = await res.json();
+
+  if (channels.length === 0) {
+    console.log('No engine channels registered.');
+    return;
+  }
+
+  const COL = [10, 10, 22];
+  const pad = (s, w) => String(s).padEnd(w);
+
+  console.log([pad('Channel', COL[0]), pad('Version', COL[1]), pad('Updated', COL[2])].join('  '));
+  console.log(COL.map(w => '-'.repeat(w)).join('  '));
+
+  for (const ch of channels) {
+    const date = new Date(ch.updated_at).toLocaleString('en-US', {
+      year: 'numeric', month: 'numeric', day: 'numeric',
+      hour: '2-digit', minute: '2-digit',
+    });
+    console.log([pad(ch.channel, COL[0]), pad(ch.version, COL[1]), pad(date, COL[2])].join('  '));
+  }
+}
+
+module.exports = { engineVersions };

package/src/commands/init.js

@@ -2,8 +2,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const { fetchPreset, DEFAULT_REGISTRY } = require('../lib/registry-client');
 
-function buildManifest(name) {
+function buildManifest(name, deps) {
+  const depLines = Object.entries(deps).map(([pkg, range]) => `  '${pkg}': '${range}'`).join('\n');
   return [
     `name: ${name}`,
     `engine:`,
@@ -11,53 +13,59 @@ function buildManifest(name) {
     `  mode: docker`,
     `  image: ghcr.io/tapestry-mud/tapestry`,
     `dependencies:`,
-    `  '@tapestry/core': '^0.0.1'`,
-    `  # Starter races, classes, and tutorial area. Remove or replace with your own content pack.`,
-    `  '@tapestry/example-pack': '^0.0.1'`,
+    depLines,
+    `  # Add more packs here. Run: tapestry install @scope/pack-name`,
     `packs: []`,
     `tag_validation: strict`,
     ``,
+    `# Server port, admin seed account, and engine settings are in server.yaml`,
   ].join('\n');
 }
 
-function init(cwd) {
-  {
-    if (cwd === undefined) {
-      {
-        cwd = process.cwd();
-      }
-    }
-
-    const manifestPath = path.join(cwd, 'tapestry.yaml');
-    if (fs.existsSync(manifestPath)) {
-      {
-        throw new Error('tapestry.yaml already exists. Run tapestry install to install dependencies.');
-      }
-    }
-
-    const name = path.basename(cwd);
-    fs.writeFileSync(manifestPath, buildManifest(name));
-    fs.writeFileSync(path.join(cwd, 'server.yaml'), '# Tapestry server configuration\n# See https://tapestryengine.com/docs/config for full options\nport: 4000\n');
-    fs.mkdirSync(path.join(cwd, 'packs'), { recursive: true });
-    fs.writeFileSync(
-      path.join(cwd, '.gitignore'),
-      '# Installed packages (managed by tapestry install)\npacks/\n\n# Engine artifacts (managed by tapestry engine install)\n.tapestry-engine/\n'
-    );
-
-    console.log(`Initialized: ${name}`);
-    console.log('  tapestry.yaml  project manifest');
-    console.log('  server.yaml    engine config');
-    console.log('  packs/         installed packages');
-    console.log('  .gitignore     excludes packs/ and .tapestry-engine/ from git');
-
-    if (!fs.existsSync(path.join(cwd, '.git'))) {
-      {
-        console.log('\nHint: no git repo detected. Run: git init');
-      }
-    }
-
-    console.log('\nNext: run tapestry install, then tapestry engine install, then tapestry start');
+async function init(cwd, { registryUrl = DEFAULT_REGISTRY } = {}) {
+  if (cwd === undefined) {
+    cwd = process.cwd();
   }
+
+  const manifestPath = path.join(cwd, 'tapestry.yaml');
+  if (fs.existsSync(manifestPath)) {
+    throw new Error('tapestry.yaml already exists. Run tapestry install to install dependencies.');
+  }
+
+  let preset;
+  try {
+    preset = await fetchPreset('starter', registryUrl);
+  } catch (e) {
+    throw new Error(`Failed to fetch starter preset from registry: ${e.message}. Check your connection and try again.`);
+  }
+
+  console.log(`Initializing Tapestry Starter v${preset.version}`);
+
+  const deps = {};
+  for (const [pkg, ver] of Object.entries(preset.packs)) {
+    deps[pkg] = `^${ver}`;
+  }
+
+  const name = path.basename(cwd);
+  fs.writeFileSync(manifestPath, buildManifest(name, deps));
+  fs.writeFileSync(path.join(cwd, 'server.yaml'), '# Tapestry server configuration\n# See https://tapestryengine.com/docs/config for full options\nport: 4000\n\n# Admin account created on first boot (change password after login)\nadmin:\n  handle: TODO    # your admin character name\n  password: changeme\n');
+  fs.mkdirSync(path.join(cwd, 'packs'), { recursive: true });
+  fs.writeFileSync(
+    path.join(cwd, '.gitignore'),
+    '# Installed packages (managed by tapestry install)\npacks/\n\n# Engine artifacts (managed by tapestry engine install)\n.tapestry-engine/\n\n# Game data (players, saves)\ndata/\n'
+  );
+
+  console.log(`Initialized: ${name}`);
+  console.log('  tapestry.yaml  project manifest');
+  console.log('  server.yaml    engine config');
+  console.log('  packs/         installed packages');
+  console.log('  .gitignore     excludes packs/ and .tapestry-engine/ from git');
+
+  if (!fs.existsSync(path.join(cwd, '.git'))) {
+    console.log('\nHint: no git repo detected. Run: git init');
+  }
+
+  console.log('\nNext: run tapestry install, then tapestry engine install, then tapestry start');
 }
 
 module.exports = { init };

package/src/commands/install.js

@@ -9,6 +9,7 @@ const { readLock, writeLock } = require('../lib/lock-file');
 const { fetchTarball, DEFAULT_REGISTRY } = require('../lib/registry-client');
 const { verifyIntegrity, saveTarball, extractTarball } = require('../lib/tarball');
 const { addPackageToBoot } = require('../lib/boot');
+const { loadToken } = require('../lib/auth');
 
 function packInstallPath(cwd, packageName) {
   const parts = packageName.split('/');
@@ -28,7 +29,7 @@ function isLockCurrent(manifestDeps, lock) {
   return Object.keys(manifestDeps).every((name) => lockResolved[name]);
 }
 
-async function installResolved(cwd, resolved) {
+async function installResolved(cwd, resolved, token) {
   for (const [packageName, info] of Object.entries(resolved)) {
     const destDir = packInstallPath(cwd, packageName);
 
@@ -43,7 +44,7 @@ async function installResolved(cwd, resolved) {
     const tmpPath = path.join(os.tmpdir(), `tapestry-${safeId}-${info.version}.tgz`);
 
     try {
-      const buffer = await fetchTarball(info.tarball);
+      const buffer = await fetchTarball(info.tarball, token);
       verifyIntegrity(buffer, info.integrity);
       saveTarball(buffer, tmpPath);
       await extractTarball(tmpPath, destDir);
@@ -64,6 +65,7 @@ async function install(packageArg, { cwd = process.cwd(), registryUrl = DEFAULT_
     throw new Error('No tapestry.yaml found. Run `tapestry init` first.');
   }
 
+  const token = loadToken();
   const manifest = readYaml(manifestPath);
   let resolved;
 
@@ -74,7 +76,7 @@ async function install(packageArg, { cwd = process.cwd(), registryUrl = DEFAULT_
     manifest.dependencies[name] = tempRange;
 
     console.log('Resolving dependencies...');
-    resolved = await resolve(manifest.dependencies, registryUrl);
+    resolved = await resolve(manifest.dependencies, registryUrl, token);
 
     if (!rawRange) {
       manifest.dependencies[name] = `^${resolved[name].version}`;
@@ -88,11 +90,11 @@ async function install(packageArg, { cwd = process.cwd(), registryUrl = DEFAULT_
       resolved = lock.resolved;
     } else {
       console.log('Resolving dependencies...');
-      resolved = await resolve(manifest.dependencies || {}, registryUrl);
+      resolved = await resolve(manifest.dependencies || {}, registryUrl, token);
     }
   }
 
-  await installResolved(cwd, resolved);
+  await installResolved(cwd, resolved, token);
   writeLock(cwd, { lockfile_version: 1, resolved });
   console.log('Done.');
 }

package/src/commands/login.js

@@ -16,7 +16,12 @@ async function promptCredentials() {
   }
 }
 
-async function login({ email, password } = {}, { registryUrl = DEFAULT_REGISTRY } = {}) {
+async function login({ email, password } = {}, { registryUrl = DEFAULT_REGISTRY, token = null } = {}) {
+  if (token) {
+    saveToken(token);
+    console.log('Token saved.');
+    return;
+  }
   if (!email || !password) {
     ({ email, password } = await promptCredentials());
   }
@@ -29,8 +34,8 @@ async function login({ email, password } = {}, { registryUrl = DEFAULT_REGISTRY
 
   await throwIfError(res, 'Login failed');
 
-  const { token } = await res.json();
-  saveToken(token);
+  const { token: authToken } = await res.json();
+  saveToken(authToken);
   console.log('Logged in.');
 }
 

package/src/commands/preset.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const { requireToken } = require('../lib/auth');
+const { patchPreset, DEFAULT_REGISTRY } = require('../lib/registry-client');
+
+async function presetSet(name, version, engineChannel, packs, { registryUrl = DEFAULT_REGISTRY } = {}) {
+  const token = requireToken();
+  await patchPreset(name, { version, engine_channel: engineChannel, packs }, token, registryUrl);
+  console.log(`  Updated preset '${name}' to v${version}`);
+  console.log('Done.');
+}
+
+module.exports = { presetSet };

package/src/lib/engine-manager.js

@@ -5,6 +5,34 @@ const path = require('path');
 const { spawnSync, spawn } = require('child_process');
 const { readYaml } = require('../util/yaml');
 const { writePid, readPid, clearPid } = require('./process-tracker');
+const fetch = require('node-fetch');
+const { DEFAULT_REGISTRY } = require('./registry-client');
+
+const NAMED_CHANNELS = ['nightly', 'stable'];
+
+async function resolveDockerTag(config) {
+  if (!NAMED_CHANNELS.includes(config.version)) {
+    return config.version;
+  }
+  let res;
+  try {
+    res = await fetch(`${DEFAULT_REGISTRY}/v1/engine-channels/${config.version}`);
+  } catch {
+    console.warn('Could not reach registry to resolve channel, using version string directly.');
+    return config.version;
+  }
+  if (res.status === 404) {
+    throw new Error(
+      `Channel '${config.version}' not found in registry. Run \`tapestry engine versions\` to see available channels.`
+    );
+  }
+  if (!res.ok) {
+    console.warn(`Registry returned ${res.status} resolving channel, using version string directly.`);
+    return config.version;
+  }
+  const { docker_tag } = await res.json();
+  return docker_tag;
+}
 
 const ENGINE_REPO = 'https://github.com/tapestry-mud/tapestry.git';
 const DEFAULT_IMAGE = 'ghcr.io/tapestry-mud/tapestry';
@@ -30,8 +58,17 @@ function dockerPull(image, version) {
   console.log(`Engine image ready: ${image}:${version}`);
 }
 
-function dockerStart(projectName, image, version, packsDir, serverYamlPath) {
+function dockerEnsureImage(image, version) {
+  const check = spawnSync('docker', ['image', 'inspect', `${image}:${version}`], { stdio: 'ignore' });
+  if (check.status !== 0) {
+    dockerPull(image, version);
+  }
+}
+
+function dockerStart(projectName, image, version, packsDir, serverYamlPath, dataDir) {
   const containerName = `tapestry-${projectName}`;
+  dockerEnsureImage(image, version);
+  spawnSync('docker', ['rm', '-f', containerName], { stdio: 'ignore' });
   const result = spawnSync('docker', [
     'run', '--detach',
     '--name', containerName,
@@ -39,6 +76,7 @@ function dockerStart(projectName, image, version, packsDir, serverYamlPath) {
     '-p', '4001:4001',
     '-v', `${packsDir}:/app/packs`,
     '-v', `${serverYamlPath}:/app/server.yaml`,
+    '-v', `${dataDir}:/app/data`,
     `${image}:${version}`,
   ], { stdio: 'inherit' });
   if (result.status !== 0) {
@@ -233,7 +271,8 @@ function readEngineConfig(cwd) {
 async function installEngine(cwd) {
   const config = readEngineConfig(cwd);
   if (config.mode === 'docker') {
-    dockerPull(config.image, config.version);
+    const tag = await resolveDockerTag(config);
+    dockerPull(config.image, tag);
   } else if (config.mode === 'binary') {
     binaryInstall(config.version, config.installDir);
   } else {
@@ -244,7 +283,8 @@ async function installEngine(cwd) {
 async function updateEngine(cwd) {
   const config = readEngineConfig(cwd);
   if (config.mode === 'docker') {
-    dockerPull(config.image, config.version);
+    const tag = await resolveDockerTag(config);
+    dockerPull(config.image, tag);
   } else if (config.mode === 'binary') {
     binaryInstall(config.version, config.installDir);
   } else {
@@ -266,6 +306,7 @@ function getEngineInfo(cwd) {
 async function startEngine(cwd) {
   const config = readEngineConfig(cwd);
   const packsDir = path.resolve(cwd, 'packs');
+  const dataDir = path.resolve(cwd, 'data');
   const serverYamlPath = path.resolve(cwd, 'server.yaml');
   if (!fs.existsSync(packsDir)) {
     throw new Error('packs/ directory not found. Run tapestry install first.');
@@ -273,8 +314,10 @@ async function startEngine(cwd) {
   if (!fs.existsSync(serverYamlPath)) {
     throw new Error('server.yaml not found in the current directory.');
   }
+  fs.mkdirSync(dataDir, { recursive: true });
   if (config.mode === 'docker') {
-    dockerStart(config.projectName, config.image, config.version, packsDir, serverYamlPath);
+    const tag = await resolveDockerTag(config);
+    dockerStart(config.projectName, config.image, tag, packsDir, serverYamlPath, dataDir);
   } else if (config.mode === 'binary') {
     binaryStart(config.version, config.installDir, packsDir, serverYamlPath, cwd);
   } else {

package/src/lib/registry-client.js

@@ -28,10 +28,12 @@ async function throwIfError(res, context) {
   }
 }
 
-async function fetchPackageMetadata(name, registryUrl = DEFAULT_REGISTRY) {
+async function fetchPackageMetadata(name, registryUrl = DEFAULT_REGISTRY, token = null) {
   validatePackageName(name);
   const url = `${registryUrl}/v1/packages/${name}`;
-  const res = await fetch(url);
+  const headers = {};
+  if (token) { headers['Authorization'] = `Bearer ${token}`; }
+  const res = await fetch(url, { headers });
   if (!res.ok) {
     if (res.status === 404) {
       throw new Error(`Package ${name} not found in registry`);
@@ -46,8 +48,13 @@ async function fetchPackageMetadata(name, registryUrl = DEFAULT_REGISTRY) {
   }
 }
 
-async function fetchTarball(url) {
-  const res = await fetch(url);
+async function fetchTarball(url, token = null) {
+  const headers = {};
+  if (token) { headers['Authorization'] = `Bearer ${token}`; }
+  const res = await fetch(url, { headers });
+  if (res.status === 401) {
+    throw new Error('pack is private - run tapestry login first');
+  }
   if (!res.ok) {
     const body = await res.text();
     throw new Error(`Tarball download failed: ${res.status}: ${body}`);
@@ -55,4 +62,51 @@ async function fetchTarball(url) {
   return res.buffer();
 }
 
-module.exports = { fetchPackageMetadata, fetchTarball, throwIfError, DEFAULT_REGISTRY };
+async function fetchPreset(name, registryUrl = DEFAULT_REGISTRY) {
+  const url = `${registryUrl.replace(/\/$/, '')}/v1/presets/${name}`;
+  const res = await fetch(url);
+  await throwIfError(res, `Failed to fetch preset '${name}'`);
+  return res.json();
+}
+
+async function patchDistTag(packName, tag, version, token, registryUrl = DEFAULT_REGISTRY) {
+  validatePackageName(packName);
+  const url = `${registryUrl.replace(/\/$/, '')}/v1/packages/${packName}/dist-tags/${tag}`;
+  const res = await fetch(url, {
+    method: 'PATCH',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({ version }),
+  });
+  await throwIfError(res, `Failed to set dist-tag ${tag} on ${packName}`);
+  return res.json();
+}
+
+async function listDistTags(packName, registryUrl = DEFAULT_REGISTRY) {
+  validatePackageName(packName);
+  const url = `${registryUrl.replace(/\/$/, '')}/v1/packages/${packName}/dist-tags`;
+  const res = await fetch(url);
+  await throwIfError(res, `Failed to fetch dist-tags for ${packName}`);
+  return res.json();
+}
+
+async function patchPreset(name, payload, token, registryUrl = DEFAULT_REGISTRY) {
+  const url = `${registryUrl.replace(/\/$/, '')}/v1/admin/presets/${name}`;
+  const res = await fetch(url, {
+    method: 'PATCH',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(payload),
+  });
+  await throwIfError(res, `Failed to update preset '${name}'`);
+  return res.json();
+}
+
+module.exports = {
+  fetchPackageMetadata, fetchTarball, throwIfError, DEFAULT_REGISTRY,
+  fetchPreset, patchDistTag, listDistTags, patchPreset,
+};

package/src/lib/semver-resolver.js

@@ -3,7 +3,7 @@
 const semver = require('semver');
 const { fetchPackageMetadata } = require('./registry-client');
 
-async function resolve(dependencies, registryUrl) {
+async function resolve(dependencies, registryUrl, token = null) {
   if (!dependencies || Object.keys(dependencies).length === 0) {
     return {};
   }
@@ -34,13 +34,23 @@ async function resolve(dependencies, registryUrl) {
 
     resolvedBy[name] = { range, requiredBy };
 
-    const meta = await fetchPackageMetadata(name, baseUrl);
+    const meta = await fetchPackageMetadata(name, baseUrl, token);
+
+    let resolvedRange = range;
+    if (/^[a-z]+$/.test(range)) {
+      const distTags = meta.dist_tags || {};
+      if (!distTags[range]) {
+        throw new Error(`Tag '${range}' not found for ${name}. Available tags: ${Object.keys(distTags).join(', ') || 'none'}`);
+      }
+      resolvedRange = distTags[range];
+    }
+
     const versions = meta.versions.map((v) => v.version);
-    const best = semver.maxSatisfying(versions, range);
+    const best = semver.maxSatisfying(versions, resolvedRange);
 
     if (!best) {
       throw new Error(
-        `No version of ${name} satisfies ${range}. Available: ${versions.join(', ') || 'none'}`
+        `No version of ${name} satisfies ${resolvedRange}. Available: ${versions.join(', ') || 'none'}`
       );
     }
 

package/src/scaffold/templates.js

@@ -12,6 +12,9 @@ author:
   handle: "TODO: your-registry-handle"
 license: "MIT"
 
+# Packs default to public. Add \`private: true\` to restrict access to your
+# account and registry admins only.
+
 # Semver range: >=3.0.0 means any engine version at or above this.
 engine: ">=3.0.0"
 

package/src/schema/manifest.js

@@ -41,6 +41,7 @@ const PackageManifestSchema = z.object({
     properties: z.number().optional(),
     keywords: z.array(z.string()).optional(),
   }).optional(),
+  private: z.boolean().optional(),
 });
 
 const ProjectManifestSchema = z.object({