@constraint/cli 0.3.3 → 0.3.4

package/README.md

@@ -55,9 +55,11 @@ Or target agents explicitly:
 constraint setup --agent codex --agent claude-code
 ```
 
-Setup installs the `constraint-skills` companion skill and offers to add a
-marked Constraint block to the agent's global instructions. Existing
-`AGENTS.md` and `CLAUDE.md` content outside that block is preserved.
+Setup presents two separate stages: first it offers to add a marked Constraint
+block to each agent's global instructions, then it shows the global destination
+and installs the `constraint-skills` companion using the regular install-plan
+flow. Existing `AGENTS.md` and `CLAUDE.md` content outside that block is
+preserved.
 
 Preview the instruction change without applying it:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constraint/cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Install, publish, and report Agent Skills with Constraint",
   "type": "module",
   "bin": {

package/skills/constraint-skills/references/commands.md

@@ -12,7 +12,7 @@ constraint setup
 constraint doctor
 ```
 
-`login` uses WorkOS device authorization. Never request or embed an API key or client secret. `setup` detects Codex and Claude Code, installs this skill, and deterministically merges a marked global instruction block without replacing unrelated instructions.
+`login` uses WorkOS device authorization. Never request or embed an API key or client secret. `setup` detects Codex and Claude Code, then separately presents the managed global-instruction change and this skill's global installation destinations. It never replaces unrelated instructions.
 
 ## Discover, inspect, install, and update
 

package/src/cli.js

@@ -18,7 +18,12 @@ import {
   note,
   taskSpinner,
 } from './prompts.js';
-import { setupAgent, setupStatus } from './setup.js';
+import {
+  applyInstructionSetup,
+  installCompanionSkill,
+  setupPlan,
+  setupStatus,
+} from './setup.js';
 import {
   configuredAgents,
   installSkill,
@@ -30,7 +35,7 @@ import {
   uploadSkill,
 } from './skills.js';
 
-const VERSION = '0.3.3';
+const VERSION = '0.3.4';
 
 const HELP = `Constraint Skills CLI
 
@@ -236,17 +241,78 @@ async function setupCommand(args, out) {
     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,
-    }));
+  const plans = await Promise.all(agents.map(setupPlan));
+  const conflicts = plans.filter((plan) => plan.skill.action === 'conflict');
+  if (conflicts.length) {
+    throw new Error(`Local Constraint skill has uncommitted changes and was not replaced: ${conflicts.map((plan) => plan.skill.path).join(', ')}`);
+  }
+  if (dryRun) {
+    out.data(plans.map((plan) => ({
+      agent: plan.agent,
+      instructions: {
+        path: plan.instructions.path,
+        action: plan.instructions.changed ? 'update' : 'current',
+        content: plan.instructions.content,
+      },
+      skill: { path: plan.skill.path, scope: 'global', action: plan.skill.action },
+    })));
+    return;
+  }
+  const hasInstructionChanges = plans.some((plan) => plan.instructions.changed);
+  const hasSkillChanges = plans.some((plan) => plan.skill.action !== 'current');
+  if (!useUi && !yes && (hasInstructionChanges || hasSkillChanges)) {
+    throw new Error('Non-interactive setup has pending changes. Pass --yes or use --dry-run.');
+  }
+
+  let configureInstructions = true;
+  let installSkill = true;
+  if (useUi) {
+    note(
+      plans.map((plan) => `${humanize(plan.agent)}\n${plan.instructions.path}\n${plan.instructions.changed ? 'Managed block will be added or updated' : 'Already configured'}`).join('\n\n'),
+      '1. Configure agent instructions',
+    );
+    configureInstructions = !hasInstructionChanges || yes || await confirmPlan('Apply these instruction changes?');
+
+    note(
+      [
+        'Skill: constraint-skills',
+        'Scope: Global',
+        '',
+        ...plans.flatMap((plan) => [
+          `${humanize(plan.agent)} destination:`,
+          `${plan.skill.path} · ${plan.skill.action === 'current' ? 'already current' : plan.skill.action}`,
+          '',
+        ]),
+      ].join('\n').trim(),
+      '2. Install Constraint Skills',
+    );
+    installSkill = !hasSkillChanges || yes || await confirmPlan(`Install globally for ${agents.map(humanize).join(' and ')}?`);
   }
-  if (useUi) finish(`Constraint Skills configured for ${agents.join(' and ')}.`);
-  else out.data(results);
+
+  const result = { instructions: [], skill: [] };
+  if (configureInstructions) {
+    const spinner = taskSpinner(useUi && hasInstructionChanges);
+    for (const plan of plans) {
+      spinner.message(`Configuring ${humanize(plan.agent)} instructions`);
+      result.instructions.push(await applyInstructionSetup(plan.agent));
+    }
+    spinner.stop('Agent instructions configured.');
+  }
+  if (installSkill) {
+    const spinner = taskSpinner(useUi && hasSkillChanges);
+    for (const plan of plans) {
+      spinner.message(`Installing Constraint Skills for ${humanize(plan.agent)}`);
+      result.skill.push(await installCompanionSkill(plan.agent));
+    }
+    spinner.stop('Constraint Skills installed globally.');
+  }
+  if (useUi) {
+    finish([
+      'Setup complete.',
+      `Instructions: ${configureInstructions ? `${agents.length} configured` : 'skipped'}`,
+      `Skill: ${installSkill ? `installed for ${agents.map(humanize).join(' and ')}` : 'skipped'}`,
+    ].join('\n'));
+  } else out.data(result);
 }
 
 async function doctorCommand(args, config, out) {

package/src/setup.js

@@ -42,41 +42,107 @@ async function companionFiles() {
   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);
+async function instructionPlan(selected, paths) {
   let existing = '';
-  let instructionMode = 0o644;
+  let mode = 0o644;
   try {
     existing = await fs.readFile(paths.instructions, 'utf8');
-    instructionMode = (await fs.stat(paths.instructions)).mode & 0o777;
+    mode = (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 content = mergeInstructionBlock(existing);
+  return { path: paths.instructions, changed: content !== existing, content, mode };
+}
+
+async function skillPlan(selected, paths) {
+  const files = await companionFiles();
+  const bundledHash = packageDigest(files);
+  const config = await loadConfig();
+  const expectedHash = config.companion_hashes?.[selected] || null;
+  const target = path.join(paths.skills, 'constraint-skills');
+  let currentHash = null;
+  try {
+    currentHash = packageDigest(await readSkillDirectory(target));
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') throw error;
   }
+  const action = currentHash === bundledHash
+    ? 'current'
+    : currentHash === null
+      ? 'install'
+      : expectedHash && currentHash === expectedHash
+        ? 'update'
+        : 'conflict';
+  return { path: target, action, bundledHash, expectedHash };
+}
+
+export async function setupPlan(agent) {
+  const selected = normalizeAgent(agent);
+  const paths = agentPaths(selected);
+  return {
+    agent: selected,
+    instructions: await instructionPlan(selected, paths),
+    skill: await skillPlan(selected, paths),
+  };
+}
+
+async function recordConfiguredAgent(selected, config = null) {
+  const next = config || await loadConfig();
+  next.agents = [...new Set([...next.agents.map(normalizeAgent), selected])];
+  await saveConfig(next);
+}
+
+export async function applyInstructionSetup(agent) {
+  const selected = normalizeAgent(agent);
+  const paths = agentPaths(selected);
+  const plan = await instructionPlan(selected, paths);
+  if (plan.changed) await writeInstructions(plan.path, plan.content, plan.mode);
+  await recordConfiguredAgent(selected);
+  return { agent: selected, path: plan.path, changed: plan.changed, applied: true };
+}
+
+export async function installCompanionSkill(agent) {
+  const selected = normalizeAgent(agent);
+  const paths = agentPaths(selected);
   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 };
+  const result = await writeSkillDirectory(target, files, {
+    expectedHash: config.companion_hashes[selected] || null,
+  });
+  config.companion_hashes[selected] = result.hash;
+  await recordConfiguredAgent(selected, config);
+  return { agent: selected, path: target, changed: result.changed, applied: true };
+}
+
+export async function setupAgent(agent, {
+  dryRun = false,
+  yes = false,
+  confirmChange = async () => false,
+  output = console.log,
+  instructions = true,
+  skill = true,
+} = {}) {
+  const selected = normalizeAgent(agent);
+  const plan = await setupPlan(selected);
+  output(`${selected}: ${plan.instructions.path}`);
+  if (dryRun) {
+    if (instructions) output(plan.instructions.content);
+    if (skill) output(`Install constraint-skills globally at ${plan.skill.path} (${plan.skill.action}).`);
+    return { agent: selected, instructions: plan.instructions, skill: plan.skill, applied: false };
+  }
+  let instructionResult = null;
+  let skillResult = null;
+  if (instructions) {
+    const approved = !plan.instructions.changed || yes || await confirmChange(
+      `Add the Constraint Skills block to ${plan.instructions.path}?`,
+    );
+    if (approved) instructionResult = await applyInstructionSetup(selected);
+  }
+  if (skill) skillResult = await installCompanionSkill(selected);
+  return { agent: selected, instructions: instructionResult, skill: skillResult, applied: true };
 }
 
 export async function setupStatus(agent) {