@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/model-licences.js

@@ -0,0 +1,305 @@
+/**
+ * Model and LoRA licence catalog and verification helpers (G4, §5.2–§5.3).
+ *
+ * Cleared SPDX licences for CC-BY-4.0 dataset/LoRA release:
+ *   Apache-2.0, MIT, BSD-2-Clause, BSD-3-Clause, CC0-1.0, CC-BY-4.0
+ *
+ * Excluded / held models (FLUX.1-dev, FLUX.2-dev, FLUX.2-klein-9B, SD 3.5,
+ * Qwen-Image 2.1, community SDXL merges, and the held Portlight `plsvessel`
+ * LoRA trained on 336 Nano Banana-derived pairs) are explicitly flagged
+ * `cc_by_4_eligible: false` and `excluded: true`.
+ */
+
+import { inputError } from './errors.js';
+
+export const CLEARED_SPDX_IDS = Object.freeze([
+  'Apache-2.0',
+  'MIT',
+  'BSD-2-Clause',
+  'BSD-3-Clause',
+  'CC0-1.0',
+  'CC-BY-4.0',
+]);
+
+export const QUARANTINED_PATTERNS = Object.freeze([
+  /plsvessel/i,
+  /nano[_-\s]?banana/i,
+  /held[_-\s]?portlight/i,
+]);
+
+const KNOWN_CATALOG = Object.freeze([
+  // Quarantined / held Portlight distillation artifacts (§5.3, §8.1)
+  {
+    pattern: /^(?:plsvessel|.*nano[_-\s]?banana.*)/i,
+    spdx_id: 'PROPRIETARY-HELD-DISTILL',
+    url: 'https://ai.google.dev/gemini-api/terms',
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: false,
+    excluded: true,
+    quarantined: true,
+    status: 'held',
+    reason: 'Held Portlight LoRA trained on 336 Nano Banana-derived pairs; not eligible for CC-BY-4.0 release or training',
+  },
+  // Excluded Qwen-Image 2.1 proprietary API (§5.3)
+  {
+    pattern: /^qwen[_-]image[_-]2\.1/i,
+    spdx_id: 'PROPRIETARY-API',
+    url: 'https://www.alibabacloud.com/help/en/model-studio/',
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: false,
+    excluded: true,
+    status: 'excluded',
+    reason: 'Proprietary API-only model; no open weights',
+  },
+  // Cleared Qwen-Image 20B and VAE (§5.2)
+  {
+    pattern: /^qwen[_-]image/i,
+    spdx_id: 'Apache-2.0',
+    url: 'https://github.com/QwenLM/Qwen-Image/blob/main/LICENSE',
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: true,
+    excluded: false,
+    status: 'cleared',
+  },
+  // Cleared Qwen 2.5 VL 7B text encoder (§5.2)
+  {
+    pattern: /^qwen[_-]?2\.5[_-]vl[_-]7b/i,
+    spdx_id: 'Apache-2.0',
+    url: 'https://github.com/QwenLM/Qwen2.5-VL/blob/main/LICENSE',
+    verified_at: '2026-10-28',
+    cc_by_4_eligible: true,
+    excluded: false,
+    status: 'cleared',
+  },
+  // Cleared FLUX.2 [klein] 4B and FLUX.2 VAE (§5.2)
+  {
+    pattern: /^(?:flux[_-]?2[_-]klein[_-](?:base[_-])?4b|flux2[_-]vae|ae\.safetensors)/i,
+    spdx_id: 'Apache-2.0',
+    url: 'https://huggingface.co/black-forest-labs/FLUX.2-klein-4B/blob/main/LICENSE.md',
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: true,
+    excluded: false,
+    status: 'cleared',
+  },
+  // Cleared Muse Glimmer 30B / Qwen3-VL-30B-A3B-Instruct / Qwen2.5-VL-32B (§5.2)
+  {
+    pattern: /^qwen(?:3[_-]vl[_-]30b[_-]a3b|2\.5[_-]vl[_-]32b|2\.5[:_-]14b|3[:_-]14b)/i,
+    spdx_id: 'Apache-2.0',
+    url: 'https://huggingface.co/Qwen/Qwen3-VL-30B-A3B-Instruct/blob/main/LICENSE',
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: true,
+    excluded: false,
+    status: 'cleared',
+  },
+  // Excluded FLUX.1 [dev] (§5.3)
+  {
+    pattern: /^flux[_-]?1[_-]dev/i,
+    spdx_id: 'FLUX-1-DEV-NC',
+    url: 'https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/LICENSE.md',
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: false,
+    excluded: true,
+    status: 'excluded',
+    reason: 'FLUX.1 [dev] Non-Commercial License restricts model and derivatives',
+  },
+  // Excluded FLUX.2 [dev] and FLUX.2 [klein] 9B (§5.3)
+  {
+    pattern: /^flux[_-]?2[_-](?:dev|klein[_-](?:base[_-])?9b)/i,
+    spdx_id: 'FLUX-2-NC',
+    url: 'https://huggingface.co/black-forest-labs/FLUX.2-dev/blob/main/LICENSE.md',
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: false,
+    excluded: true,
+    status: 'excluded',
+    reason: 'FLUX.2 Non-Commercial License',
+  },
+  // Excluded Stable Diffusion 3.5 family (§5.3)
+  {
+    pattern: /^(?:sd3\.?5|stable[_-]diffusion[_-]3\.?5)/i,
+    spdx_id: 'STABILITY-COMMUNITY',
+    url: 'https://huggingface.co/stabilityai/stable-diffusion-3.5-large/blob/main/LICENSE.md',
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: false,
+    excluded: true,
+    status: 'excluded',
+    reason: 'Stability AI Community License revenue cap and derivative terms',
+  },
+  // Excluded community SDXL merges (§5.3)
+  {
+    pattern: /^(?:dreamshaper|juggernaut|pony|illustrious|animagine)/i,
+    spdx_id: 'UNCLEARED-COMMUNITY-MERGE',
+    url: null,
+    verified_at: '2026-10-25',
+    cc_by_4_eligible: false,
+    excluded: true,
+    status: 'excluded',
+    reason: 'Community SDXL merge without audited upstream weight lineage',
+  },
+]);
+
+/**
+ * Check whether a string references a quarantined/held artifact (`plsvessel`, `nano-banana`).
+ */
+export function isQuarantinedName(value) {
+  if (!value || typeof value !== 'string') return false;
+  return QUARANTINED_PATTERNS.some((re) => re.test(value));
+}
+
+/**
+ * Normalize a licence descriptor into the canonical `{ spdx_id, licence_id, url, licence_url, verified_at, date_read, cc_by_4_eligible, excluded, status }` shape.
+ */
+function normalizeLicenceObject(raw) {
+  const spdxId = raw.spdx_id || raw.licence_id || null;
+  const url = raw.url || raw.licence_url || null;
+  const verifiedAt = raw.verified_at || raw.date_read || null;
+  const excluded = Boolean(raw.excluded);
+  const quarantined = Boolean(raw.quarantined);
+  const eligible =
+    !excluded &&
+    !quarantined &&
+    raw.cc_by_4_eligible !== false &&
+    Boolean(spdxId && CLEARED_SPDX_IDS.includes(spdxId)) &&
+    typeof url === 'string' &&
+    url.trim().length > 0 &&
+    typeof verifiedAt === 'string' &&
+    verifiedAt.trim().length > 0;
+  return {
+    spdx_id: spdxId,
+    licence_id: spdxId,
+    url,
+    licence_url: url,
+    verified_at: verifiedAt,
+    date_read: verifiedAt,
+    cc_by_4_eligible: eligible,
+    excluded,
+    ...(quarantined ? { quarantined: true } : {}),
+    status: raw.status || (eligible ? 'cleared' : excluded ? 'excluded' : 'unknown'),
+    ...(raw.reason ? { reason: raw.reason } : {}),
+  };
+}
+
+/**
+ * Resolve licence metadata for a model or LoRA filename.
+ *
+ * @param {string} name - Model or LoRA filename
+ * @param {Object|null} [explicitLicence] - Explicit override `{ licence_id, licence_url, date_read }`
+ * @param {Object|null} [modelLicences] - Map of `filename -> licence` overrides
+ */
+export function resolveModelLicence(name, explicitLicence = null, modelLicences = null) {
+  if (!name || typeof name !== 'string') {
+    return normalizeLicenceObject({ status: 'unknown', cc_by_4_eligible: false });
+  }
+
+  // Always check catalog first for quarantined/excluded models so an override cannot mask a held model.
+  const baseName = name.split(/[\\/]/).pop();
+  const catalogMatch = KNOWN_CATALOG.find((entry) => entry.pattern.test(baseName));
+  if (catalogMatch && catalogMatch.excluded) {
+    return normalizeLicenceObject(catalogMatch);
+  }
+
+  const override = explicitLicence || (modelLicences && (modelLicences[name] || modelLicences[baseName]));
+  if (override && typeof override === 'object') {
+    return normalizeLicenceObject(override);
+  }
+
+  if (catalogMatch) {
+    return normalizeLicenceObject(catalogMatch);
+  }
+
+  return normalizeLicenceObject({ status: 'unknown', cc_by_4_eligible: false });
+}
+
+/**
+ * Check whether a model/LoRA entry carries a non-empty sha256 digest.
+ */
+export function hasModelSha256(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  return typeof entry.sha256 === 'string' && entry.sha256.trim().length > 0;
+}
+
+/**
+ * Normalize a model identifier to its canonical family key (DESIGN-v3 §12.5).
+ */
+export function normalizeModelFamilyKey(modelId) {
+  if (!modelId || typeof modelId !== 'string') return '';
+  const raw = modelId.trim().toLowerCase();
+  if (!raw) return '';
+  if (raw.startsWith('human:') || raw === 'human') return 'human';
+  if (raw.startsWith('rule-based:')) return 'rule-based';
+  const stripped = raw
+    .replace(/^model:/, '')
+    .replace(/@sha256:[0-9a-f]{64}$/, '')
+    .replace(/\.(safetensors|ckpt|pt|pth|bin|gguf)$/, '');
+  if (stripped.includes('glimmer') || stripped.includes('muse-glimmer') || stripped.includes('muse_glimmer')) {
+    return 'family:muse-glimmer-30b';
+  }
+  if (stripped.includes('qwen')) {
+    return 'family:qwen';
+  }
+  if (stripped.includes('gemma')) {
+    return 'family:gemma';
+  }
+  if (stripped.includes('internvl')) {
+    return 'family:internvl';
+  }
+  if (stripped.includes('siglip') || stripped.includes('ai-eyes')) {
+    return 'family:siglip2';
+  }
+  if (stripped.includes('flux') || stripped === 'ae') {
+    return 'family:flux';
+  }
+  if (/^(?:sd3\.?5|stable[_-]diffusion[_-]3\.?5)/.test(stripped)) {
+    return 'family:sd3';
+  }
+  if (
+    stripped.startsWith('sdxl') ||
+    stripped.includes('stable-diffusion-xl') ||
+    stripped.includes('stable_diffusion_xl') ||
+    /^(?:dreamshaper|juggernaut|pony|illustrious|animagine)/.test(stripped)
+  ) {
+    return 'family:sdxl';
+  }
+  return stripped;
+}
+
+/**
+ * Check whether a model/LoRA pinning entry has a valid cleared SPDX licence,
+ * non-empty URL, non-empty date_read, and (by default) a non-empty sha256.
+ */
+export function isClearedLicenceEntry(entry, { requireSha256 = true } = {}) {
+  if (!entry || typeof entry !== 'object') return false;
+  if (entry.name && isQuarantinedName(entry.name)) return false;
+  if (requireSha256 && !hasModelSha256(entry)) return false;
+  const lic = entry.licence || {};
+  const spdxId = entry.licence_id || lic.spdx_id || lic.licence_id;
+  const url = entry.licence_url || lic.url || lic.licence_url;
+  const dateRead = entry.date_read || lic.verified_at || lic.date_read;
+  if (lic.excluded === true || lic.cc_by_4_eligible === false) return false;
+  if (!spdxId || !CLEARED_SPDX_IDS.includes(spdxId)) return false;
+  if (typeof url !== 'string' || !url.trim()) return false;
+  if (typeof dateRead !== 'string' || !dateRead.trim()) return false;
+  return true;
+}
+
+/**
+ * Enforce that every model and LoRA in a pinning block has a cleared licence
+ * unless `allowUnlicensedResearch` is explicitly set.
+ */
+export function assertClearedPinningLicences(models, loras, { allowUnlicensedResearch = false, requireSha256 = false } = {}) {
+  if (allowUnlicensedResearch) return;
+  const entries = [
+    ...Object.entries(models || {}).map(([role, entry]) => ({ role, ...entry })),
+    ...(loras || []).map((entry, idx) => ({ role: `lora[${idx}]`, ...entry })),
+  ];
+  const bad = entries.filter((e) => !isClearedLicenceEntry(e, { requireSha256 }));
+  if (bad.length > 0) {
+    const summary = bad
+      .map((b) => `${b.role}:${b.name || '<unnamed>'} (${b.licence_id || 'unlicensed'})`)
+      .join(', ');
+    throw inputError(
+      'MODEL_LICENCE_REJECTED',
+      `Model/LoRA licence check failed for: ${summary}`,
+      'Only cleared SPDX weights (Apache-2.0, MIT, BSD-*, CC0-1.0, CC-BY-4.0) with a verified licence_url are eligible for CC-BY-4.0 release.',
+    );
+  }
+}

package/lib/npy-meta.js

@@ -0,0 +1,130 @@
+/**
+ * NPY header reader — structural validation for .npy channel files in the
+ * asset-lane ingest contract (docs/asset-lane-kickoff.md).
+ *
+ * The asset contract lets a manifest declare a channel stored as a NumPy
+ * array (facet's standing sidecars, e.g. a styled/unstyled mask or a future
+ * per-texel view-owner map). sdlab never interprets the array's MEANING —
+ * it proves the file's declared dtype and shape match its actual header,
+ * the same way lib/png-meta.js proves a PNG's declared encoding matches
+ * its IHDR. Header only; the payload is hashed, not parsed.
+ *
+ * Format reference: NumPy NEP 1 (the .npy format, versions 1.0/2.0/3.0):
+ * magic "\x93NUMPY", one version byte pair, a little-endian header length
+ * (2 bytes for v1, 4 bytes for v2+), then a Python dict literal with keys
+ * 'descr', 'fortran_order', 'shape'.
+ *
+ * Schema 1.1.0 adds `readNpyValues` — still no MEANING, but a categorical
+ * npy channel declares its classes, and "declared ⊆ actual" is provable only
+ * by looking at the values. Kept to single-byte dtypes: those are what a
+ * per-pixel class/owner map is, and a reader that cannot honestly decode a
+ * dtype says so rather than skipping the proof silently.
+ */
+
+import { inputError } from './errors.js';
+
+const MAGIC = Buffer.from('\x93NUMPY', 'latin1');
+
+function npyError(message, hint) {
+  return inputError('NPY_INVALID', message, hint);
+}
+
+/**
+ * Parse a .npy file's header.
+ *
+ * @param {Buffer} buf — at least the first ~64KB of the file (the whole
+ *   file is fine; only the header is read)
+ * @param {string} [label] — filename for error messages
+ * @returns {{dtype:string, fortranOrder:boolean, shape:number[],
+ *            version:string, headerLength:number, dataOffset:number}}
+ */
+export function parseNpyHeader(buf, label = 'npy') {
+  if (buf.length < 10 || !buf.subarray(0, 6).equals(MAGIC)) {
+    throw npyError(`${label}: not a .npy file (bad magic).`);
+  }
+  const major = buf[6];
+  const minor = buf[7];
+  let headerLength;
+  let headerStart;
+  if (major === 1) {
+    headerLength = buf.readUInt16LE(8);
+    headerStart = 10;
+  } else if (major === 2 || major === 3) {
+    if (buf.length < 12) throw npyError(`${label}: truncated v${major} header.`);
+    headerLength = buf.readUInt32LE(8);
+    headerStart = 12;
+  } else {
+    throw npyError(`${label}: unsupported .npy format version ${major}.${minor}.`);
+  }
+  if (buf.length < headerStart + headerLength) {
+    throw npyError(`${label}: truncated header (declared ${headerLength} bytes).`);
+  }
+
+  const header = buf.toString('latin1', headerStart, headerStart + headerLength);
+
+  const descrMatch = header.match(/'descr'\s*:\s*'([^']+)'/);
+  const fortranMatch = header.match(/'fortran_order'\s*:\s*(True|False)/);
+  const shapeMatch = header.match(/'shape'\s*:\s*\(([^)]*)\)/);
+  if (!descrMatch || !fortranMatch || !shapeMatch) {
+    throw npyError(`${label}: header dict is missing descr/fortran_order/shape.`);
+  }
+
+  const shape = shapeMatch[1]
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((s) => {
+      const n = Number(s);
+      if (!Number.isInteger(n) || n < 0) {
+        throw npyError(`${label}: non-integer dimension "${s}" in shape.`);
+      }
+      return n;
+    });
+
+  return {
+    dtype: descrMatch[1],
+    fortranOrder: fortranMatch[1] === 'True',
+    shape,
+    version: `${major}.${minor}`,
+    headerLength,
+    dataOffset: headerStart + headerLength,
+  };
+}
+
+/**
+ * Single-byte dtypes whose values this contract can read. A categorical npy
+ * channel must declare one of these — see readNpyValues.
+ */
+export const NPY_PROVABLE_DTYPES = new Set(['|i1', '|u1', '|b1']);
+
+/**
+ * Read an npy payload as a typed array. Single-byte dtypes only, so element
+ * order is byte order and `fortran_order` does not change the VALUE SET a
+ * categorical proof examines (it changes which index means which pixel —
+ * that is the consumer's business, and numpy reads the flag itself).
+ *
+ * Also catches a truncation the header-only parse cannot: a file whose
+ * payload is shorter than its declared shape.
+ *
+ * @param {Buffer} buf — the whole file
+ * @param {ReturnType<typeof parseNpyHeader>} header
+ * @param {string} [label]
+ * @returns {Int8Array|Uint8Array}
+ */
+export function readNpyValues(buf, header, label = 'npy') {
+  if (!NPY_PROVABLE_DTYPES.has(header.dtype)) {
+    throw npyError(
+      `${label}: dtype ${header.dtype} is not one this contract reads values from.`,
+      `Value proofs cover ${[...NPY_PROVABLE_DTYPES].join(', ')} — the single-byte dtypes a per-pixel class or owner map uses. Export the channel in one of those, or drop "categorical" and let it ride as an opaque declared array.`
+    );
+  }
+  const count = header.shape.reduce((a, b) => a * b, 1);
+  const available = buf.length - header.dataOffset;
+  if (available < count) {
+    throw npyError(
+      `${label}: truncated payload — shape ${JSON.stringify(header.shape)} needs ${count} byte(s), the file carries ${available} after the header.`
+    );
+  }
+  const Ctor = header.dtype === '|i1' ? Int8Array : Uint8Array;
+  return new Ctor(buf.buffer, buf.byteOffset + header.dataOffset, count);
+}

package/lib/paths.js

@@ -10,12 +10,176 @@ import { inputError } from './errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-/** Absolute path to the repository root. */
-export const REPO_ROOT = join(__dirname, '..');
+// ─── Workspace root resolution (SDL-C1) ───────────────────────────
+//
+// `REPO_ROOT` used to be `join(__dirname, '..')` — always the directory
+// this module happens to live in. That is correct for an in-repo checkout,
+// but for an npm-installed consumer it resolves to
+// `node_modules/@mcptoolshop/style-dataset-lab`, so `sdlab init demo`
+// silently wrote the user's whole project tree into node_modules — gone on
+// the next `npm ci`.
+//
+// The fix is a 4-step search, cheapest/most-explicit signal first:
+//   1. SDLAB_ROOT env var, if set and it exists.
+//   2. Walk up from process.cwd() looking for a directory containing
+//      `projects/`. First hit wins — this is how a user's own workspace
+//      (wherever it lives) gets found.
+//   3. The module's own root, IF it already has a `projects/` dir — this is
+//      what preserves every existing in-repo dev/test workflow, where cwd
+//      already resolves via step 2 anyway, but is kept as an explicit
+//      fallback for callers with an unusual cwd.
+//   4. process.cwd() itself — a fresh workspace where `init` will create
+//      `projects/`.
+//
+// Whatever step wins, the result is never allowed to sit inside a
+// node_modules directory — that is the exact shape of the original bug, so
+// it is a hard error instead of a silent write into someone's
+// node_modules tree.
+
+/**
+ * True if any path segment of `absPath` is literally `node_modules`.
+ */
+function isInsideNodeModules(absPath) {
+  return resolve(absPath)
+    .split(/[\\/]+/)
+    .some((seg) => seg.toLowerCase() === 'node_modules');
+}
+
+function assertNotInNodeModules(absPath, label) {
+  if (isInsideNodeModules(absPath)) {
+    throw inputError(
+      'INPUT_ROOT_IN_NODE_MODULES',
+      `Resolved workspace root (${label}) sits inside a node_modules directory: ${absPath}`,
+      'Run sdlab from your own project directory, or set SDLAB_ROOT to your workspace path.'
+    );
+  }
+  return absPath;
+}
+
+/**
+ * Walk up from `startDir` looking for a directory that contains a
+ * `projects/` subdirectory. Returns the first hit, or null if the walk
+ * reaches the filesystem root without finding one.
+ */
+function walkUpForProjectsDir(startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(join(dir, 'projects'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null; // reached the filesystem root
+    dir = parent;
+  }
+}
+
+/**
+ * Pure resolution logic for the workspace root, taking every input
+ * explicitly (cwd, env, module root) rather than reading global process
+ * state directly. This is what makes it possible to unit-test all four
+ * branches deterministically without mutating the real process.cwd() or
+ * environment (which are shared, global, and unsafe to mutate across a
+ * concurrently-run test suite).
+ *
+ * Production callers should use `getWorkspaceRoot()` instead, which
+ * supplies the real process.cwd()/env and memoizes the result.
+ *
+ * @param {string} cwd
+ * @param {{env?: Object, moduleRoot?: string}} [opts]
+ * @returns {string} absolute workspace root
+ */
+export function resolveWorkspaceRootFrom(cwd, opts = {}) {
+  const env = opts.env || process.env;
+  const moduleRoot = opts.moduleRoot || join(__dirname, '..');
+
+  // 1. SDLAB_ROOT env var, if set and it exists.
+  const envRoot = env.SDLAB_ROOT;
+  if (envRoot && existsSync(envRoot)) {
+    return assertNotInNodeModules(resolve(envRoot), 'from SDLAB_ROOT');
+  }
+
+  // 2. Walk up from cwd looking for projects/.
+  const fromCwd = walkUpForProjectsDir(cwd);
+  if (fromCwd) {
+    return assertNotInNodeModules(fromCwd, 'found by walking up from the current directory');
+  }
+
+  // 3. The module root itself is the repo checkout.
+  if (existsSync(join(moduleRoot, 'projects'))) {
+    return assertNotInNodeModules(resolve(moduleRoot), 'the style-dataset-lab install directory');
+  }
+
+  // 4. Fresh workspace — init will create projects/ here.
+  return assertNotInNodeModules(resolve(cwd), 'the current directory');
+}
+
+let _workspaceRootCache = null;
+
+/**
+ * Resolve (and memoize) the workspace root using the real process.cwd()
+ * and process.env. Safe to call repeatedly — it only walks the filesystem
+ * once per process, unless reset.
+ * @returns {string}
+ */
+export function getWorkspaceRoot() {
+  if (_workspaceRootCache === null) {
+    _workspaceRootCache = resolveWorkspaceRootFrom(process.cwd());
+  }
+  return _workspaceRootCache;
+}
+
+/**
+ * Clear the memoized workspace root so the next getWorkspaceRoot() call
+ * re-resolves from scratch. Exists for tests that need to exercise the
+ * resolver under different SDLAB_ROOT/cwd conditions within one process.
+ */
+export function resetWorkspaceRootCache() {
+  _workspaceRootCache = null;
+}
+
+/**
+ * Absolute path to the workspace root — the directory that contains (or
+ * will contain) `projects/`. Kept as a plain exported constant for
+ * backward compatibility with the ~30 existing call sites that do
+ * `join(REPO_ROOT, ...)`, but its VALUE now comes from the resolver above
+ * rather than being hardcoded to this module's own location.
+ */
+export const REPO_ROOT = getWorkspaceRoot();
+
+/**
+ * Absolute path to the INSTALLED PACKAGE's own root — always module-relative,
+ * never the user's workspace.
+ *
+ * There are two distinct roots and conflating them is a shipping bug:
+ *
+ *   - **workspace root** (`getWorkspaceRoot()`) — where the user's `projects/`
+ *     live. Correctly cwd-relative, so an npm-installed user's data lands in
+ *     their own directory instead of inside `node_modules`.
+ *   - **package root** (this) — where assets that SHIP IN THE TARBALL live:
+ *     `templates/` (domain starter packs) and `runtime/` (ComfyUI workflow
+ *     graphs). These belong to the install, not to the workspace.
+ *
+ * In a repo checkout the two coincide, which is exactly why the distinction
+ * is easy to lose and impossible to catch with in-repo tests. Measured in a
+ * clean-room tarball install: with `templates/` resolved against the
+ * workspace root, `sdlab init demo --domain character-design` failed with
+ * `INPUT_UNKNOWN_DOMAIN: Available: generic,` — the five domain packs were
+ * sitting in the package the whole time, being looked for in the user's cwd.
+ */
+export function getPackageRoot() {
+  return resolve(join(__dirname, '..'));
+}
+
+// ─── Project name / path safety (SDL-C3) ──────────────────────────
+
+// A project name must be a single path segment: no separators, no `..`.
+// This is deliberately a blacklist (not the stricter creation-time
+// `/^[a-z0-9][a-z0-9-]*[a-z0-9]$/` from scripts/init.js) so existing
+// project directories keep resolving; it is paired with the
+// resolveSafeProjectPath() containment check below as defense in depth.
+const UNSAFE_PROJECT_NAME_RE = /\.\.|[\\/]/;
 
 /**
  * Resolve the root directory for a named project.
- * @param {string} name — project name (e.g. 'star-freight')
+ * @param {string} name — a single path segment, e.g. 'my-project'
  * @returns {string} absolute path to projects/<name>/
  */
 export function getProjectRoot(name) {
@@ -26,12 +190,32 @@ export function getProjectRoot(name) {
       'Pass --project <name>.'
     );
   }
-  const root = join(REPO_ROOT, 'projects', name);
+  if (UNSAFE_PROJECT_NAME_RE.test(name)) {
+    throw inputError(
+      'INPUT_UNSAFE_PROJECT_NAME',
+      `Project name "${name}" is not valid — it contains a path separator or "..".`,
+      `--project takes a name, not a path: it names a directory under projects/. ` +
+      `Try --project my-project. Run "sdlab init <name>" to create one.`
+    );
+  }
+  const projectsDir = join(getWorkspaceRoot(), 'projects');
+  // Defense in depth: even though the blacklist above already rejects the
+  // characters needed to escape projectsDir, reuse the same containment
+  // pattern as every other user-path entry point in this file so a future
+  // change to the blacklist can't silently reopen the traversal.
+  const root = resolveSafeProjectPath(projectsDir, name, { flagName: 'project' });
   if (!existsSync(root)) {
     throw inputError(
       'INPUT_UNKNOWN_PROJECT',
       `Project "${name}" not found at ${root}.`,
-      `Run: sdlab init ${name} --domain <domain>`
+      // Two different causes land here and they need opposite responses, so
+      // name both rather than assuming the project is missing. Since the
+      // workspace root is resolved from the current directory, running from
+      // the wrong place produces this same error — and blindly following
+      // "run init" would then scaffold a duplicate project somewhere else.
+      `Looking under ${projectsDir} (workspace resolved from the current directory).\n` +
+      `  · Wrong directory? cd to your workspace, or set SDLAB_ROOT to it.\n` +
+      `  · New project?     sdlab init ${name} --domain character-design`
     );
   }
   return root;
@@ -100,8 +284,13 @@ export function getRunsDir(projectRoot) {
 }
 
 /**
- * Return the runtime templates directory (repo-level).
+ * Return the ComfyUI runtime workflow templates directory.
+ *
+ * PACKAGE-relative, deliberately — see `getPackageRoot()`. `runtime/` ships
+ * inside the npm tarball; it is not workspace content. Resolving it against
+ * the workspace root made `listWorkflowTemplates()` return `[]` for every
+ * installed user, which is the bug `getPackageRoot()` exists to prevent.
  */
 export function getRuntimeDir() {
-  return join(REPO_ROOT, 'runtime');
+  return join(getPackageRoot(), 'runtime');
 }