@constraint/cli 0.3.2 → 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.2",
+  "version": "0.3.4",
   "description": "Install, publish, and report Agent Skills with Constraint",
   "type": "module",
   "bin": {

package/skills/constraint-skills/SKILL.md

@@ -1,44 +1,71 @@
 ---
 name: constraint-skills
-description: Report Agent Skill invocations to Constraint. Use whenever an agent invokes a skill installed from or governed by Constraint, including nested or multiple skill invocations in one client session.
+description: Operate governed Agent Skills with the Constraint terminal CLI and report their invocations. Use when an agent needs to authenticate or diagnose Constraint access; configure agents; discover upload domains; inspect, install, update, or upload skills; query run history; or invoke any skill installed from or governed by Constraint.
 ---
 
 # Constraint Skills
 
-Record each invocation without editing the invoked skill or changing its work.
+Use the `constraint` command for organization-authorized skills. Do not edit its config, lockfiles, instruction blocks, installation receipts, or authorization tokens directly.
+
+## Choose the operation
+
+- Authenticate or diagnose: `constraint login`, `constraint whoami`, `constraint doctor`.
+- Configure agents: `constraint setup`.
+- Discover or inspect skills: `constraint skills list`, `constraint skills inspect`.
+- Install or update: `constraint skills install`, `constraint skills update`.
+- Discover upload destinations: `constraint skills domains --json`.
+- Upload a local skill folder: `constraint skills upload`.
+- Review runs: `constraint skills run list`, `constraint skills run get`.
+
+Read [references/commands.md](references/commands.md) before constructing flags or handling a less common operation.
+
+## Upload skills
+
+Upload the skill directory, not an individual `SKILL.md`. Before every upload, run:
+
+```bash
+constraint skills domains --json
+```
+
+Use one returned `slug` exactly as `--domain`. Never guess a slug from a display name or reuse a domain from another organization. If multiple destinations are valid and ownership is unclear, ask the user.
+
+```bash
+constraint skills upload <skill-directory> --domain <returned-slug>
+```
+
+## Install skills
+
+Choose the target agent and scope explicitly. Prefer `--project`; use `--global` only when the user wants the skill across projects. Prefer managed links and use `--copy` only when independent files are required. Never overwrite locally edited installed skills.
 
 ## Start a run
 
-Immediately after selecting and loading a skill, run:
+Immediately after selecting and loading a governed skill, run:
 
 ```bash
 constraint skills run start <skill-name> --client <client> --session <session-id>
 ```
 
-Use the invoked skill's frontmatter `name`. Normalize the client to `codex` or
-`claude-code`. Use the current client session identifier. Retain the exact run ID
-printed by the command. If one session invokes multiple skills, start and retain
-a distinct run ID for each invocation.
+Use the invoked skill's frontmatter `name`. Normalize the client to `codex` or `claude-code`. Use the current client session identifier. Retain the exact run ID printed by the command. If one session invokes multiple skills, start and retain a distinct run ID for each invocation.
 
-If the command fails, report the failure briefly and continue the user's work.
-Do not fabricate a run ID.
+If the command fails, report the failure briefly and continue the user's work. Do not fabricate a run ID.
 
 ## Complete a run
 
-After finishing the invoked skill's work and before ending the response, locate
-the current session's real JSON or JSONL transcript file and run:
+After finishing the governed skill's work and before ending the response, locate the current session's real JSON or JSONL transcript file and run:
 
 ```bash
 constraint skills run complete <run-id> <transcript-path>
 ```
 
-Pass the explicit local path. The CLI uploads the whole transcript file as it
-exists at that moment and completes only that run. Never create a replacement
-transcript, summarize it, pass a temporary file, or guess a path.
+Pass the explicit local path. The CLI uploads the whole transcript file as it exists at that moment and completes only that run. Never create a replacement transcript, summarize it, pass a temporary file, or guess a path.
 
-For multiple invocations, complete each retained run separately. Overlapping
-full-session transcript prefixes are expected. If the transcript path cannot be
-determined, leave the run started and tell the user that reporting could not be
-completed.
+For multiple invocations, complete each retained run separately. Overlapping full-session transcript prefixes are expected. If the transcript path cannot be determined, leave the run started and tell the user that reporting could not be completed.
 
 Do not run completion hooks, background flushes, or pending-run scans.
+
+## Work safely
+
+- Use `--json` when parsing output.
+- Respect WorkOS authorization failures; never bypass domain permissions.
+- Do not invent an uninstall workflow.
+- After mutations, report the affected skill, version, agent, scope, domain, or run ID as applicable.

package/skills/constraint-skills/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Constraint Skills"
-  short_description: "Report skill runs to Constraint"
-  default_prompt: "Use $constraint-skills to report this skill run to Constraint."
+  short_description: "Operate and report governed agent skills"
+  default_prompt: "Use $constraint-skills to manage a governed skill and report its run."

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

@@ -0,0 +1,65 @@
+# Constraint CLI command reference
+
+## Install, authenticate, and configure
+
+```bash
+npm install --global @constraint/cli
+constraint --version
+constraint login
+constraint whoami
+constraint logout
+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, 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
+
+```bash
+constraint skills list
+constraint skills list --search <text>
+constraint skills inspect <skill> [--version <number>] [--files]
+
+constraint skills install <skill> --agent codex --project
+constraint skills install <skill> --agent claude-code --global
+constraint skills list --installed --project
+constraint skills update <skill> --project
+constraint skills update --all --global
+```
+
+The catalog is already authorization-filtered. Project installs create `skills-lock.json`. Global receipts live in Constraint's per-user configuration directory.
+
+## Discover upload domains and upload
+
+```bash
+constraint skills domains
+constraint skills domains --json
+constraint skills upload <skill-directory> --domain <returned-slug>
+```
+
+`skills domains` returns only domains where the authenticated user can manage skills. JSON objects contain the exact `slug`, display `name`, and `description`. Discover first and pass one returned slug. Ask the user when multiple domains fit and ownership is unclear.
+
+## Start, complete, and review runs
+
+```bash
+constraint skills run start <skill> --client codex --session <stable-session-id>
+constraint skills run complete <run-id> <actual-transcript-path>
+
+constraint skills run list
+constraint skills run list --team <domain> --user <workos-user-id> --skill <skill>
+constraint skills run get <run-id>
+constraint skills run get <run-id> --raw --output transcript.jsonl
+```
+
+Repeat `--team`, `--user`, or `--skill` to request subsets. Review visibility is permission-controlled.
+
+## Automation and recovery
+
+Global flags: `--json`, `--quiet`, `--no-color`, `--help`, and `--version`. Installer workflows also accept `--yes`.
+
+- Authentication failure: run `constraint login`, then `constraint whoami`.
+- Setup uncertainty: run `constraint doctor`.
+- Upload denied: rerun `constraint skills domains --json` and respect the returned scope.
+- Install conflict: preserve local edits.
+- Missing transcript: locate the real client JSON or JSONL file before completion.

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.2';
+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

@@ -12,9 +12,9 @@ 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.
+When using the Constraint CLI or invoking any installed Agent Skill, load and
+follow the global \`constraint-skills\` companion skill. It contains the CLI
+workflow and records governed runs without modifying the invoked skill.
 ${BLOCK_END}`;
 
 export function mergeInstructionBlock(existing) {
@@ -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) {