sindicate 0.11.0 → 0.13.0

package/tools/devPlugin.js

@@ -23,6 +23,10 @@
 //     perfSink: process.env.MY_PERF_SINK || '/tmp/mygame-perf.jsonl',
 //   })]
 import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const _toolsDir = path.dirname(fileURLToPath(import.meta.url));
 
 // Guard for the source-writing endpoints: only same-machine pages may write, and the
 // payload must look like the file it claims to be — an empty/garbage body used to be
@@ -205,6 +209,336 @@ function editorShotsPlugin({ shotsDir, mapsDir }) {
   };
 }
 
+// THE PACK IMPORTER (ENGINE_DESIGN §5c) — bring publisher packs (Synty et al.) into the
+// RUNNING GAME's repo. A .unitypackage is a gzip tar of GUID dirs, each holding `pathname`
+// (the original Assets/… path) and `asset` (the bytes) — the parse western's python
+// extractor proved, done here with the OS tar. Assets land in the GAME (public/assets/
+// packs/<name>/), never in Sindicate: the engine stays content-free and licenses stay
+// per-project. Animation FBXs route through accentimation-converter when it's present.
+export function packImporterPlugin({ stagingDir = '_staging', packsDir = 'public/assets/packs', converterPath = '../accentimation-converter' } = {}) {
+  // category rules from the 85-pack survey (135k paths): newer packs live under
+  // Assets/Synty/<Pack>/, older under Assets/<Pack>/Models/; Convex/Collision dirs hold
+  // collision meshes (not display models); /Animations/ FBXs are converter fodder;
+  // .prefab/.asset/.mat/.cs and friends are Unity-only noise.
+  const TEXTURE_RE = /\.(png|jpg|jpeg|tga)$/i;
+  const MODEL_RE = /\.(fbx|glb|gltf|obj)$/i;
+  const ANIM_HINT = /(^|\/)animations?\//i;
+  const COLLISION_RE = /(^|\/)(convex|collision|collisionconvex)\//i;
+  const isAnim = (p) => (ANIM_HINT.test(p) && /\.fbx$/i.test(p)) || /(^|\/)A_[^/]+\.fbx$/i.test(p);
+
+  function inventory(dir) {
+    const out = { models: [], textures: [], animations: [], collision: [], other: [] };
+    const walk = (d, rel = '') => {
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+        if (e.name.startsWith('_')) continue;   // working dirs (_anims) are not pack content
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) walk(path.join(d, e.name), r);
+        else if (isAnim(r)) out.animations.push(r);
+        else if (COLLISION_RE.test(r) && MODEL_RE.test(r)) out.collision.push(r);
+        else if (MODEL_RE.test(r)) out.models.push(r);
+        else if (TEXTURE_RE.test(r)) out.textures.push(r);
+        else out.other.push(r);
+      }
+    };
+    walk(dir);
+    return out;
+  }
+
+  return {
+    name: 'sindicate-pack-importer',
+    apply: 'serve',
+    configureServer(server) {
+      // upload: stream the .unitypackage to disk, tar-extract, resolve pathname map, stage
+      server.middlewares.use('/__pack/upload', (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        const name = (new URL(req.url, 'http://x').searchParams.get('name') || 'pack').replace(/\.unitypackage$/i, '').replace(/[^\w.-]+/g, '_');
+        const upDir = path.join(stagingDir, '_uploads');
+        fs.mkdirSync(upDir, { recursive: true });
+        const tmp = path.join(upDir, `${name}.unitypackage`);
+        const ws = fs.createWriteStream(tmp);
+        req.pipe(ws);
+        ws.on('finish', () => {
+          try {
+            const raw = path.join(stagingDir, '_raw', name);
+            fs.rmSync(raw, { recursive: true, force: true });
+            fs.mkdirSync(raw, { recursive: true });
+            execFileSync('tar', ['-xzf', tmp, '-C', raw], { stdio: 'pipe' });
+            const dest = path.join(stagingDir, name);
+            fs.rmSync(dest, { recursive: true, force: true });
+            let staged = 0;
+            for (const guid of fs.readdirSync(raw)) {
+              const pn = path.join(raw, guid, 'pathname');
+              const as = path.join(raw, guid, 'asset');
+              if (!fs.existsSync(pn) || !fs.existsSync(as)) continue;
+              const orig = fs.readFileSync(pn, 'utf8').split('\n')[0].trim();
+              if (!orig || orig.split('/').includes('..')) continue;
+              const to = path.join(dest, orig);
+              fs.mkdirSync(path.dirname(to), { recursive: true });
+              fs.renameSync(as, to);
+              staged++;
+            }
+            fs.rmSync(raw, { recursive: true, force: true });
+            fs.rmSync(tmp, { force: true });
+            sendJson(res, 200, { pack: name, staged, inventory: summarize(inventory(dest)) });
+          } catch (e) { sendJson(res, 500, { err: String(e).slice(0, 300) }); }
+        });
+        ws.on('error', (e) => sendJson(res, 500, { err: String(e) }));
+      });
+
+      const summarize = (inv) => ({ models: inv.models.length, textures: inv.textures.length, animations: inv.animations.length, collision: inv.collision.length, other: inv.other.length });
+      // THE CATALOG: registry.json (ships with the engine) + live status per entry —
+      // installed (node_modules/<name>/sindicate.json) and packaged (newest
+      // *.sindicatepackage in the repo dir, resolved against the Sites root = game's parent)
+      server.middlewares.use('/__pack/registry', (req, res) => {
+        try {
+          const reg = JSON.parse(fs.readFileSync(path.join(_toolsDir, 'registry.json'), 'utf8'));
+          const sites = path.resolve('..');
+          const out = reg.packages.map((p) => {
+            const manPath = path.join('node_modules', p.name, 'sindicate.json');
+            let installed = null;
+            if (fs.existsSync(manPath)) { try { installed = JSON.parse(fs.readFileSync(manPath, 'utf8')).version; } catch { installed = '?'; } }
+            const repoDir = path.join(sites, p.repo ?? '');
+            let packageFile = null;
+            if (p.repo && fs.existsSync(repoDir)) {
+              const c = fs.readdirSync(repoDir).filter((f) => f.endsWith('.sindicatepackage')).sort();
+              if (c.length) packageFile = path.join(repoDir, c[c.length - 1]);
+            }
+            return { ...p, installed, packageFile, repoExists: p.repo ? fs.existsSync(repoDir) : false };
+          });
+          sendJson(res, 200, { packages: out });
+        } catch (e) { sendJson(res, 500, { err: String(e) }); }
+      });
+
+      // install straight from the catalog: run the sindicate CLI server-side into THIS game
+      server.middlewares.use('/__pack/installAddon', async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        try {
+          const { file } = JSON.parse((await readBody(req)).toString());
+          if (!file || !String(file).endsWith('.sindicatepackage') || !fs.existsSync(file)) return sendJson(res, 400, { err: 'no such package file' });
+          const out = execFileSync('node', [path.join(_toolsDir, 'sindicate-cli.mjs'), 'install', file, '--game', '.'], { stdio: 'pipe', timeout: 300000 });
+          sendJson(res, 200, { ok: true, log: out.toString().slice(-400) });
+        } catch (e) { sendJson(res, 500, { err: String(e.stderr ?? e).slice(0, 300) }); }
+      });
+
+      // installed add-ons: every node_modules package that ships a sindicate.json
+      server.middlewares.use('/__pack/addons', (req, res) => {
+        try {
+          const nm = 'node_modules';
+          const addons = [];
+          if (fs.existsSync(nm)) for (const d of fs.readdirSync(nm)) {
+            if (d.startsWith('.')) continue;
+            const man = path.join(nm, d, 'sindicate.json');
+            if (!fs.existsSync(man)) continue;
+            try { addons.push(JSON.parse(fs.readFileSync(man, 'utf8'))); } catch { /* unreadable manifest */ }
+          }
+          sendJson(res, 200, { addons });
+        } catch (e) { sendJson(res, 500, { err: String(e) }); }
+      });
+
+      // staged packs + inventories
+      server.middlewares.use('/__pack/list', (req, res) => {
+        try {
+          const packs = fs.existsSync(stagingDir)
+            ? fs.readdirSync(stagingDir).filter((d) => !d.startsWith('_') && fs.statSync(path.join(stagingDir, d)).isDirectory())
+                .map((d) => ({ pack: d, inventory: summarize(inventory(path.join(stagingDir, d))) }))
+            : [];
+          const imported = fs.existsSync(packsDir)
+            ? fs.readdirSync(packsDir).filter((d) => fs.existsSync(path.join(packsDir, d, 'pack.json')))
+            : [];
+          sendJson(res, 200, { packs, imported });
+        } catch (e) { sendJson(res, 500, { err: String(e) }); }
+      });
+
+      // import: copy models/textures into the game pack dir; cook animations via the converter
+      server.middlewares.use('/__pack/import', async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        try {
+          const { pack, categories = ['models', 'textures', 'animations'] } = JSON.parse((await readBody(req)).toString());
+          const src = path.join(stagingDir, String(pack).replace(/[^\w.-]+/g, '_'));
+          if (!fs.existsSync(src)) return sendJson(res, 404, { err: 'no such staged pack' });
+          const inv = inventory(src);
+          const out = path.join(packsDir, pack);
+          const copied = { models: 0, textures: 0 };
+          const copy = (rel, sub) => {
+            const to = path.join(out, sub, path.basename(rel));
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.copyFileSync(path.join(src, rel), to);
+          };
+          if (categories.includes('models')) for (const r of inv.models) { copy(r, 'models'); copied.models++; }
+          if (categories.includes('textures')) for (const r of inv.textures) { copy(r, 'textures'); copied.textures++; }
+          let clips = null;
+          if (categories.includes('animations') && inv.animations.length) {
+            const conv = path.resolve(converterPath, 'bin/accentimation.js');
+            if (fs.existsSync(conv)) {
+              const animDir = path.join(src, '_anims');
+              fs.rmSync(animDir, { recursive: true, force: true });
+              fs.mkdirSync(animDir, { recursive: true });
+              for (const r of inv.animations) fs.copyFileSync(path.join(src, r), path.join(animDir, path.basename(r)));
+              const clipsOut = path.join(out, 'clips');
+              try {
+                execFileSync('node', [conv, 'convert', animDir, '--out', clipsOut], { stdio: 'pipe', timeout: 300000 });
+                clips = fs.readdirSync(clipsOut).filter((f) => f.endsWith('.json')).length;
+              } catch (e) { clips = `converter failed: ${String(e.stderr ?? e).slice(0, 200)}`; }
+            } else clips = `converter not found at ${conv} — animations staged, not cooked`;
+          }
+          const manifest = { name: pack, importedAt: new Date().toISOString(), counts: { ...copied, clips }, source: 'unitypackage' };
+          fs.mkdirSync(out, { recursive: true });
+          fs.writeFileSync(path.join(out, 'pack.json'), JSON.stringify(manifest, null, 2));
+          sendJson(res, 200, { ok: true, pack, copied, clips, dest: out });
+        } catch (e) { sendJson(res, 500, { err: String(e).slice(0, 300) }); }
+      });
+    },
+  };
+}
+
+// THE ENGINE DEV GUI (/__sindicate/) — served by the dev server, talks to the RUNNING
+// game through the game bus. v1: live tunables (core/tune.js groups render as sliders;
+// edits apply in the game the same frame). Panels for add-ons/packs mount here next.
+export function guiPlugin() {
+  const PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>Sindicate</title><style>
+    body{margin:0;font:14px/1.5 -apple-system,sans-serif;background:#14141f;color:#e8e2d0;padding:28px}
+    h1{font-size:18px;letter-spacing:0.14em;color:#e8c66a;margin:0 0 4px} .sub{color:#8d8875;font-size:12px;margin-bottom:22px}
+    .grp{background:#1c1c2b;border:1px solid #2c2c40;border-radius:10px;padding:16px 18px;margin-bottom:14px;max-width:520px}
+    .grp h2{font-size:13px;letter-spacing:0.1em;text-transform:uppercase;color:#e8c66a;margin:0 0 10px}
+    .row{display:grid;grid-template-columns:130px 1fr 64px;gap:12px;align-items:center;margin:7px 0}
+    .row label{color:#b8b09a;font-size:12px} .row output{text-align:right;font-variant-numeric:tabular-nums;color:#f5ead0}
+    input[type=range]{width:100%;accent-color:#e8c66a}
+    .file{color:#6d6858;font-size:11px;margin-top:8px} .status{color:#8d8875;font-size:12px;margin-top:18px}
+  </style></head><body>
+  <h1>SINDICATE</h1><div class="sub">dev panel — tunables apply LIVE in the running game</div>
+  <div id="groups"></div><div class="status" id="status">connecting to the game bus…</div>
+  <div class="grp" style="margin-top:26px"><h2>Packages</h2>
+    <div style="font-size:12px;color:#8d8875;margin-bottom:8px">The Sindicate catalog — install into THIS game with one click (or: sindicate install &lt;file&gt; --game .)</div>
+    <div id="ad-list" style="font-size:12px;color:#b8b09a"></div>
+    <div id="ad-status" style="font-size:12px;color:#8d8875;margin-top:6px"></div>
+  </div>
+  <script>
+  async function adRefresh() {
+    try {
+      const j = await fetch('/__pack/registry').then((r) => r.json());
+      const el = document.getElementById('ad-list'); el.innerHTML = '';
+      for (const p of j.packages ?? []) {
+        const row = document.createElement('div');
+        row.style.cssText = 'display:flex;align-items:flex-start;gap:10px;margin:8px 0';
+        const status = p.installed ? '<span style="color:#7dc24a">installed v' + p.installed + '</span>'
+          : p.packageFile ? '<span style="color:#e8c66a">available</span>'
+          : '<span style="color:#6d6858">' + (p.note ?? 'not packaged') + '</span>';
+        row.innerHTML = '<div style="flex:1"><span style="color:#f5ead0">' + p.name + '</span> <span style="color:#6d6858">· ' + p.type + '</span> ' + status
+          + '<br><span style="color:#8d8875">' + (p.description ?? '') + '</span></div>';
+        if (!p.installed && p.packageFile) {
+          const btn = document.createElement('button');
+          btn.textContent = 'Install';
+          btn.style.cssText = 'padding:3px 12px;border:1px solid #3a3a52;border-radius:5px;background:#22223a;color:#e8c66a;cursor:pointer;font-size:12px;flex:none';
+          btn.onclick = async () => {
+            btn.disabled = true;
+            document.getElementById('ad-status').textContent = 'installing ' + p.name + '…';
+            const r = await fetch('/__pack/installAddon', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ file: p.packageFile }) }).then((x) => x.json());
+            document.getElementById('ad-status').textContent = r.ok ? 'installed ' + p.name + ' — restart the dev server to use it' : 'failed: ' + (r.err ?? '?');
+            adRefresh();
+          };
+          row.appendChild(btn);
+        }
+        el.appendChild(row);
+      }
+    } catch (e) { document.getElementById('ad-list').textContent = 'unreachable: ' + e.message; }
+  }
+  adRefresh();
+  </script>
+  <div class="grp" style="margin-top:14px"><h2>Import Packs</h2>
+    <div style="font-size:12px;color:#8d8875;margin-bottom:10px">Drop or choose a .unitypackage — assets land in THIS game's repo (public/assets/packs/). Animations cook through accentimation-converter.</div>
+    <input type="file" id="pk-file" accept=".unitypackage" style="color:#b8b09a;font-size:12px">
+    <div id="pk-status" style="font-size:12px;color:#8d8875;margin-top:8px"></div>
+    <div id="pk-list" style="margin-top:10px"></div>
+  </div>
+  <script>
+  const pkStatus = (m) => { document.getElementById('pk-status').textContent = m; };
+  async function pkRefresh() {
+    try {
+      const j = await fetch('/__pack/list').then((r) => r.json());
+      const el = document.getElementById('pk-list'); el.innerHTML = '';
+      for (const p of j.packs ?? []) {
+        const row = document.createElement('div');
+        row.style.cssText = 'display:flex;align-items:center;gap:10px;margin:6px 0;font-size:12px;color:#b8b09a';
+        const inv = p.inventory;
+        const done = (j.imported ?? []).includes(p.pack);
+        row.innerHTML = '<span style="color:#f5ead0">' + p.pack + '</span><span>' + inv.models + ' models · ' + inv.textures + ' tex · ' + inv.animations + ' anims</span>' + (done ? '<span style="color:#7dc24a">imported</span>' : '');
+        const btn = document.createElement('button');
+        btn.textContent = done ? 'Re-import' : 'Import';
+        btn.style.cssText = 'padding:3px 12px;border:1px solid #3a3a52;border-radius:5px;background:#22223a;color:#e8c66a;cursor:pointer;font-size:12px';
+        btn.onclick = async () => {
+          btn.disabled = true; pkStatus('importing ' + p.pack + '…');
+          const r = await fetch('/__pack/import', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ pack: p.pack }) }).then((x) => x.json());
+          pkStatus(r.ok ? 'imported ' + p.pack + ': ' + r.copied.models + ' models, ' + r.copied.textures + ' textures' + (r.clips != null ? ', clips: ' + r.clips : '') : 'failed: ' + (r.err ?? '?'));
+          btn.disabled = false; pkRefresh();
+        };
+        row.appendChild(btn); el.appendChild(row);
+      }
+      if (!(j.packs ?? []).length) el.innerHTML = '<div style="font-size:12px;color:#6d6858">nothing staged yet</div>';
+    } catch (e) { pkStatus('importer unreachable: ' + e.message); }
+  }
+  document.getElementById('pk-file').onchange = async (ev) => {
+    const f = ev.target.files[0]; if (!f) return;
+    pkStatus('uploading ' + f.name + ' (' + Math.round(f.size / 1048576) + 'MB)…');
+    try {
+      const j = await fetch('/__pack/upload?name=' + encodeURIComponent(f.name), { method: 'POST', body: f }).then((r) => r.json());
+      pkStatus(j.err ? 'failed: ' + j.err : 'staged ' + j.pack + ' — ' + j.staged + ' files');
+      pkRefresh();
+    } catch (e) { pkStatus('upload failed: ' + e.message); }
+  };
+  pkRefresh();
+  </script>
+  <script>
+  const cmd = (js) => fetch('/__game/cmd', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ js }) }).then((r) => r.json());
+  const take = async (id) => { for (let i = 0; i < 40; i++) { const r = await fetch('/__game/take?id=' + id).then((x) => x.json()); if (!r.pending) return r; await new Promise((res) => setTimeout(res, 250)); } return { err: 'timeout' }; };
+  const bus = async (js) => { const { id, err } = await cmd(js); if (err) throw new Error(err); const r = await take(id); if (!r.ok) throw new Error(r.err ?? 'bus error'); return r.value; };
+  let sig = '', dragging = false;
+  const rows = new Map();
+  addEventListener('pointerup', () => { dragging = false; });
+  async function refresh() {
+    try {
+      const r = await bus('return { who: location.pathname + location.search, title: document.title, groups: window.__sindTune ? window.__sindTune.list() : [] }');
+      const groups = r.groups, tab = r.title + ' — ' + r.who;
+      const s = JSON.stringify(groups.map((g) => [g.name, Object.keys(g.spec)]));
+      document.getElementById('status').textContent = (groups.length ? 'live — ' + groups.length + ' group(s)' : 'connected — no tunables registered') + ' · answering tab: ' + tab;
+      if (s === sig) {
+        if (!dragging) for (const g of groups) for (const [k, v] of Object.entries(g.spec)) {
+          const row = rows.get(g.name + '.' + k);
+          if (row && String(row.inp.value) !== String(v.value)) { row.inp.value = v.value; row.out.textContent = v.value; }
+        }
+        return;
+      }
+      sig = s; rows.clear();
+      const root = document.getElementById('groups'); root.innerHTML = '';
+      for (const g of groups) {
+        const div = document.createElement('div'); div.className = 'grp';
+        div.innerHTML = '<h2>' + g.name + '</h2>';
+        for (const [k, v] of Object.entries(g.spec)) {
+          const row = document.createElement('div'); row.className = 'row';
+          row.innerHTML = '<label>' + k + '</label><input type="range" min="' + (v.min ?? 0) + '" max="' + (v.max ?? 1) + '" step="' + (v.step ?? 0.01) + '" value="' + v.value + '"><output>' + v.value + '</output>';
+          const inp = row.querySelector('input'), out = row.querySelector('output');
+          rows.set(g.name + '.' + k, { inp, out });
+          inp.onpointerdown = () => { dragging = true; };
+          inp.oninput = () => { out.textContent = inp.value; bus('return window.__sindTune.set(' + JSON.stringify(g.name) + ',' + JSON.stringify(k) + ',' + inp.value + ')').catch(() => {}); };
+          div.appendChild(row);
+        }
+        if (g.file) { const f = document.createElement('div'); f.className = 'file'; f.textContent = 'persists to: ' + g.file; div.appendChild(f); }
+        root.appendChild(div);
+      }
+    } catch (e) { document.getElementById('status').textContent = 'game bus unreachable — is a game tab open? (' + e.message + ')'; }
+  }
+  refresh(); setInterval(refresh, 3000);
+  </script></body></html>`;
+  return {
+    name: 'sindicate-gui',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use('/__sindicate', (req, res) => {
+        res.setHeader('content-type', 'text/html'); res.end(PAGE);
+      });
+    },
+  };
+}
+
 export function sindicateDevTools({
   sourceWrites = [],
   assetLists = [],
@@ -225,6 +559,8 @@ export function sindicateDevTools({
     ...assetLists.map(assetListPlugin),
     ...stores.map(binStorePlugin),
     perfSinkPlugin(perfSink),
+    guiPlugin(),
+    packImporterPlugin(),
     busPlugin({ name: 'game', prefix: '/__game', originGuard: true }),
     busPlugin({ name: 'editor', prefix: '/__editor' }),
     editorShotsPlugin({ shotsDir: editorShotsDir, mapsDir }),

package/tools/registry.json

@@ -0,0 +1,45 @@
+{
+  "//": "The Sindicate package catalog — what exists in the ecosystem and where it lives on this machine (repo paths relative to the Sites root, i.e. the games' parent dir). The dev GUI reads this via /__pack/registry and installs straight from it.",
+  "packages": [
+    {
+      "name": "rayhit-three",
+      "type": "addon",
+      "description": "Runtime mesh fracturing & physics destruction — Voronoi shattering, demolition, bombs, structural collapse.",
+      "repo": "rayhit-three"
+    },
+    {
+      "name": "weather-threejs",
+      "type": "addon",
+      "description": "Stylized weather, atmosphere & time-of-day — sky, sun/moon/stars, clouds, fog, rain & snow, forecast system.",
+      "repo": "weather-threejs"
+    },
+    {
+      "name": "accentimations",
+      "type": "clips",
+      "description": "The animation pack: 259 cooked clips + manifest. Dev flow consumes it via file: + registerClipPack; a packaged release is pending.",
+      "repo": "Accentimations",
+      "note": "consumed via file: dependency in dev — not yet packaged"
+    },
+    {
+      "name": "kitforge",
+      "type": "addon",
+      "description": "Kit-piece cataloguer + render-to-PNG thumbnails (feeds the importer's future thumbnail grid).",
+      "repo": "kitforge",
+      "note": "not yet manifested"
+    },
+    {
+      "name": "fft-water",
+      "type": "addon",
+      "description": "FFT ocean/water surface (from transport-tycoon-remake) — extraction pending.",
+      "repo": "transport-tycoon-remake",
+      "note": "planned — extraction not started"
+    },
+    {
+      "name": "glodify",
+      "type": "service",
+      "description": "LOD baker (CLI/REST service) — games consume its output files; never installed as a package.",
+      "repo": "glodify",
+      "note": "service, not installable"
+    }
+  ]
+}

package/tools/sindicate-cli.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// THE .sindicatepackage CLI (ENGINE_DESIGN §4c) — one distributable wrapper for everything
+// installable. Under the hood: an npm-compatible tarball (package/ prefix) with a
+// sindicate.json manifest at the package root, so code add-ons install with plain npm and
+// the engine tooling can read what a thing IS before installing it.
+//
+//   sindicate pack <dir>                  → <name>-<version>.sindicatepackage (from
+//                                           package.json + sindicate.json in <dir>)
+//   sindicate inspect <file>              → print the manifest
+//   sindicate install <file> [--game .]   → type 'addon'  = npm install the tarball into
+//                                           the game (dep + node_modules, bridge on boot)
+//                                           type 'assets'|'clips' = extract package/assets
+//                                           into <game>/public/assets/packs/<name>/
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const [, , cmd, target, ...rest] = process.argv;
+const opt = (name, dflt) => { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : dflt; };
+const die = (m) => { console.error(`sindicate: ${m}`); process.exit(1); };
+
+function readManifestFromTarball(file) {
+  try {
+    const out = execFileSync('tar', ['-xzOf', file, 'package/sindicate.json'], { stdio: ['ignore', 'pipe', 'pipe'] });
+    return JSON.parse(out.toString());
+  } catch (e) { die(`${path.basename(file)}: no readable package/sindicate.json — not a .sindicatepackage (${String(e).slice(0, 120)})`); }
+}
+
+if (cmd === 'pack') {
+  const dir = path.resolve(target ?? '.');
+  const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  const sinPath = path.join(dir, 'sindicate.json');
+  if (!fs.existsSync(sinPath)) die(`${dir}/sindicate.json missing — add { name, version, type, description } first`);
+  const sin = JSON.parse(fs.readFileSync(sinPath, 'utf8'));
+  // npm pack builds the canonical npm tarball (honours "files", writes package/ prefix);
+  // sindicate.json rides along because it is listed in "files" (enforce that here).
+  const files = pkg.files ?? [];
+  if (files.length && !files.includes('sindicate.json')) die(`package.json "files" must include "sindicate.json" so the manifest ships`);
+  const out = execFileSync('npm', ['pack', '--silent'], { cwd: dir }).toString().trim().split('\n').pop();
+  const dest = path.join(dir, `${(sin.name ?? pkg.name).replace('/', '-')}-${pkg.version}.sindicatepackage`);
+  fs.renameSync(path.join(dir, out), dest);
+  console.log(`packed ${dest} (type: ${sin.type})`);
+} else if (cmd === 'inspect') {
+  console.log(JSON.stringify(readManifestFromTarball(path.resolve(target)), null, 2));
+} else if (cmd === 'install') {
+  const file = path.resolve(target);
+  const game = path.resolve(opt('--game', '.'));
+  if (!fs.existsSync(path.join(game, 'package.json'))) die(`${game} is not a game (no package.json) — pass --game <dir>`);
+  const sin = readManifestFromTarball(file);
+  if (sin.engineRange) console.log(`engine range: ${sin.engineRange} (checked at boot by the bridge)`);
+  if (sin.type === 'addon') {
+    // npm only recognises tarballs by extension (.sindicatepackage reads as a folder path
+    // → ENOTDIR), so a .tgz TWIN sits beside the original — and STAYS: npm records the
+    // dep as file:<path-to-tgz>, so deleting it would break the game's next npm install
+    const tgz = file.replace(/\.sindicatepackage$/, '.tgz');
+    fs.copyFileSync(file, tgz);
+    execFileSync('npm', ['install', tgz], { cwd: game, stdio: 'inherit' });
+    console.log(`installed addon '${sin.name}' into ${path.basename(game)} — import it from game code${sin.bridge ? `; bridge: ${sin.bridge}` : ''}`);
+  } else if (sin.type === 'assets' || sin.type === 'clips') {
+    const dest = path.join(game, 'public/assets/packs', sin.name);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.mkdirSync(dest, { recursive: true });
+    // extract only the package/assets tree, stripping the two leading path parts
+    execFileSync('tar', ['-xzf', file, '-C', dest, '--strip-components', '2', 'package/assets'], { stdio: 'pipe' });
+    fs.writeFileSync(path.join(dest, 'pack.json'), JSON.stringify({ ...sin, installedAt: new Date().toISOString(), source: 'sindicatepackage' }, null, 2));
+    console.log(`installed ${sin.type} pack '${sin.name}' → ${dest}`);
+  } else die(`unknown type '${sin.type}' (addon | assets | clips | pack-profile)`);
+} else {
+  console.log('usage: sindicate pack <dir> | inspect <file> | install <file> [--game <dir>]');
+  process.exit(cmd ? 1 : 0);
+}