@losclaws/cli 0.1.2 → 0.1.4

package/src/workshop-local.js

@@ -0,0 +1,785 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+import { CliError } from './errors.js';
+
+const execFileAsync = promisify(execFile);
+const localVersion = 1;
+const metaDirectoryName = '.losclaws';
+
+export async function initWorkshopWorkspaceRoot({
+  requestWorkshop,
+  workspaceId,
+  rootPath = process.cwd(),
+  role = 'worker',
+  syncArtifacts = true,
+  syncSkills = true,
+  skillsRepoUrl = '',
+  skillsRepoRef = 'main',
+}) {
+  const absoluteRoot = path.resolve(rootPath);
+  const workspace = await requestWorkshop({
+    path: `/api/v1/workspaces/${workspaceId}`,
+  });
+
+  const state = {
+    version: localVersion,
+    rootType: 'workspace',
+    rootPath: absoluteRoot,
+    role,
+    workspace: normalizeIdentity(workspace),
+    project: null,
+    artifacts: [],
+    skills: [],
+    updatedAt: new Date().toISOString(),
+  };
+
+  await writeStateFiles(absoluteRoot, state);
+  const results = {
+    rootPath: absoluteRoot,
+    rootType: 'workspace',
+    workspaceId: state.workspace.id,
+    syncedArtifacts: 0,
+    syncedSkills: 0,
+    notes: [],
+  };
+
+  if (syncArtifacts) {
+    const pull = await pullWorkshopArtifacts({ requestWorkshop, rootPath: absoluteRoot });
+    results.syncedArtifacts = pull.downloaded;
+    results.notes.push(...pull.notes);
+  }
+  if (syncSkills) {
+    const sync = await syncWorkshopSkills({
+      requestWorkshop,
+      rootPath: absoluteRoot,
+      role,
+      skillsRepoUrl,
+      skillsRepoRef,
+    });
+    results.syncedSkills = sync.installed;
+    results.notes.push(...sync.notes);
+  }
+
+  const status = await getWorkshopSyncStatus({ rootPath: absoluteRoot });
+  results.artifactStatus = status.summary;
+  return results;
+}
+
+export async function initWorkshopProjectRoot({
+  requestWorkshop,
+  projectId,
+  rootPath = process.cwd(),
+  role = 'worker',
+  syncArtifacts = true,
+  syncSkills = true,
+  skillsRepoUrl = '',
+  skillsRepoRef = 'main',
+}) {
+  const absoluteRoot = path.resolve(rootPath);
+  const project = await requestWorkshop({
+    path: `/api/v1/projects/${projectId}`,
+  });
+  const workspaceId = extractWorkspaceId(project);
+  if (!workspaceId) {
+    throw new CliError('Workshop project payload does not include a workspace id.');
+  }
+  const workspace = await requestWorkshop({
+    path: `/api/v1/workspaces/${workspaceId}`,
+  });
+
+  const state = {
+    version: localVersion,
+    rootType: 'project',
+    rootPath: absoluteRoot,
+    role,
+    workspace: normalizeIdentity(workspace),
+    project: normalizeIdentity(project),
+    artifacts: [],
+    skills: [],
+    updatedAt: new Date().toISOString(),
+  };
+
+  await writeStateFiles(absoluteRoot, state);
+  const results = {
+    rootPath: absoluteRoot,
+    rootType: 'project',
+    workspaceId: state.workspace.id,
+    projectId: state.project.id,
+    syncedArtifacts: 0,
+    syncedSkills: 0,
+    notes: [],
+  };
+
+  if (syncArtifacts) {
+    const pull = await pullWorkshopArtifacts({ requestWorkshop, rootPath: absoluteRoot });
+    results.syncedArtifacts = pull.downloaded;
+    results.notes.push(...pull.notes);
+  }
+  if (syncSkills) {
+    const sync = await syncWorkshopSkills({
+      requestWorkshop,
+      rootPath: absoluteRoot,
+      role,
+      skillsRepoUrl,
+      skillsRepoRef,
+    });
+    results.syncedSkills = sync.installed;
+    results.notes.push(...sync.notes);
+  }
+
+  const status = await getWorkshopSyncStatus({ rootPath: absoluteRoot });
+  results.artifactStatus = status.summary;
+  return results;
+}
+
+export async function getWorkshopSyncStatus({ rootPath = process.cwd() }) {
+  const state = await loadWorkshopState(rootPath);
+  const index = await buildArtifactIndex(state);
+  await writeJson(resolveLayout(state.rootPath).indexFile, index);
+  return {
+    rootPath: state.rootPath,
+    rootType: state.rootType,
+    summary: summarizeIndex(index),
+    entries: index.entries,
+  };
+}
+
+export async function pullWorkshopArtifacts({ requestWorkshop, rootPath = process.cwd() }) {
+  const state = await loadWorkshopState(rootPath);
+  const artifactRefs = await listArtifactRefs(requestWorkshop, state);
+  const notes = [];
+  const downloaded = [];
+
+  for (const ref of artifactRefs) {
+    const detail = await requestWorkshop({
+      path: `/api/v1/artifacts/${ref.id}`,
+    });
+    const materialized = await materializeArtifact({
+      rootPath: state.rootPath,
+      artifact: detail,
+      fallbackScope: ref.scope,
+      fallbackPath: ref.relativePath,
+    });
+    downloaded.push(materialized);
+  }
+
+  state.artifacts = mergeArtifactStates(state.artifacts, downloaded);
+  state.updatedAt = new Date().toISOString();
+  await writeStateFiles(state.rootPath, state);
+  const index = await buildArtifactIndex(state);
+  await writeJson(resolveLayout(state.rootPath).indexFile, index);
+
+  return {
+    rootPath: state.rootPath,
+    downloaded: downloaded.length,
+    notes,
+    summary: summarizeIndex(index),
+  };
+}
+
+export async function pushWorkshopArtifacts({ requestWorkshop, rootPath = process.cwd() }) {
+  const state = await loadWorkshopState(rootPath);
+  const index = await buildArtifactIndex(state);
+  const modified = index.entries.filter((entry) => entry.status === 'modified');
+  const missing = modified.filter((entry) => entry.remoteRevisionNo === null);
+  if (missing.length > 0) {
+    throw new CliError(
+      'Cannot push modified artifacts without known remote revision numbers. Re-run `workshop sync pull` first.',
+    );
+  }
+
+  const pushed = [];
+  for (const entry of modified) {
+    const absolutePath = path.join(state.rootPath, entry.relativePath);
+    const content = await fs.readFile(absolutePath, 'utf8');
+    const requestBody = buildRevisionRequest(entry, content);
+    await requestWorkshop({
+      method: 'POST',
+      path: `/api/v1/artifacts/${entry.id}/revisions`,
+      body: requestBody,
+    });
+    pushed.push(entry.id);
+  }
+
+  const refreshed = await pullWorkshopArtifacts({ requestWorkshop, rootPath: state.rootPath });
+  return {
+    rootPath: state.rootPath,
+    pushed,
+    pushedCount: pushed.length,
+    pulledAfterPush: refreshed.downloaded,
+    summary: refreshed.summary,
+  };
+}
+
+export async function syncWorkshopSkills({
+  requestWorkshop,
+  rootPath = process.cwd(),
+  role,
+  skillsRepoUrl = '',
+  skillsRepoRef = 'main',
+}) {
+  const state = await loadWorkshopState(rootPath);
+  const effectiveRole = role || state.role || 'worker';
+  state.role = effectiveRole;
+  const skills = await resolveRequiredSkills({
+    requestWorkshop,
+    state,
+    role: effectiveRole,
+  });
+  const notes = [];
+
+  if (skills.length === 0) {
+    throw new CliError('No required skills were resolved for this workspace/project role.');
+  }
+
+  const source = skillsRepoUrl
+    ? await cloneSkillsSource(skillsRepoUrl, skillsRepoRef)
+    : { rootPath: detectBundledSkillsRoot(), source: 'bundled', revision: 'bundled' };
+  if (!skillsRepoUrl) {
+    notes.push('Using bundled skill source. Set --skills-repo URL to pull from an official remote repository.');
+  }
+
+  const installed = [];
+  try {
+    for (const skill of skills) {
+      const skillName = normalizeSkillName(skill);
+      const sourcePath = await findSkillPath(source.rootPath, skillName);
+      const destination = path.join(resolveLayout(state.rootPath).skillsRoot, effectiveRole, skillName);
+      await fs.rm(destination, { recursive: true, force: true });
+      await copyDirectory(sourcePath, destination);
+      installed.push({
+        name: skillName,
+        role: effectiveRole,
+        path: path.relative(state.rootPath, destination),
+        source: source.source,
+        revision: source.revision,
+        installedAt: new Date().toISOString(),
+      });
+    }
+  } finally {
+    if (source.cleanup) {
+      await source.cleanup();
+    }
+  }
+
+  state.skills = mergeSkillStates(state.skills, installed, effectiveRole);
+  state.updatedAt = new Date().toISOString();
+  await writeStateFiles(state.rootPath, state);
+  return {
+    rootPath: state.rootPath,
+    role: effectiveRole,
+    installed: installed.length,
+    skills: installed,
+    notes,
+  };
+}
+
+export async function loadWorkshopState(rootPath = process.cwd()) {
+  const absoluteRoot = path.resolve(rootPath);
+  const layout = resolveLayout(absoluteRoot);
+  const state = await readJson(layout.stateFile, 'Local Workshop state not found. Run `losclaws workshop init ...` first.');
+  return normalizeState(state, absoluteRoot);
+}
+
+export async function buildArtifactIndex(state) {
+  const entries = [];
+  for (const artifact of state.artifacts) {
+    const absolutePath = path.join(state.rootPath, artifact.relativePath);
+    let status = 'missing';
+    let currentHash = null;
+    try {
+      const buffer = await fs.readFile(absolutePath);
+      currentHash = hashBuffer(buffer);
+      status = currentHash === artifact.lastSyncedHash ? 'clean' : 'modified';
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+    entries.push({
+      id: artifact.id,
+      relativePath: artifact.relativePath,
+      status,
+      currentHash,
+      lastSyncedHash: artifact.lastSyncedHash || null,
+      remoteRevisionNo: asNumberOrNull(artifact.remoteRevisionNo),
+      remoteVersion: asNumberOrNull(artifact.remoteVersion),
+      contentKind: artifact.contentKind || 'text',
+    });
+  }
+
+  const knownPaths = new Set(entries.map((entry) => entry.relativePath));
+  const discovered = await listFiles(resolveLayout(state.rootPath).artifactsRoot);
+  for (const absoluteFile of discovered) {
+    const relativePath = path.relative(state.rootPath, absoluteFile);
+    if (!knownPaths.has(relativePath)) {
+      const currentHash = hashBuffer(await fs.readFile(absoluteFile));
+      entries.push({
+        id: null,
+        relativePath,
+        status: 'untracked',
+        currentHash,
+        lastSyncedHash: null,
+        remoteRevisionNo: null,
+        remoteVersion: null,
+        contentKind: 'text',
+      });
+    }
+  }
+
+  return {
+    version: localVersion,
+    generatedAt: new Date().toISOString(),
+    summary: summarizeIndex({ entries }),
+    entries: entries.sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
+  };
+}
+
+export function summarizeIndex(index) {
+  const summary = {
+    clean: 0,
+    modified: 0,
+    missing: 0,
+    untracked: 0,
+    total: index.entries.length,
+  };
+  for (const entry of index.entries) {
+    if (entry.status in summary) {
+      summary[entry.status] += 1;
+    }
+  }
+  return summary;
+}
+
+function resolveLayout(rootPath) {
+  const metaRoot = path.join(rootPath, metaDirectoryName);
+  return {
+    rootPath,
+    metaRoot,
+    stateFile: path.join(metaRoot, 'state.json'),
+    workspaceFile: path.join(metaRoot, 'workspace.json'),
+    projectFile: path.join(metaRoot, 'project.json'),
+    manifestFile: path.join(metaRoot, 'manifest.json'),
+    indexFile: path.join(metaRoot, 'index.json'),
+    artifactsRoot: path.join(rootPath, 'artifacts'),
+    skillsRoot: path.join(rootPath, 'skills'),
+    objectsRoot: path.join(metaRoot, 'objects'),
+  };
+}
+
+async function ensureLayout(rootPath) {
+  const layout = resolveLayout(rootPath);
+  await Promise.all([
+    fs.mkdir(layout.metaRoot, { recursive: true }),
+    fs.mkdir(layout.artifactsRoot, { recursive: true }),
+    fs.mkdir(layout.skillsRoot, { recursive: true }),
+    fs.mkdir(layout.objectsRoot, { recursive: true }),
+  ]);
+  return layout;
+}
+
+async function writeStateFiles(rootPath, state) {
+  const layout = await ensureLayout(rootPath);
+  const normalized = normalizeState(state, rootPath);
+  await writeJson(layout.stateFile, normalized);
+  await writeJson(layout.workspaceFile, normalized.workspace || null);
+  await writeJson(layout.projectFile, normalized.project || null);
+  await writeJson(layout.manifestFile, {
+    version: localVersion,
+    rootType: normalized.rootType,
+    role: normalized.role,
+    workspace: normalized.workspace,
+    project: normalized.project,
+    artifacts: normalized.artifacts,
+    skills: normalized.skills,
+    updatedAt: normalized.updatedAt,
+  });
+}
+
+async function writeJson(filePath, value) {
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+async function readJson(filePath, notFoundMessage) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new CliError(notFoundMessage || `File not found: ${filePath}`);
+    }
+    if (error instanceof SyntaxError) {
+      throw new CliError(`Invalid JSON at ${filePath}.`);
+    }
+    throw error;
+  }
+}
+
+function normalizeState(state, rootPath) {
+  return {
+    version: Number(state.version) || localVersion,
+    rootType: state.rootType === 'project' ? 'project' : 'workspace',
+    rootPath: path.resolve(rootPath || state.rootPath || process.cwd()),
+    role: String(state.role || 'worker'),
+    workspace: state.workspace ? normalizeIdentity(state.workspace) : null,
+    project: state.project ? normalizeIdentity(state.project) : null,
+    artifacts: normalizeArtifacts(state.artifacts || []),
+    skills: normalizeSkills(state.skills || []),
+    updatedAt: state.updatedAt || new Date().toISOString(),
+  };
+}
+
+function normalizeIdentity(value) {
+  const id = String(value?.id || value?.workspaceId || value?.projectId || '');
+  if (!id) {
+    throw new CliError('Workspace/project payload does not include an id.');
+  }
+  return {
+    id,
+    name: String(value?.name || ''),
+    slug: String(value?.slug || ''),
+    version: asNumberOrNull(value?.version),
+  };
+}
+
+function normalizeArtifacts(values) {
+  return values
+    .map((entry) => ({
+      id: String(entry?.id || ''),
+      scope: entry?.scope === 'workspace' ? 'workspace' : 'project',
+      relativePath: normalizeRelativePath(entry?.relativePath || ''),
+      contentKind: entry?.contentKind || 'text',
+      mimeType: String(entry?.mimeType || ''),
+      lastSyncedHash: String(entry?.lastSyncedHash || ''),
+      remoteRevisionNo: asNumberOrNull(entry?.remoteRevisionNo),
+      remoteVersion: asNumberOrNull(entry?.remoteVersion),
+      updatedAt: entry?.updatedAt || new Date().toISOString(),
+    }))
+    .filter((entry) => entry.id && entry.relativePath);
+}
+
+function normalizeSkills(values) {
+  return values
+    .map((entry) => ({
+      name: String(entry?.name || ''),
+      role: String(entry?.role || 'worker'),
+      path: normalizeRelativePath(entry?.path || ''),
+      source: String(entry?.source || 'unknown'),
+      revision: String(entry?.revision || ''),
+      installedAt: entry?.installedAt || new Date().toISOString(),
+    }))
+    .filter((entry) => entry.name && entry.path);
+}
+
+async function listArtifactRefs(requestWorkshop, state) {
+  const refs = [];
+  if (state.workspace?.id) {
+    refs.push(
+      ...(await tryArtifactRefEndpoint(
+        requestWorkshop,
+        `/api/v1/workspaces/${state.workspace.id}/artifacts`,
+        { workspaceId: state.workspace.id },
+        'workspace',
+      )),
+    );
+  }
+  if (state.project?.id) {
+    refs.push(
+      ...(await tryArtifactRefEndpoint(
+        requestWorkshop,
+        `/api/v1/projects/${state.project.id}/artifacts`,
+        { projectId: state.project.id },
+        'project',
+      )),
+    );
+  }
+  if (refs.length === 0) {
+    throw new CliError('No remote artifacts were returned for this workspace/project.');
+  }
+  return dedupeById(refs);
+}
+
+async function tryArtifactRefEndpoint(requestWorkshop, endpoint, fallbackQuery, scope) {
+  const direct = await tryArtifactRefRequest(requestWorkshop, { path: endpoint });
+  const fallback = direct.length > 0
+    ? []
+    : await tryArtifactRefRequest(requestWorkshop, { path: '/api/v1/artifacts', query: fallbackQuery });
+  const entries = direct.length > 0 ? direct : fallback;
+  return entries
+    .map((entry) => {
+      const id = String(entry?.id || entry?.artifactId || '');
+      if (!id) {
+        return null;
+      }
+      return {
+        id,
+        scope,
+        relativePath: normalizeRelativePath(
+          entry?.path ||
+            entry?.relativePath ||
+            entry?.filePath ||
+            `${scope}/${id}.${entry?.contentKind === 'json' ? 'json' : 'txt'}`,
+        ),
+      };
+    })
+    .filter(Boolean);
+}
+
+async function tryArtifactRefRequest(requestWorkshop, request) {
+  try {
+    const result = await requestWorkshop(request);
+    return Array.isArray(result) ? result : Array.isArray(result?.items) ? result.items : [];
+  } catch (error) {
+    if (error instanceof CliError && (error.status === 404 || error.status === 405)) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+async function materializeArtifact({ rootPath, artifact, fallbackScope, fallbackPath }) {
+  const id = String(artifact?.id || artifact?.artifactId || '');
+  if (!id) {
+    throw new CliError('Artifact payload does not include an id.');
+  }
+  const scope = normalizeScope(artifact?.scope, fallbackScope);
+  const relativePath = normalizeRelativePath(
+    artifact?.path || artifact?.relativePath || artifact?.filePath || fallbackPath || `${scope}/${id}.txt`,
+  );
+  const absolutePath = path.join(rootPath, relativePath);
+  await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+
+  const content = extractArtifactContent(artifact);
+  await fs.writeFile(absolutePath, content.buffer);
+  const hash = hashBuffer(content.buffer);
+
+  return {
+    id,
+    scope,
+    relativePath,
+    contentKind: content.kind,
+    mimeType: artifact?.mimeType || artifact?.mime_type || content.mimeType,
+    lastSyncedHash: hash,
+    remoteRevisionNo: asNumberOrNull(
+      artifact?.latestRevisionNo ?? artifact?.latest_revision_no ?? artifact?.revisionNo ?? artifact?.revision_no,
+    ),
+    remoteVersion: asNumberOrNull(artifact?.version),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function extractArtifactContent(artifact) {
+  if (typeof artifact?.bodyText === 'string') {
+    return { kind: 'text', mimeType: 'text/plain', buffer: Buffer.from(artifact.bodyText, 'utf8') };
+  }
+  if (artifact?.bodyJson !== undefined) {
+    return {
+      kind: 'json',
+      mimeType: 'application/json',
+      buffer: Buffer.from(`${JSON.stringify(artifact.bodyJson, null, 2)}\n`, 'utf8'),
+    };
+  }
+  if (typeof artifact?.bodyBase64 === 'string') {
+    return { kind: 'base64', mimeType: 'application/octet-stream', buffer: Buffer.from(artifact.bodyBase64, 'base64') };
+  }
+
+  const latest = artifact?.latestRevision || artifact?.latest_revision || null;
+  if (latest) {
+    return extractArtifactContent(latest);
+  }
+
+  if (Array.isArray(artifact?.revisions) && artifact.revisions.length > 0) {
+    return extractArtifactContent(artifact.revisions[artifact.revisions.length - 1]);
+  }
+
+  if (typeof artifact?.content === 'string') {
+    return { kind: 'text', mimeType: 'text/plain', buffer: Buffer.from(artifact.content, 'utf8') };
+  }
+
+  return {
+    kind: 'json',
+    mimeType: 'application/json',
+    buffer: Buffer.from(`${JSON.stringify(artifact, null, 2)}\n`, 'utf8'),
+  };
+}
+
+function mergeArtifactStates(existing, downloaded) {
+  const map = new Map(existing.map((entry) => [entry.id, entry]));
+  for (const artifact of downloaded) {
+    map.set(artifact.id, artifact);
+  }
+  return [...map.values()].sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+
+function mergeSkillStates(existing, installed, role) {
+  const retained = existing.filter((entry) => entry.role !== role);
+  return [...retained, ...installed].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function buildRevisionRequest(entry, content) {
+  if (entry.contentKind === 'json') {
+    return {
+      expectedVersion: entry.remoteVersion,
+      contentKind: 'json',
+      baseRevisionNo: entry.remoteRevisionNo,
+      bodyJson: JSON.parse(content),
+    };
+  }
+  return {
+    expectedVersion: entry.remoteVersion,
+    contentKind: 'text',
+    baseRevisionNo: entry.remoteRevisionNo,
+    bodyText: content,
+  };
+}
+
+async function resolveRequiredSkills({ requestWorkshop, state, role }) {
+  const result = await requestWorkshop({
+    method: 'POST',
+    path: '/api/v1/skills/resolve',
+    body: {
+      role,
+      workspaceId: state.workspace?.id || null,
+      projectId: state.project?.id || null,
+    },
+  });
+
+  const entries = Array.isArray(result)
+    ? result
+    : Array.isArray(result?.skills)
+      ? result.skills
+      : Array.isArray(result?.items)
+        ? result.items
+        : [];
+  return entries.map(normalizeSkillName).filter(Boolean);
+}
+
+function normalizeSkillName(skill) {
+  return String(typeof skill === 'string' ? skill : skill?.name || skill?.key || '').trim();
+}
+
+function detectBundledSkillsRoot() {
+  const modulePath = new URL('../skill', import.meta.url);
+  return path.resolve(fileURLToPath(modulePath));
+}
+
+async function cloneSkillsSource(repoUrl, ref) {
+  const tempDirectory = await fs.mkdtemp(path.join(os.tmpdir(), 'losclaws-skills-'));
+  const cloneTarget = path.join(tempDirectory, 'skills-repo');
+  await execFileAsync('git', ['clone', '--depth', '1', '--branch', ref, repoUrl, cloneTarget], {
+    windowsHide: true,
+  });
+  const root = await exists(path.join(cloneTarget, 'skill')) ? path.join(cloneTarget, 'skill') : cloneTarget;
+  return {
+    source: 'official-repo',
+    revision: ref,
+    rootPath: root,
+    cleanup: async () => fs.rm(tempDirectory, { recursive: true, force: true }),
+  };
+}
+
+async function findSkillPath(skillsRoot, skillName) {
+  const direct = path.join(skillsRoot, skillName);
+  if (await exists(path.join(direct, 'SKILL.md'))) {
+    return direct;
+  }
+  const nested = path.join(skillsRoot, 'skills', skillName);
+  if (await exists(path.join(nested, 'SKILL.md'))) {
+    return nested;
+  }
+  throw new CliError(`Required skill "${skillName}" was not found in the selected skill source.`);
+}
+
+async function copyDirectory(source, destination) {
+  await fs.mkdir(destination, { recursive: true });
+  const entries = await fs.readdir(source, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = path.join(source, entry.name);
+    const to = path.join(destination, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(from, to);
+    } else {
+      await fs.copyFile(from, to);
+    }
+  }
+}
+
+async function listFiles(rootPath) {
+  if (!(await exists(rootPath))) {
+    return [];
+  }
+  const results = [];
+  const stack = [rootPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const next = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(next);
+      } else {
+        results.push(next);
+      }
+    }
+  }
+  return results;
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function hashBuffer(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function normalizeScope(value, fallback) {
+  if (value === 'workspace' || value === 'project') {
+    return value;
+  }
+  return fallback === 'workspace' ? 'workspace' : 'project';
+}
+
+function normalizeRelativePath(value) {
+  const normalized = String(value || '')
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '');
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.includes('../')) {
+    throw new CliError(`Invalid artifact/skill relative path: ${value}`);
+  }
+  return normalized;
+}
+
+function extractWorkspaceId(project) {
+  return String(project?.workspaceId || project?.workspace_id || project?.workspace?.id || '');
+}
+
+function dedupeById(values) {
+  const seen = new Map();
+  for (const value of values) {
+    seen.set(value.id, value);
+  }
+  return [...seen.values()];
+}
+
+function asNumberOrNull(value) {
+  if (value === null || value === undefined || value === '') {
+    return null;
+  }
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}