draftgo-cli 1.0.4

package/src/worktree/inlineScripts.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const vm = require('vm');
+const { spawnSync } = require('child_process');
+const parse5 = require('parse5');
+
+const DATA_SCRIPT_TYPES = new Set([
+  'application/json',
+  'application/ld+json',
+  'importmap',
+  'speculationrules',
+]);
+
+function attribute(node, name) {
+  const item = (node.attrs || []).find((candidate) => candidate.name.toLowerCase() === name);
+  return item ? item.value : '';
+}
+
+function scriptSource(node) {
+  return (node.childNodes || [])
+    .filter((child) => child.nodeName === '#text')
+    .map((child) => child.value || '')
+    .join('');
+}
+
+function collectInlineScripts(html) {
+  const document = parse5.parse(String(html || ''), { sourceCodeLocationInfo: true });
+  const scripts = [];
+  const visit = (node) => {
+    if (node.tagName === 'script' && !attribute(node, 'src')) {
+      const type = attribute(node, 'type').trim().toLowerCase();
+      if (!DATA_SCRIPT_TYPES.has(type) && (!type || type === 'module' || /(?:java|ecma)script/.test(type))) {
+        const location = node.sourceCodeLocation || {};
+        const startTag = location.startTag || {};
+        scripts.push({
+          index: scripts.length + 1,
+          type: type === 'module' ? 'module' : 'classic',
+          source: scriptSource(node),
+          startLine: startTag.endLine || location.startLine || 1,
+          startColumn: startTag.endCol || 1,
+        });
+      }
+    }
+    for (const child of node.childNodes || []) visit(child);
+    if (node.content) visit(node.content);
+  };
+  visit(document);
+  return scripts;
+}
+
+function syntaxPosition(message) {
+  const line = String(message || '').match(/(?:\[stdin\]|inline-script):(\d+)(?::(\d+))?/);
+  if (line) return { line: Number(line[1]), column: Number(line[2] || 1) };
+  const caretLines = String(message || '').split(/\r?\n/);
+  const caretIndex = caretLines.findIndex((value) => /^\s*\^/.test(value));
+  return { line: null, column: caretIndex > 0 ? caretLines[caretIndex].indexOf('^') + 1 : null };
+}
+
+function conciseMessage(error) {
+  const lines = String(error && (error.stderr || error.message) || error || '').split(/\r?\n/);
+  return lines.find((line) => /^SyntaxError:/.test(line))
+    || lines.find((line) => line.trim() && !/^\s*at\s/.test(line))
+    || 'Invalid JavaScript syntax';
+}
+
+function validateInlineScripts(html) {
+  const issues = [];
+  for (const script of collectInlineScripts(html)) {
+    if (!script.source.trim()) continue;
+    let failure = null;
+    if (script.type === 'module') {
+      const result = spawnSync(process.execPath, ['--check', '--input-type=module'], {
+        input: script.source,
+        encoding: 'utf8',
+        windowsHide: true,
+      });
+      if (result.error || result.status !== 0) failure = { message: result.stderr || result.stdout || result.error.message };
+    } else {
+      try { new vm.Script(script.source, { filename: 'inline-script' }); }
+      catch (error) { failure = error; }
+    }
+    if (!failure) continue;
+    const diagnostic = failure.stack || failure.message;
+    const position = syntaxPosition(diagnostic);
+    issues.push({
+      code: 'DG-JS-001',
+      script: script.index,
+      script_type: script.type,
+      line: position.line ? script.startLine + position.line - 1 : script.startLine,
+      column: position.column
+        ? position.column + (position.line === 1 ? script.startColumn - 1 : 0)
+        : script.startColumn,
+      message: conciseMessage(failure),
+    });
+  }
+  return issues;
+}
+
+module.exports = { DATA_SCRIPT_TYPES, collectInlineScripts, validateInlineScripts };

package/src/worktree/locks.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { acquireLock, releaseLock } = require('../worklog');
+const { WorktreeError } = require('./errors');
+
+// Reuse owner-token locks, but never expire an active long-running transfer.
+function lockFile(file) {
+  const lockPath = `${file}.lock`;
+  try {
+    const token = fs.readFileSync(lockPath, 'utf8').trim();
+    const pid = Number(token.split(':')[0]);
+    if (Number.isSafeInteger(pid) && pid > 0) {
+      try { process.kill(pid, 0); } catch (error) {
+        if (error.code === 'ESRCH' && fs.readFileSync(lockPath, 'utf8').trim() === token) fs.rmSync(lockPath);
+      }
+    }
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  try { return acquireLock(file, { lockTimeoutMs: 0, lockStaleMs: Number.MAX_SAFE_INTEGER }); }
+  catch (error) {
+    if (error.code !== 'WORKLOG_LOCK_TIMEOUT') throw error;
+    throw new WorktreeError('WORKTREE_LOCKED', 'Another process owns this worktree resource; retry after it finishes.', { lock_path: lockPath });
+  }
+}
+
+async function withResourceLocks(projectDir, keys, action) {
+  const locks = [];
+  try {
+    for (const key of [...new Set(keys)].sort()) {
+      const name = crypto.createHash('sha256').update(key).digest('hex');
+      locks.push(lockFile(path.join(projectDir, '.draftgo', 'worktree', '.locks', name)));
+    }
+    return await action();
+  } finally { for (const lock of locks.reverse()) releaseLock(lock); }
+}
+
+async function withManifestLock(projectDir, action) {
+  const file = path.join(projectDir, '.draftgo', 'worktree', 'manifest.json');
+  const started = Date.now();
+  let lock;
+  while (!lock) {
+    try { lock = lockFile(file); } catch (error) {
+      if (error.code !== 'WORKTREE_LOCKED' || Date.now() - started >= 10000) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 15));
+    }
+  }
+  try { return await action(); } finally { releaseLock(lock); }
+}
+
+module.exports = { withResourceLocks, withManifestLock };

package/src/worktree/manifest.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { WorktreeError } = require('./errors');
+const { entryKey } = require('./types');
+const { writeJsonAtomic } = require('./streams');
+
+const { withManifestLock } = require('./locks');
+const snapshots = new WeakMap();
+const MANIFEST_SCHEMA_VERSION = 1;
+
+function manifestPath(projectDir) {
+  return path.join(projectDir, '.draftgo', 'worktree', 'manifest.json');
+}
+
+function emptyManifest() {
+  const value = { schema_version: MANIFEST_SCHEMA_VERSION, entries: {} };
+  snapshots.set(value, {});
+  return value;
+}
+
+function loadManifest(projectDir) {
+  const file = manifestPath(projectDir);
+  if (!fs.existsSync(file)) return emptyManifest();
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new WorktreeError('INVALID_WORKTREE_MANIFEST', `Invalid checkout manifest: ${error.message}`);
+  }
+  if (!parsed || parsed.schema_version !== MANIFEST_SCHEMA_VERSION
+      || !parsed.entries || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
+    throw new WorktreeError('INVALID_WORKTREE_MANIFEST', 'Unsupported or malformed checkout manifest.');
+  }
+  snapshots.set(parsed, JSON.parse(JSON.stringify(parsed.entries)));
+  return parsed;
+}
+
+function getEntry(manifest, resourceType, resourceId) {
+  return manifest.entries[entryKey(resourceType, resourceId)] || null;
+}
+
+function relativePath(projectDir, absolutePath) {
+  const relative = path.relative(path.resolve(projectDir), path.resolve(absolutePath));
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new WorktreeError('INVALID_WORKTREE_PATH', 'Checkout paths must stay inside the project.');
+  }
+  return relative.replace(/\\/g, '/');
+}
+
+function absolutePath(projectDir, relative) {
+  if (!relative || typeof relative !== 'string' || path.isAbsolute(relative)) {
+    throw new WorktreeError('INVALID_WORKTREE_PATH', 'Manifest path must be project-relative.');
+  }
+  const root = path.resolve(projectDir);
+  const resolved = path.resolve(root, relative);
+  const relation = path.relative(root, resolved);
+  if (!relation || relation.startsWith('..') || path.isAbsolute(relation)) {
+    throw new WorktreeError('INVALID_WORKTREE_PATH', 'Manifest path escapes the project.');
+  }
+  return resolved;
+}
+
+async function saveManifest(projectDir, manifest) {
+  const before = snapshots.get(manifest) || {};
+  await withManifestLock(projectDir, async () => {
+    const fresh = loadManifest(projectDir);
+    for (const key of new Set([...Object.keys(before), ...Object.keys(manifest.entries)])) {
+      if (JSON.stringify(before[key]) === JSON.stringify(manifest.entries[key])) continue;
+      if (manifest.entries[key] === undefined) delete fresh.entries[key];
+      else fresh.entries[key] = manifest.entries[key];
+    }
+    fresh.updated_at = new Date().toISOString();
+    await writeJsonAtomic(manifestPath(projectDir), fresh);
+    snapshots.set(manifest, JSON.parse(JSON.stringify(manifest.entries)));
+  });
+}
+
+module.exports = {
+  MANIFEST_SCHEMA_VERSION,
+  manifestPath,
+  emptyManifest,
+  loadManifest,
+  getEntry,
+  relativePath,
+  absolutePath,
+  saveManifest,
+};

package/src/worktree/status.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const fs = require('fs');
+const { loadProjectConfig } = require('../projectConfig');
+const { DraftGoMcpClient } = require('../mcp/client');
+const backendDefaults = require('./backend');
+const { loadManifest, absolutePath } = require('./manifest');
+const { hashFile } = require('./streams');
+
+function versionValue(source) {
+  if (!source) return null;
+  if (source.base_version != null) return source.base_version;
+  if (source.base_revision != null) return source.base_revision;
+  return null;
+}
+
+function sameVersion(entry, remote) {
+  const local = versionValue(entry);
+  const current = versionValue(remote);
+  if (local == null || current == null) return true;
+  return String(local) === String(current);
+}
+
+async function optionalHash(projectDir, relative) {
+  if (!relative) return null;
+  const file = absolutePath(projectDir, relative);
+  return fs.existsSync(file) ? (await hashFile(file)).hash : null;
+}
+
+function classify(entry, localHash, baseHash, remote) {
+  const manifestHash = entry.base_hash;
+  const remoteHash = remote && remote.content_hash || null;
+  const baseMatchesManifest = baseHash === manifestHash;
+  const localMatchesManifest = localHash === manifestHash;
+  const localMatchesRemote = Boolean(localHash && remoteHash && localHash === remoteHash);
+  const remoteMatchesManifest = Boolean(remoteHash && remoteHash === manifestHash);
+  const versionMatches = remote ? sameVersion(entry, remote) : null;
+
+  let state;
+  let recommendation = null;
+  if (!localHash) {
+    state = 'local_missing';
+    recommendation = `draftgo checkout ${entry.resource_type} ${entry.resource_id} --force`;
+  } else if (!baseHash) {
+    state = 'base_missing';
+    recommendation = `draftgo checkout ${entry.resource_type} ${entry.resource_id} --force`;
+  } else if (!remote) {
+    state = baseMatchesManifest
+      ? (localMatchesManifest ? 'clean_local' : 'local_modified')
+      : 'local_metadata_corrupt';
+  } else if (localMatchesRemote && (!remoteMatchesManifest || !versionMatches || !baseMatchesManifest)) {
+    state = remoteMatchesManifest ? 'metadata_stale' : 'committed_unrecorded';
+    recommendation = `draftgo reconcile ${entry.resource_type} ${entry.resource_id}`;
+  } else if (!baseMatchesManifest) {
+    state = 'local_metadata_corrupt';
+    recommendation = `draftgo checkout ${entry.resource_type} ${entry.resource_id} --force`;
+  } else if (remoteMatchesManifest && versionMatches) {
+    state = localMatchesManifest ? 'clean' : 'local_modified';
+  } else if (localMatchesManifest) {
+    state = 'remote_changed';
+    recommendation = `draftgo checkout ${entry.resource_type} ${entry.resource_id}`;
+  } else {
+    state = 'diverged';
+    recommendation = `draftgo commit ${entry.resource_type} ${entry.resource_id}`;
+  }
+
+  return {
+    state,
+    local_hash: localHash,
+    base_file_hash: baseHash,
+    manifest_hash: manifestHash,
+    remote_hash: remoteHash,
+    manifest_version: versionValue(entry),
+    remote_version: versionValue(remote),
+    version_matches: versionMatches,
+    local_matches_remote: localMatchesRemote,
+    recommendation,
+  };
+}
+
+async function inspectEntry(projectDir, entry, remote = null) {
+  const [localHash, baseHash] = await Promise.all([
+    optionalHash(projectDir, entry.local_path),
+    optionalHash(projectDir, entry.base_path),
+  ]);
+  return { ...entry, ...classify(entry, localHash, baseHash, remote) };
+}
+
+async function openMetadataSession(config, options = {}) {
+  if (options.client && options.tools) return { client: options.client, tools: options.tools };
+  const client = options.client || new DraftGoMcpClient(config);
+  await client.initialize(options);
+  const tools = options.tools || await client.listAllTools(options);
+  return { client, tools };
+}
+
+async function inspectRemoteCheckouts(projectDir, options = {}) {
+  const config = options.config || loadProjectConfig(projectDir);
+  const manifest = options.manifest || loadManifest(projectDir);
+  const backend = { ...backendDefaults, ...(options.backend || {}) };
+  const session = options.backend && typeof options.backend.resolveMetadata === 'function'
+    ? { client: options.client || {}, tools: options.tools || [] }
+    : await openMetadataSession(config, options);
+  const entries = options.entries || Object.values(manifest.entries);
+  const { mapBounded } = require('../mcp/parallel');
+  return mapBounded(entries, async (entry) => {
+    const remote = await backend.resolveMetadata(config, entry.resource_type, entry.resource_id, {
+      ...options,
+      ...session,
+      projectDir,
+      clientInitialized: true,
+    });
+    return inspectEntry(projectDir, entry, remote);
+  }, options);
+}
+
+module.exports = {
+  versionValue,
+  sameVersion,
+  classify,
+  inspectEntry,
+  openMetadataSession,
+  inspectRemoteCheckouts,
+};

package/src/worktree/streams.js

@@ -0,0 +1,200 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { once } = require('events');
+const { WorktreeError } = require('./errors');
+
+function normalizeSha256(value) {
+  if (value == null || value === '') return null;
+  const normalized = String(value).trim().toLowerCase().replace(/^sha-?256[:=]/, '');
+  return /^[a-f0-9]{64}$/.test(normalized) ? normalized : null;
+}
+
+function tempPathFor(destination) {
+  const suffix = crypto.randomBytes(8).toString('hex');
+  return path.join(
+    path.dirname(destination),
+    `.${path.basename(destination)}.${process.pid}.${suffix}.tmp`
+  );
+}
+
+async function ensureParent(filePath) {
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+}
+
+async function syncDirectory(directory) {
+  let handle;
+  try {
+    handle = await fs.promises.open(directory, 'r');
+    await handle.sync();
+  } catch {
+    // Directory fsync is unavailable on some Windows filesystems.
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+}
+
+function bodyIterable(body) {
+  if (!body) throw new WorktreeError('DOWNLOAD_INCOMPLETE', 'The content response did not include a body.');
+  if (typeof body[Symbol.asyncIterator] === 'function') return body;
+  if (typeof body.getReader === 'function') {
+    return {
+      async *[Symbol.asyncIterator]() {
+        const reader = body.getReader();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) return;
+            yield value;
+          }
+        } finally {
+          reader.releaseLock();
+        }
+      },
+    };
+  }
+  throw new WorktreeError('DOWNLOAD_INCOMPLETE', 'The content response body is not streamable.');
+}
+
+async function writeChunk(stream, chunk) {
+  if (stream.write(chunk)) return;
+  await once(stream, 'drain');
+}
+
+async function closeStream(stream) {
+  stream.end();
+  await once(stream, 'close');
+}
+
+async function streamToFiles(body, destinations, options = {}) {
+  const unique = [...new Set(destinations.map((item) => path.resolve(item)))];
+  if (!unique.length) throw new WorktreeError('INVALID_DESTINATION', 'At least one destination is required.');
+  await Promise.all(unique.map(ensureParent));
+
+  const temporaries = unique.map((destination) => ({
+    destination,
+    temporary: tempPathFor(destination),
+    backup: `${tempPathFor(destination)}.bak`,
+    stream: null,
+    backedUp: false,
+    installed: false,
+  }));
+  const hash = crypto.createHash('sha256');
+  let size = 0;
+  let complete = false;
+
+  try {
+    for (const item of temporaries) {
+      item.stream = fs.createWriteStream(item.temporary, { flags: 'wx', mode: 0o600 });
+      await once(item.stream, 'open');
+    }
+
+    for await (const rawChunk of bodyIterable(body)) {
+      const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+      hash.update(chunk);
+      size += chunk.length;
+      for (const item of temporaries) await writeChunk(item.stream, chunk);
+    }
+
+    for (const item of temporaries) {
+      await new Promise((resolve, reject) => item.stream.end((error) => error ? reject(error) : resolve()));
+      await fs.promises.open(item.temporary, 'r+').then(async (handle) => {
+        try { await handle.sync(); } finally { await handle.close(); }
+      });
+    }
+
+    const actualHash = hash.digest('hex');
+    const expectedHash = normalizeSha256(options.expectedHash);
+    if (options.expectedHash && !expectedHash) {
+      throw new WorktreeError('INVALID_CONTENT_HASH', 'The backend returned an invalid SHA-256 hash.');
+    }
+    if (expectedHash && actualHash !== expectedHash) {
+      throw new WorktreeError('HASH_MISMATCH', 'Downloaded content did not match its SHA-256 metadata.', {
+        expected_hash: expectedHash,
+        actual_hash: actualHash,
+      });
+    }
+    if (options.expectedSize != null && Number(options.expectedSize) !== size) {
+      throw new WorktreeError('DOWNLOAD_INCOMPLETE', 'Downloaded content size did not match its metadata.', {
+        expected_size: Number(options.expectedSize),
+        actual_size: size,
+      });
+    }
+
+    try {
+      for (const item of temporaries) {
+        if (fs.existsSync(item.destination)) {
+          await fs.promises.rename(item.destination, item.backup);
+          item.backedUp = true;
+        }
+      }
+      for (const item of temporaries) {
+        await fs.promises.rename(item.temporary, item.destination);
+        item.installed = true;
+      }
+    } catch (error) {
+      for (const item of [...temporaries].reverse()) {
+        if (item.installed) await fs.promises.rm(item.destination, { force: true }).catch(() => {});
+        if (item.backedUp) await fs.promises.rename(item.backup, item.destination).catch(() => {});
+      }
+      throw error;
+    }
+    await Promise.all([...new Set(unique.map(path.dirname))].map(syncDirectory));
+    await Promise.all(temporaries.map((item) => fs.promises.rm(item.backup, { force: true })));
+    complete = true;
+    return { hash: actualHash, size };
+  } finally {
+    for (const item of temporaries) {
+      if (item.stream && !item.stream.closed) item.stream.destroy();
+      if (!complete) await fs.promises.rm(item.temporary, { force: true }).catch(() => {});
+      if (!complete && item.backedUp && fs.existsSync(item.backup) && !fs.existsSync(item.destination)) {
+        await fs.promises.rename(item.backup, item.destination).catch(() => {});
+      }
+      if (complete) await fs.promises.rm(item.backup, { force: true }).catch(() => {});
+    }
+  }
+}
+
+async function hashFile(filePath) {
+  const hash = crypto.createHash('sha256');
+  let size = 0;
+  const stream = fs.createReadStream(filePath);
+  for await (const chunk of stream) {
+    hash.update(chunk);
+    size += chunk.length;
+  }
+  return { hash: hash.digest('hex'), size };
+}
+
+async function copyFileAtomic(source, destination, options = {}) {
+  return streamToFiles(fs.createReadStream(source), [destination], options);
+}
+
+async function writeJsonAtomic(destination, value) {
+  await ensureParent(destination);
+  const temporary = tempPathFor(destination);
+  let handle;
+  try {
+    handle = await fs.promises.open(temporary, 'wx', 0o600);
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await fs.promises.rename(temporary, destination);
+    await syncDirectory(path.dirname(destination));
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+    await fs.promises.rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+module.exports = {
+  normalizeSha256,
+  tempPathFor,
+  streamToFiles,
+  hashFile,
+  copyFileAtomic,
+  writeJsonAtomic,
+};

package/src/worktree/types.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const crypto = require('crypto');
+const { WorktreeError } = require('./errors');
+
+const RESOURCE_TYPES = Object.freeze({
+  pages: Object.freeze({ directory: 'pages', prefix: 'page' }),
+  navigations: Object.freeze({ directory: 'navigations', prefix: 'nav' }),
+  docs: Object.freeze({ directory: 'docs', prefix: 'article' }),
+});
+
+const TYPE_ALIASES = new Map([
+  ['page', 'pages'],
+  ['pages', 'pages'],
+  ['nav', 'navigations'],
+  ['navigation', 'navigations'],
+  ['navigations', 'navigations'],
+  ['doc', 'docs'],
+  ['docs', 'docs'],
+  ['article', 'docs'],
+  ['articles', 'docs'],
+  ['docs/articles', 'docs'],
+]);
+
+const CONTENT_EXTENSIONS = new Map([
+  ['text/html', '.html'],
+  ['application/xhtml+xml', '.html'],
+  ['text/markdown', '.md'],
+  ['text/x-markdown', '.md'],
+  ['text/plain', '.txt'],
+]);
+
+function canonicalResourceType(value) {
+  const key = String(value || '').trim().toLowerCase().replace(/\\/g, '/');
+  const canonical = TYPE_ALIASES.get(key);
+  if (!canonical) {
+    throw new WorktreeError(
+      'UNSUPPORTED_RESOURCE_TYPE',
+      `Unsupported checkout resource type: ${value}. Expected pages, nav, or docs.`,
+      { resource_type: value }
+    );
+  }
+  return canonical;
+}
+
+function mediaType(contentType) {
+  return String(contentType || '').split(';', 1)[0].trim().toLowerCase();
+}
+
+function normalizeExtension(contentType, backendExtension) {
+  const known = CONTENT_EXTENSIONS.get(mediaType(contentType));
+  if (known) return known;
+  if (backendExtension == null || backendExtension === '') {
+    throw new WorktreeError(
+      'MISSING_FILE_EXTENSION',
+      'DraftGo must provide a safe file extension for this content type.',
+      { content_type: contentType },
+    );
+  }
+  let extension = String(backendExtension).trim();
+  if (!extension.startsWith('.')) extension = `.${extension}`;
+  if (!/^\.[A-Za-z0-9][A-Za-z0-9._-]{0,15}$/.test(extension)) {
+    throw new WorktreeError(
+      'UNSAFE_FILE_EXTENSION',
+      'The backend returned an unsafe checkout file extension.',
+      { file_extension: backendExtension }
+    );
+  }
+  return extension.toLowerCase();
+}
+
+function safeIdSegment(value) {
+  const raw = String(value == null ? '' : value).trim();
+  if (!raw) throw new WorktreeError('INVALID_RESOURCE_ID', 'A non-empty resource id is required.');
+  let clean = raw.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^\.+/, '').slice(0, 80);
+  if (!clean) clean = 'resource';
+  if (clean !== raw) {
+    const suffix = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 10);
+    clean = `${clean.slice(0, 68)}-${suffix}`;
+  }
+  return clean;
+}
+
+function entryKey(resourceType, resourceId) {
+  return `${canonicalResourceType(resourceType)}:${String(resourceId)}`;
+}
+
+function resourceFileName(resourceType, resourceId, extension) {
+  const canonical = canonicalResourceType(resourceType);
+  return `${RESOURCE_TYPES[canonical].prefix}_${safeIdSegment(resourceId)}${extension}`;
+}
+
+module.exports = {
+  RESOURCE_TYPES,
+  TYPE_ALIASES,
+  CONTENT_EXTENSIONS,
+  canonicalResourceType,
+  mediaType,
+  normalizeExtension,
+  safeIdSegment,
+  entryKey,
+  resourceFileName,
+};