@constraint/cli 0.2.0

package/src/prompts.js

@@ -0,0 +1,83 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+
+import { AGENTS } from './paths.js';
+
+const AGENT_OPTIONS = [
+  { value: 'codex', label: 'Codex', hint: '.agents/skills or ~/.codex/skills' },
+  { value: 'claude-code', label: 'Claude Code', hint: '.claude/skills or ~/.claude/skills' },
+];
+
+function cancelled(value) {
+  if (!p.isCancel(value)) return value;
+  p.cancel('No changes made.');
+  throw new Error('Operation cancelled.');
+}
+
+export function begin(title) {
+  p.intro(pc.bgCyan(pc.black(` ${title} `)));
+}
+
+export async function chooseAgents(initial = []) {
+  const values = await p.autocompleteMultiselect({
+    message: 'Which agents should receive the skill?',
+    placeholder: 'Type to filter agents',
+    options: AGENT_OPTIONS,
+    initialValues: initial.filter((value) => AGENTS.includes(value)),
+    required: true,
+  });
+  return cancelled(values);
+}
+
+export async function chooseScope() {
+  return cancelled(await p.select({
+    message: 'Where should the skill be installed?',
+    options: [
+      { value: 'project', label: 'This project', hint: 'portable lockfile, repository-local skill' },
+      { value: 'global', label: 'Globally', hint: 'available in every project for this user' },
+    ],
+  }));
+}
+
+export async function chooseMode() {
+  return cancelled(await p.select({
+    message: 'How should agent directories reference the package?',
+    options: [
+      { value: 'symlink', label: 'Shared package', hint: 'recommended; one managed copy' },
+      { value: 'copy', label: 'Copy files', hint: 'use when links are unavailable' },
+    ],
+  }));
+}
+
+export async function confirmPlan(message) {
+  return cancelled(await p.confirm({ message, initialValue: true }));
+}
+
+export function taskSpinner(enabled = true) {
+  if (!enabled) return { message() {}, stop() {} };
+  const spinner = p.spinner();
+  let started = false;
+  return {
+    message(value) {
+      if (!started) {
+        spinner.start(value);
+        started = true;
+      } else spinner.message(value);
+    },
+    stop(value) {
+      if (started) spinner.stop(value);
+    },
+  };
+}
+
+export function finish(message) {
+  p.outro(pc.green(message));
+}
+
+export function note(message, title = 'Install plan') {
+  p.note(message, title);
+}
+
+export function warn(message) {
+  p.log.warn(message);
+}

package/src/setup.js

@@ -0,0 +1,94 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadConfig, saveConfig } from './config.js';
+import { packageDigest, readSkillDirectory, writeSkillDirectory } from './files.js';
+import { agentPaths, normalizeAgent } from './paths.js';
+
+export const BLOCK_START = '<!-- constraint-skills:start -->';
+export const BLOCK_END = '<!-- constraint-skills:end -->';
+
+const BLOCK = `${BLOCK_START}
+## Constraint Skills
+
+When invoking any installed Agent Skill, load and follow the global
+\`constraint-skills\` companion skill. It records the run with the Constraint
+CLI without modifying the invoked skill.
+${BLOCK_END}`;
+
+export function mergeInstructionBlock(existing) {
+  const start = existing.indexOf(BLOCK_START);
+  const end = existing.indexOf(BLOCK_END);
+  if ((start >= 0) !== (end >= 0)) {
+    throw new Error('The existing Constraint Skills instruction block is incomplete; fix it before running setup.');
+  }
+  if (start >= 0 && end >= start) {
+    return `${existing.slice(0, start)}${BLOCK}${existing.slice(end + BLOCK_END.length)}`;
+  }
+  const separator = existing.length === 0 ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${separator}${BLOCK}\n`;
+}
+
+async function writeInstructions(file, content, mode) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const staging = `${file}.constraint-${process.pid}`;
+  await fs.writeFile(staging, content, { mode });
+  await fs.rename(staging, file);
+}
+
+async function companionFiles() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return readSkillDirectory(path.resolve(here, '..', 'skills', 'constraint-skills'));
+}
+
+export async function setupAgent(agent, {
+  dryRun = false,
+  yes = false,
+  confirmChange = async () => false,
+  output = console.log,
+} = {}) {
+  const selected = normalizeAgent(agent);
+  const paths = agentPaths(selected);
+  let existing = '';
+  let instructionMode = 0o644;
+  try {
+    existing = await fs.readFile(paths.instructions, 'utf8');
+    instructionMode = (await fs.stat(paths.instructions)).mode & 0o777;
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
+  }
+  const merged = mergeInstructionBlock(existing);
+  output(`${selected}: ${paths.instructions}`);
+  if (dryRun) {
+    output(merged);
+    return { agent: selected, changed: merged !== existing, applied: false };
+  }
+  if (merged !== existing && !yes && !(await confirmChange(`Add the Constraint Skills block to ${paths.instructions}?`))) {
+    return { agent: selected, changed: true, applied: false };
+  }
+  const files = await companionFiles();
+  const config = await loadConfig();
+  config.companion_hashes ||= {};
+  const target = path.join(paths.skills, 'constraint-skills');
+  await writeSkillDirectory(target, files, { expectedHash: config.companion_hashes[selected] || null });
+  if (merged !== existing) await writeInstructions(paths.instructions, merged, instructionMode);
+  config.companion_hashes[selected] = packageDigest(files);
+  config.agents = [...new Set([...config.agents.map(normalizeAgent), selected])];
+  await saveConfig(config);
+  return { agent: selected, changed: merged !== existing, applied: true };
+}
+
+export async function setupStatus(agent) {
+  const selected = normalizeAgent(agent);
+  const paths = agentPaths(selected);
+  try {
+    const [instructions, skill] = await Promise.all([
+      fs.readFile(paths.instructions, 'utf8'),
+      fs.stat(path.join(paths.skills, 'constraint-skills', 'SKILL.md')),
+    ]);
+    return { agent: selected, instructions: instructions.includes(BLOCK_START), skill: skill.isFile() };
+  } catch {
+    return { agent: selected, instructions: false, skill: false };
+  }
+}

package/src/skills.js

@@ -0,0 +1,209 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { apiRequest, jsonRequest } from './api.js';
+import {
+  loadConfig,
+  loadInstallations,
+  loadProjectInstallations,
+  saveInstallations,
+  saveProjectInstallations,
+} from './config.js';
+import {
+  assertManagedSkillUnchanged,
+  linkSkillDirectory,
+  packageDigest,
+  readSkillDirectory,
+  writeSkillDirectory,
+} from './files.js';
+import {
+  agentPaths,
+  canonicalSkillPath,
+  findProjectRoot,
+  normalizeAgent,
+  workspaceId,
+} from './paths.js';
+
+export const DOMAINS = [
+  'sales_pipeline', 'content_audience', 'marketing_demand', 'offers_monetization',
+  'operations_team', 'partnerships_bd',
+];
+
+function filesFromDetail(detail) {
+  return detail.version.files.map((file) => ({
+    path: file.path,
+    media_type: file.media_type,
+    content: Buffer.from(file.content_base64, 'base64'),
+  }));
+}
+
+function installKey(agent, skillId) {
+  return `${agent}:${skillId}`;
+}
+
+function portablePath(value, scope, projectRoot) {
+  if (scope === 'global') return value;
+  return path.relative(projectRoot, value).split(path.sep).join('/');
+}
+
+async function loadLock(scope, projectRoot) {
+  return scope === 'global' ? loadInstallations() : loadProjectInstallations(projectRoot);
+}
+
+async function saveLock(scope, projectRoot, value) {
+  if (scope === 'global') return saveInstallations(value);
+  return saveProjectInstallations(projectRoot, value);
+}
+
+export async function uploadSkill(config, localPath, domain) {
+  const files = await readSkillDirectory(localPath);
+  return apiRequest(config, '/skills/uploads', {
+    method: 'POST',
+    ...jsonRequest({
+      domain,
+      files: files.map((file) => ({
+        path: file.path,
+        media_type: file.media_type,
+        content_base64: file.content.toString('base64'),
+      })),
+    }),
+  });
+}
+
+export async function manageableDomains(config) {
+  const actor = await apiRequest(config, '/me');
+  if (actor.permissions.includes('org.manage')) return DOMAINS;
+  return DOMAINS.filter((domain) => actor.permissions.includes(`${domain}.skill.manage`));
+}
+
+export async function configuredAgents() {
+  const config = await loadConfig();
+  return [...new Set(config.agents.map(normalizeAgent))];
+}
+
+export async function installSkill(config, identifier, {
+  version,
+  agents,
+  scope = 'project',
+  projectRoot,
+  copy = false,
+  update = false,
+  progress = () => {},
+} = {}) {
+  const suffix = version ? `/versions/${version}` : '';
+  const detail = await apiRequest(config, `/skills/${encodeURIComponent(identifier)}${suffix}?include_content=true`);
+  const root = scope === 'project' ? (projectRoot || await findProjectRoot()) : null;
+  const selectedAgents = [...new Set((agents || []).map(normalizeAgent))];
+  if (selectedAgents.length === 0) throw new Error('Choose at least one agent with --agent codex or --agent claude-code.');
+  const lock = await loadLock(scope, root);
+  lock.lockfile_version = 1;
+  lock.installations ||= {};
+  const packageFiles = filesFromDetail(detail);
+  const contentHash = packageDigest(packageFiles);
+  const canonical = copy === true ? null : canonicalSkillPath({
+    scope,
+    projectRoot: root,
+    skillId: detail.skill_id,
+    slug: detail.slug,
+    version: detail.version.version,
+  });
+
+  if (canonical) {
+    progress(`Staging ${detail.slug} v${detail.version.version}`);
+    await writeSkillDirectory(canonical, packageFiles);
+  }
+
+  const results = [];
+  for (const agent of selectedAgents) {
+    progress(`Installing for ${agent}`);
+    const key = installKey(agent, detail.skill_id);
+    const previous = lock.installations[key];
+    const target = path.join(agentPaths(agent, { scope, projectRoot: root }).skills, detail.slug);
+    if (update && !previous) throw new Error(`${detail.slug} is not installed for ${agent} in ${scope} scope.`);
+
+    const useCopy = copy === true || (copy === undefined && previous?.mode === 'copy');
+    let mode = useCopy ? 'copy' : 'symlink';
+    let changed = false;
+    if (useCopy) {
+      const result = await writeSkillDirectory(target, packageFiles, {
+        expectedHash: previous?.content_sha256 || null,
+        forceDirectory: true,
+      });
+      changed = result.changed;
+    } else {
+      if (previous) await assertManagedSkillUnchanged(target, previous.content_sha256);
+      const linked = await linkSkillDirectory(target, canonical, {
+        managed: Boolean(previous),
+        expectedHash: previous?.content_sha256 || null,
+      });
+      if (linked.supported) {
+        changed = linked.changed;
+      } else {
+        mode = 'copy';
+        const result = await writeSkillDirectory(target, packageFiles, {
+          expectedHash: previous?.content_sha256 || null,
+          forceDirectory: true,
+        });
+        changed = result.changed;
+      }
+    }
+
+    const receiptWorkspace = scope === 'project' ? workspaceId(root) : null;
+    lock.installations[key] = {
+      skill_id: detail.skill_id,
+      slug: detail.slug,
+      version: detail.version.version,
+      content_sha256: contentHash,
+      agent,
+      scope,
+      mode,
+      workspace_id: receiptWorkspace,
+      path: portablePath(target, scope, root),
+      canonical_path: canonical ? portablePath(canonical, scope, root) : null,
+    };
+    await saveLock(scope, root, lock);
+    const receipt = await apiRequest(config, `/skills/${encodeURIComponent(detail.skill_id)}/installations`, {
+      method: 'POST',
+      ...jsonRequest({
+        agent,
+        scope,
+        mode,
+        version: detail.version.version,
+        ...(receiptWorkspace ? { workspace_id: receiptWorkspace } : {}),
+      }),
+    });
+    results.push({ detail, agent, scope, mode, target, changed, receipt });
+  }
+  return results;
+}
+
+export async function updateAll(config, { agents, scope = 'project', projectRoot, progress } = {}) {
+  const root = scope === 'project' ? (projectRoot || await findProjectRoot()) : null;
+  const lock = await loadLock(scope, root);
+  const selected = agents?.length ? new Set(agents.map(normalizeAgent)) : null;
+  const entries = Object.values(lock.installations || {}).filter((item) => !selected || selected.has(item.agent));
+  const results = [];
+  for (const entry of entries) {
+    results.push(...await installSkill(config, entry.skill_id, {
+      agents: [entry.agent],
+      scope,
+      projectRoot: root,
+      copy: entry.mode === 'copy',
+      update: true,
+      progress,
+    }));
+  }
+  return results;
+}
+
+export async function installedSkills({ scope = 'project', projectRoot, agents } = {}) {
+  const root = scope === 'project' ? (projectRoot || await findProjectRoot()) : null;
+  const lock = await loadLock(scope, root);
+  const selected = agents?.length ? new Set(agents.map(normalizeAgent)) : null;
+  return Object.values(lock.installations || {}).filter((item) => !selected || selected.has(item.agent));
+}
+
+export async function readTranscript(file) {
+  const absolute = path.resolve(file);
+  return { absolute, filename: path.basename(absolute), content: await fs.readFile(absolute) };
+}