@constraint/cli 0.2.0

package/src/cli.js

@@ -0,0 +1,405 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+
+import { apiRequest, jsonRequest } from './api.js';
+import { rejectUnknown, takeFlag, takeOption } from './arguments.js';
+import { login, logout } from './auth.js';
+import { loadConfig } from './config.js';
+import { mediaType } from './files.js';
+import { AGENTS, detectAgents, findProjectRoot, normalizeAgent } from './paths.js';
+import {
+  begin,
+  chooseAgents,
+  chooseMode,
+  chooseScope,
+  confirmPlan,
+  finish,
+  note,
+  taskSpinner,
+} from './prompts.js';
+import { setupAgent, setupStatus } from './setup.js';
+import {
+  configuredAgents,
+  installSkill,
+  installedSkills,
+  manageableDomains,
+  readTranscript,
+  updateAll,
+  uploadSkill,
+} from './skills.js';
+
+const VERSION = '0.2.0';
+
+const HELP = `Constraint Skills CLI
+
+Usage:
+  constraint login | logout | whoami
+  constraint setup [--agent codex|claude-code]... [--dry-run] [--yes]
+  constraint doctor [--agent codex|claude-code]...
+  constraint skills list [--search <text>]
+  constraint skills list --installed [--project|--global] [--agent <agent>]...
+  constraint skills inspect <skill> [--version <version>] [--files]
+  constraint skills install <skill> [--version <version>] [--agent <agent>]...
+                            [--project|--global] [--copy] [--yes]
+  constraint skills update <skill> [--agent <agent>]... [--project|--global]
+                           [--copy] [--yes]
+  constraint skills update --all [--agent <agent>]... [--project|--global] [--yes]
+  constraint skills upload <path>
+  constraint skills run start <skill> --client <client> --session <session-id>
+  constraint skills run complete <run-id> <transcript-path>
+  constraint skills run list [--team <team>]... [--user <user>]... [--skill <skill>]...
+  constraint skills run get <run-id>... [--raw] [--output <path>]
+
+Global options: --json --quiet --no-color --help --version`;
+
+function globals(args) {
+  const copy = [...args];
+  return {
+    args: copy.filter((value) => !['--json', '--quiet', '--no-color'].includes(value)),
+    json: copy.includes('--json'),
+    quiet: copy.includes('--quiet'),
+    noColor: copy.includes('--no-color'),
+  };
+}
+
+function printer(options) {
+  return {
+    line(value) {
+      if (!options.quiet) process.stdout.write(`${typeof value === 'string' ? value : JSON.stringify(value, null, 2)}\n`);
+    },
+    data(value) {
+      if (!options.quiet) process.stdout.write(`${JSON.stringify(value, null, options.json ? 0 : 2)}\n`);
+    },
+  };
+}
+
+function interactive(out) {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY && !out.json && !out.quiet);
+}
+
+function takeScope(args) {
+  const project = takeFlag(args, '--project');
+  const global = takeFlag(args, '--global');
+  if (project && global) throw new Error('Pass either --project or --global, not both.');
+  return project ? 'project' : global ? 'global' : null;
+}
+
+function takeAgents(args) {
+  return takeOption(args, '--agent', { multiple: true }).map(normalizeAgent);
+}
+
+async function resolveAgents(provided, out, { prompt = true } = {}) {
+  if (provided.length) return [...new Set(provided)];
+  const configured = await configuredAgents();
+  const detected = configured.length ? configured : await detectAgents();
+  if (interactive(out) && prompt) return chooseAgents(detected);
+  if (detected.length) return detected;
+  throw new Error('No agent is configured. Pass --agent codex or --agent claude-code.');
+}
+
+async function chooseDomain(domains) {
+  if (domains.length === 0) throw new Error('You do not have permission to upload skills.');
+  if (domains.length === 1) return domains[0];
+  if (!process.stdin.isTTY) throw new Error('Upload has more than one permitted domain and requires an interactive terminal.');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  domains.forEach((domain, index) => process.stdout.write(`${index + 1}. ${domain}\n`));
+  const answer = await rl.question('Choose the skill domain: ');
+  rl.close();
+  const selected = domains[Number(answer) - 1];
+  if (!selected) throw new Error('Invalid domain selection.');
+  return selected;
+}
+
+async function authCommand(command, args, config, out) {
+  rejectUnknown(args);
+  if (args.length) throw new Error(`${command} does not accept positional arguments`);
+  if (command === 'login') {
+    const session = await login(config, out.line);
+    out.line(`Logged in as ${session.user?.email || session.user?.id || 'Constraint user'}.`);
+  } else if (command === 'logout') {
+    await logout(config);
+    out.line('Logged out.');
+  } else {
+    out.data(await apiRequest(config, '/me'));
+  }
+}
+
+async function setupCommand(args, out) {
+  let agents = takeAgents(args);
+  const dryRun = takeFlag(args, '--dry-run');
+  const yes = takeFlag(args, '--yes');
+  rejectUnknown(args);
+  if (args.length) throw new Error('setup does not accept positional arguments');
+  const useUi = interactive(out) && !dryRun;
+  if (useUi) begin('Constraint Skills setup');
+  if (!agents.length) {
+    const configured = await configuredAgents();
+    const detected = configured.length ? configured : await detectAgents();
+    agents = useUi && !yes ? await chooseAgents(detected) : detected;
+  }
+  if (!agents.length) throw new Error('Choose at least one agent with --agent.');
+  const results = [];
+  for (const agent of agents) {
+    results.push(await setupAgent(agent, {
+      dryRun,
+      yes,
+      output: useUi ? () => {} : out.line,
+      confirmChange: confirmPlan,
+    }));
+  }
+  if (useUi) finish(`Constraint Skills configured for ${agents.join(' and ')}.`);
+  else out.data(results);
+}
+
+async function doctorCommand(args, config, out) {
+  let agents = takeAgents(args);
+  rejectUnknown(args);
+  if (args.length) throw new Error('doctor does not accept positional arguments');
+  if (!agents.length) agents = AGENTS;
+  let identity = null;
+  let authError = null;
+  try {
+    identity = await apiRequest(config, '/me');
+  } catch (error) {
+    authError = error.message;
+  }
+  out.data({
+    api_url: config.apiUrl,
+    authenticated: Boolean(identity),
+    identity,
+    auth_error: authError,
+    agents: await Promise.all(agents.map(setupStatus)),
+  });
+}
+
+async function listSkills(args, config, out) {
+  const search = takeOption(args, '--search');
+  const installed = takeFlag(args, '--installed');
+  const scopeFlag = takeScope(args);
+  const agents = takeAgents(args);
+  rejectUnknown(args);
+  if (args.length) throw new Error('skills list does not accept positional arguments');
+  if (installed) {
+    if (search) throw new Error('--search cannot be combined with --installed.');
+    out.data(await installedSkills({ scope: scopeFlag || 'project', agents }));
+    return;
+  }
+  if (scopeFlag || agents.length) throw new Error('--project, --global, and --agent require --installed.');
+  const query = search ? `?search=${encodeURIComponent(search)}` : '';
+  out.data(await apiRequest(config, `/skills${query}`));
+}
+
+async function inspectSkill(args, config, out) {
+  const version = takeOption(args, '--version');
+  const files = takeFlag(args, '--files');
+  rejectUnknown(args);
+  if (args.length !== 1) throw new Error('Usage: constraint skills inspect <skill>');
+  const suffix = version ? `/versions/${encodeURIComponent(version)}` : '';
+  const detail = await apiRequest(config, `/skills/${encodeURIComponent(args[0])}${suffix}`);
+  if (!files) detail.version.files = [];
+  out.data(detail);
+}
+
+async function installCommand(args, config, out, update = false) {
+  const version = takeOption(args, '--version');
+  let agents = takeAgents(args);
+  let scope = takeScope(args);
+  const copyRequested = takeFlag(args, '--copy');
+  let copy = copyRequested ? true : update ? undefined : false;
+  const yes = takeFlag(args, '--yes');
+  rejectUnknown(args);
+  if (args.length !== 1) throw new Error(`Usage: constraint skills ${update ? 'update' : 'install'} <skill>`);
+  const useUi = interactive(out);
+  if (useUi) begin(update ? 'Update a Constraint skill' : 'Install a Constraint skill');
+  if (!scope) scope = useUi && !yes ? await chooseScope() : 'project';
+  const root = scope === 'project' ? await findProjectRoot() : null;
+  if (update && !agents.length) {
+    const installed = await installedSkills({ scope, projectRoot: root });
+    agents = [...new Set(installed
+      .filter((item) => item.skill_id === args[0] || item.slug === args[0])
+      .map((item) => item.agent))];
+  }
+  agents = await resolveAgents(agents, out, { prompt: !yes && !update });
+  if (!copyRequested && useUi && !yes) copy = (await chooseMode()) === 'copy';
+  if (useUi) {
+    note([
+      `${update ? 'Update' : 'Install'}: ${args[0]}${version ? ` v${version}` : ' (latest)'}`,
+      `Agents: ${agents.join(', ')}`,
+      `Scope: ${scope}${root ? ` (${root})` : ''}`,
+      `Mode: ${copy === undefined ? 'preserve installed mode' : copy ? 'copy' : 'shared package'}`,
+    ].join('\n'));
+    if (!yes && !(await confirmPlan(`${update ? 'Update' : 'Install'} this skill?`))) {
+      finish('No changes made.');
+      return;
+    }
+  }
+  const spinner = taskSpinner(useUi);
+  const results = await installSkill(config, args[0], {
+    version: version ? Number(version) : undefined,
+    agents,
+    scope,
+    projectRoot: root,
+    copy,
+    update,
+    progress: (message) => spinner.message(message),
+  });
+  const data = results.map((result) => ({
+    skill: result.detail.slug,
+    version: result.detail.version.version,
+    agent: result.agent,
+    scope: result.scope,
+    mode: result.mode,
+    path: result.target,
+    changed: result.changed,
+  }));
+  if (useUi) {
+    spinner.stop(`${data[0].skill} v${data[0].version} installed.`);
+    finish(`Ready in ${agents.length} agent${agents.length === 1 ? '' : 's'}.`);
+  } else out.data(data.length === 1 ? data[0] : data);
+}
+
+async function updateCommand(args, config, out) {
+  const all = takeFlag(args, '--all');
+  if (!all) return installCommand(args, config, out, true);
+  const agents = takeAgents(args);
+  let scope = takeScope(args);
+  const yes = takeFlag(args, '--yes');
+  if (takeFlag(args, '--copy')) throw new Error('--copy is not used with update --all; each installed mode is preserved.');
+  rejectUnknown(args);
+  if (args.length) throw new Error('Pass either --all or a skill, not both.');
+  const useUi = interactive(out);
+  if (!scope) scope = useUi ? (begin('Update Constraint skills'), await chooseScope()) : 'project';
+  if (useUi && !yes && !(await confirmPlan(`Update all installed skills in ${scope} scope?`))) {
+    finish('No changes made.');
+    return;
+  }
+  const spinner = taskSpinner(useUi);
+  const results = await updateAll(config, {
+    agents,
+    scope,
+    progress: (message) => spinner.message(message),
+  });
+  const data = results.map((item) => ({
+    skill: item.detail.slug,
+    version: item.detail.version.version,
+    agent: item.agent,
+    scope: item.scope,
+    mode: item.mode,
+    changed: item.changed,
+  }));
+  if (useUi) {
+    spinner.stop(`Updated ${data.length} installation${data.length === 1 ? '' : 's'}.`);
+    finish('Skills are current.');
+  } else out.data(data);
+}
+
+async function uploadCommand(args, config, out) {
+  rejectUnknown(args);
+  if (args.length !== 1) throw new Error('Usage: constraint skills upload <path>');
+  const domain = await chooseDomain(await manageableDomains(config));
+  const detail = await uploadSkill(config, args[0], domain);
+  out.data({ skill_id: detail.skill_id, slug: detail.slug, domain: detail.domain, version: detail.version.version });
+}
+
+async function runStart(args, config, out) {
+  const client = takeOption(args, '--client');
+  const session = takeOption(args, '--session');
+  rejectUnknown(args);
+  if (args.length !== 1 || !client || !session) {
+    throw new Error('Usage: constraint skills run start <skill> --client <client> --session <session-id>');
+  }
+  const run = await apiRequest(config, '/skill-runs', {
+    method: 'POST',
+    ...jsonRequest({ skill: args[0], client, session_id: session }),
+  });
+  if (out.json) out.data(run);
+  else out.line(run.run_id);
+}
+
+async function runComplete(args, config, out) {
+  rejectUnknown(args);
+  if (args.length !== 2) throw new Error('Usage: constraint skills run complete <run-id> <transcript-path>');
+  const transcript = await readTranscript(args[1]);
+  const run = await apiRequest(config, `/skill-runs/${encodeURIComponent(args[0])}/complete`, {
+    method: 'POST',
+    headers: { 'Content-Type': mediaType(transcript.absolute), 'X-Transcript-Filename': transcript.filename },
+    body: transcript.content,
+  });
+  out.data(run);
+}
+
+async function runList(args, config, out) {
+  const query = new URLSearchParams();
+  for (const value of takeOption(args, '--team', { multiple: true })) query.append('team', value);
+  for (const value of takeOption(args, '--user', { multiple: true })) query.append('user', value);
+  for (const value of takeOption(args, '--skill', { multiple: true })) query.append('skill', value);
+  for (const name of ['--after', '--before', '--limit', '--cursor']) {
+    const value = takeOption(args, name);
+    if (value) query.set(name.slice(2), value);
+  }
+  rejectUnknown(args);
+  if (args.length) throw new Error('skills run list does not accept positional arguments');
+  out.data(await apiRequest(config, `/skill-runs?${query.toString()}`));
+}
+
+async function runGet(args, config, out) {
+  const raw = takeFlag(args, '--raw');
+  const output = takeOption(args, '--output');
+  rejectUnknown(args);
+  if (!args.length) throw new Error('Usage: constraint skills run get <run-id>...');
+  if (raw && args.length !== 1) throw new Error('--raw accepts exactly one run ID');
+  if (raw) {
+    const response = await apiRequest(config, `/skill-runs/${encodeURIComponent(args[0])}/transcript`, { rawResponse: true });
+    const content = Buffer.from(await response.arrayBuffer());
+    if (output) await fs.writeFile(path.resolve(output), content);
+    else process.stdout.write(content);
+    return;
+  }
+  const runs = await Promise.all(args.map((runId) => apiRequest(config, `/skill-runs/${encodeURIComponent(runId)}`)));
+  const value = runs.length === 1 ? runs[0] : runs;
+  if (output) await fs.writeFile(path.resolve(output), `${JSON.stringify(value, null, 2)}\n`);
+  else out.data(value);
+}
+
+async function runCommand(args, config, out) {
+  const command = args.shift();
+  if (command === 'start') return runStart(args, config, out);
+  if (command === 'complete') return runComplete(args, config, out);
+  if (command === 'list') return runList(args, config, out);
+  if (command === 'get') return runGet(args, config, out);
+  throw new Error('Expected skills run start, complete, list, or get.');
+}
+
+async function skillsCommand(args, config, out) {
+  const command = args.shift();
+  if (command === 'list') return listSkills(args, config, out);
+  if (command === 'inspect') return inspectSkill(args, config, out);
+  if (command === 'install') return installCommand(args, config, out);
+  if (command === 'update') return updateCommand(args, config, out);
+  if (command === 'upload') return uploadCommand(args, config, out);
+  if (command === 'run') return runCommand(args, config, out);
+  throw new Error('Expected skills list, inspect, install, update, upload, or run.');
+}
+
+export async function main(argv) {
+  if (argv.length === 1 && argv[0] === '--version') {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+  if (!argv.length || (argv.length === 1 && ['--help', '-h'].includes(argv[0]))) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  const options = globals(argv);
+  if (options.noColor) process.env.NO_COLOR = '1';
+  const args = options.args;
+  const out = { ...printer(options), ...options };
+  const command = args.shift();
+  const config = await loadConfig();
+  if (['login', 'logout', 'whoami'].includes(command)) return authCommand(command, args, config, out);
+  if (command === 'setup') return setupCommand(args, out);
+  if (command === 'doctor') return doctorCommand(args, config, out);
+  if (command === 'skills') return skillsCommand(args, config, out);
+  throw new Error(`Unknown command: ${command}`);
+}

package/src/config.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { configDirectory } from './paths.js';
+
+const DEFAULT_API_URL = 'https://api-production-3183d.up.railway.app';
+
+export async function readJson(file, fallback) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return fallback;
+    throw error;
+  }
+}
+
+export async function writeJson(file, value, { mode = 0o600 } = {}) {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode });
+  await fs.rename(temporary, file);
+  await fs.chmod(file, mode);
+}
+
+export async function loadConfig() {
+  const file = path.join(configDirectory(), 'config.json');
+  const saved = await readJson(file, {});
+  return {
+    apiUrl: (process.env.CONSTRAINT_API_URL || saved.apiUrl || DEFAULT_API_URL).replace(/\/$/, ''),
+    agents: Array.isArray(saved.agents) ? saved.agents : Array.isArray(saved.clients) ? saved.clients : [],
+  };
+}
+
+export async function saveConfig(config) {
+  await writeJson(path.join(configDirectory(), 'config.json'), config);
+}
+
+export async function loadInstallations() {
+  const value = await readJson(path.join(configDirectory(), 'installations.json'), { lockfile_version: 1, installations: {} });
+  if (value.installations) return value;
+  return { lockfile_version: 1, installations: value };
+}
+
+export async function saveInstallations(value) {
+  const normalized = value.installations ? value : { lockfile_version: 1, installations: value };
+  await writeJson(path.join(configDirectory(), 'installations.json'), normalized);
+}
+
+export async function loadProjectInstallations(projectRoot) {
+  return readJson(path.join(projectRoot, 'skills-lock.json'), { lockfile_version: 1, installations: {} });
+}
+
+export async function saveProjectInstallations(projectRoot, value) {
+  await writeJson(path.join(projectRoot, 'skills-lock.json'), value, { mode: 0o644 });
+}
+
+export async function fetchCliConfig(apiUrl) {
+  const response = await fetch(`${apiUrl}/cli/config`, { headers: { Accept: 'application/json' } });
+  if (!response.ok) throw new Error(`Could not load CLI configuration from ${apiUrl} (${response.status})`);
+  return response.json();
+}

package/src/files.js

@@ -0,0 +1,146 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MIME = {
+  '.md': 'text/markdown', '.json': 'application/json', '.jsonl': 'application/x-ndjson',
+  '.yaml': 'application/yaml', '.yml': 'application/yaml', '.js': 'text/javascript',
+  '.mjs': 'text/javascript', '.ts': 'text/typescript', '.py': 'text/x-python',
+  '.txt': 'text/plain', '.svg': 'image/svg+xml', '.png': 'image/png',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.pdf': 'application/pdf',
+};
+
+export function mediaType(file) {
+  return MIME[path.extname(file).toLowerCase()] || 'application/octet-stream';
+}
+
+async function visit(root, current, files) {
+  const entries = await fs.readdir(current, { withFileTypes: true });
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const absolute = path.join(current, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`Skill packages may not contain symlinks: ${absolute}`);
+    if (entry.isDirectory()) await visit(root, absolute, files);
+    else if (entry.isFile()) {
+      files.push({
+        path: path.relative(root, absolute).split(path.sep).join('/'),
+        media_type: mediaType(absolute),
+        content: await fs.readFile(absolute),
+      });
+    }
+  }
+}
+
+export async function readSkillDirectory(input) {
+  let root = path.resolve(input);
+  const stat = await fs.stat(root);
+  if (stat.isFile() && path.basename(root) === 'SKILL.md') root = path.dirname(root);
+  else if (!stat.isDirectory()) throw new Error('Skill upload path must be a directory or SKILL.md');
+  const files = [];
+  await visit(root, root, files);
+  if (!files.some((file) => file.path === 'SKILL.md')) throw new Error('Skill directory requires a root SKILL.md');
+  return files;
+}
+
+export function packageDigest(files) {
+  const hash = crypto.createHash('sha256');
+  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+    hash.update(file.path);
+    hash.update('\0');
+    hash.update(file.content);
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+export async function writeSkillDirectory(target, files, { expectedHash = null, forceDirectory = false } = {}) {
+  try {
+    const targetStat = await fs.lstat(target);
+    const currentHash = packageDigest(await readSkillDirectory(target));
+    if (currentHash === packageDigest(files) && !(forceDirectory && targetStat.isSymbolicLink())) {
+      return { changed: false, hash: currentHash };
+    }
+    if (!expectedHash || currentHash !== expectedHash) {
+      throw new Error(`Local skill has uncommitted changes and was not replaced: ${target}`);
+    }
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
+  }
+
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const staging = `${target}.constraint-${process.pid}`;
+  const backup = `${target}.constraint-backup-${process.pid}`;
+  await fs.rm(staging, { recursive: true, force: true });
+  await fs.mkdir(staging, { recursive: true });
+  for (const file of files) {
+    const destination = path.join(staging, ...file.path.split('/'));
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    await fs.writeFile(destination, file.content);
+  }
+  let hadTarget = false;
+  try {
+    await fs.rename(target, backup);
+    hadTarget = true;
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
+  }
+  try {
+    await fs.rename(staging, target);
+    await fs.rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    if (hadTarget) await fs.rename(backup, target).catch(() => {});
+    throw error;
+  }
+  return { changed: true, hash: packageDigest(files) };
+}
+
+export async function assertManagedSkillUnchanged(target, expectedHash) {
+  if (!expectedHash) return;
+  let current;
+  try {
+    current = packageDigest(await readSkillDirectory(target));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') throw new Error(`Managed skill is missing and was not replaced: ${target}`);
+    throw error;
+  }
+  if (current !== expectedHash) throw new Error(`Local skill has uncommitted changes and was not replaced: ${target}`);
+}
+
+export async function linkSkillDirectory(target, source, { managed = false, expectedHash = null } = {}) {
+  let existing = null;
+  try {
+    existing = await fs.lstat(target);
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+  if (existing) {
+    if (!managed) throw new Error(`An unmanaged skill already exists and was not replaced: ${target}`);
+    await assertManagedSkillUnchanged(target, expectedHash);
+  }
+
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const staging = `${target}.constraint-link-${process.pid}`;
+  const backup = `${target}.constraint-backup-${process.pid}`;
+  await fs.rm(staging, { recursive: true, force: true });
+  const relative = path.relative(path.dirname(staging), source);
+  try {
+    await fs.symlink(relative, staging, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch (error) {
+    if (['EPERM', 'EACCES', 'ENOTSUP', 'EINVAL'].includes(error?.code)) return { supported: false, changed: false };
+    throw error;
+  }
+  let hadTarget = false;
+  try {
+    await fs.rename(target, backup);
+    hadTarget = true;
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+  try {
+    await fs.rename(staging, target);
+    await fs.rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    if (hadTarget) await fs.rename(backup, target).catch(() => {});
+    throw error;
+  }
+  return { supported: true, changed: true };
+}

package/src/paths.js

@@ -0,0 +1,83 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const AGENTS = ['codex', 'claude-code'];
+
+export function expandPath(value) {
+  if (value === '~') return os.homedir();
+  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
+  return path.resolve(value);
+}
+
+export function configDirectory() {
+  if (process.env.CONSTRAINT_CONFIG_DIR) return expandPath(process.env.CONSTRAINT_CONFIG_DIR);
+  if (process.platform === 'win32' && process.env.APPDATA) return path.join(process.env.APPDATA, 'Constraint');
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'constraint');
+}
+
+export function normalizeAgent(agent) {
+  const value = String(agent || '').trim().toLowerCase().replaceAll('_', '-');
+  if (value === 'claude') return 'claude-code';
+  if (AGENTS.includes(value)) return value;
+  throw new Error(`Unsupported agent: ${agent}. Expected codex or claude-code.`);
+}
+
+export function agentPaths(agent, { scope = 'global', projectRoot = process.cwd() } = {}) {
+  const selected = normalizeAgent(agent);
+  if (scope === 'project') {
+    if (selected === 'codex') {
+      return { skills: path.join(projectRoot, '.agents', 'skills'), instructions: null };
+    }
+    return { skills: path.join(projectRoot, '.claude', 'skills'), instructions: null };
+  }
+  if (selected === 'codex') {
+    const root = process.env.CODEX_HOME ? expandPath(process.env.CODEX_HOME) : path.join(os.homedir(), '.codex');
+    return { instructions: path.join(root, 'AGENTS.md'), skills: path.join(root, 'skills') };
+  }
+  return {
+    instructions: path.join(os.homedir(), '.claude', 'CLAUDE.md'),
+    skills: path.join(os.homedir(), '.claude', 'skills'),
+  };
+}
+
+async function exists(candidate) {
+  try {
+    await fs.stat(candidate);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function findProjectRoot(start = process.cwd()) {
+  let current = path.resolve(start);
+  while (true) {
+    if (await exists(path.join(current, '.git'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(start);
+    current = parent;
+  }
+}
+
+export async function detectAgents() {
+  const detected = [];
+  const codexRoot = process.env.CODEX_HOME ? expandPath(process.env.CODEX_HOME) : path.join(os.homedir(), '.codex');
+  if (await exists(codexRoot)) detected.push('codex');
+  if (await exists(path.join(os.homedir(), '.claude'))) detected.push('claude-code');
+  return detected;
+}
+
+export function workspaceId(projectRoot) {
+  const digest = crypto.createHash('sha256').update(path.resolve(projectRoot)).digest('hex').slice(0, 24);
+  return `ws_${digest}`;
+}
+
+export function canonicalSkillPath({ scope, projectRoot, skillId, slug, version }) {
+  if (scope === 'project') {
+    return path.join(projectRoot, '.constraint', 'skills', slug, `v${version}`);
+  }
+  return path.join(configDirectory(), 'skill-cache', skillId, `v${version}`);
+}