@constraint/cli 0.4.0 → 0.4.2

package/package.json

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

package/skills/constraint-skills/SKILL.md

@@ -57,10 +57,10 @@ constraint report <transcript-path> --skill <skill-name>
 ```
 
 Pass the explicit local path to the transcript as it exists at that moment.
-Use the invoked skill's frontmatter `name`. The server detects the client and
-session id from the transcript itself; re-reporting the same session later
-supersedes the earlier report. Never create a replacement transcript,
-summarize it, or pass a temporary file. If the transcript path cannot be
+Use the invoked skill's frontmatter `name`. Client and session id are read
+from the transcript path; re-reporting the same session later supersedes the
+earlier report. Never create a replacement transcript, summarize it, copy it
+elsewhere first, or pass a temporary file. If the transcript path cannot be
 determined, say so instead of guessing.
 
 ## Work safely

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 globally, and removes the legacy managed block that earlier releases injected into global instruction files. It never adds to or replaces user instructions.
+`login` uses WorkOS device authorization. Never request or embed an API key or client secret. `setup` detects Codex and Claude Code and installs this skill globally. It never touches instruction files.
 
 ## Discover, inspect, install, and update
 
@@ -53,8 +53,9 @@ constraint skills run get <run-id> --raw
 ```
 
 `report` is user-driven: run it only when the user asks to put a session on the
-record. The server detects client and session id from the transcript;
-`--client`/`--session` are overrides for transcripts it cannot parse.
+record. Client and session id are read from the transcript path itself (Claude
+Code project transcripts and Codex rollouts are named by session id);
+`--client`/`--session` are only needed for files outside those locations.
 Re-reporting the same session supersedes the earlier report.
 
 Repeat `--team`, `--user`, or `--skill` to request subsets. Review visibility is permission-controlled.

package/src/cli.js

@@ -20,13 +20,13 @@ import {
   taskSpinner,
 } from './prompts.js';
 import {
-  applyInstructionSetup,
   installCompanionSkill,
   setupPlan,
   setupStatus,
 } from './setup.js';
 import {
   configuredAgents,
+  identifyLocalSkill,
   installSkill,
   installedSkills,
   manageableDomainRecords,
@@ -36,7 +36,7 @@ import {
   uploadSkill,
 } from './skills.js';
 
-const VERSION = '0.4.0';
+const VERSION = '0.4.2';
 
 const HELP = `Constraint Skills CLI
 
@@ -249,30 +249,17 @@ async function setupCommand(args, out) {
   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)) {
+  if (!useUi && !yes && 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 ? 'Legacy Constraint block will be removed' : 'Nothing to clean up'}`).join('\n\n'),
-      '1. Remove legacy instruction blocks',
-    );
-    configureInstructions = !hasInstructionChanges || yes || await confirmPlan('Remove the legacy Constraint block from these files?');
-
     note(
       [
         'Skill: constraint-skills',
@@ -284,20 +271,12 @@ async function setupCommand(args, out) {
           '',
         ]),
       ].join('\n').trim(),
-      '2. Install Constraint Skills',
+      'Install Constraint Skills',
     );
     installSkill = !hasSkillChanges || yes || await confirmPlan(`Install globally for ${agents.map(humanize).join(' and ')}?`);
   }
 
-  const result = { instructions: [], skill: [] };
-  if (configureInstructions) {
-    const spinner = taskSpinner(useUi && hasInstructionChanges);
-    for (const plan of plans) {
-      spinner.message(`Cleaning ${humanize(plan.agent)} instructions`);
-      result.instructions.push(await applyInstructionSetup(plan.agent));
-    }
-    spinner.stop('Agent instructions cleaned.');
-  }
+  const result = { skill: [] };
   if (installSkill) {
     const spinner = taskSpinner(useUi && hasSkillChanges);
     for (const plan of plans) {
@@ -309,7 +288,6 @@ async function setupCommand(args, out) {
   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);
@@ -472,8 +450,23 @@ async function uploadCommand(args, config, out) {
 
 // A run is the posting of a transcript in which a skill was invoked. The user
 // drives reporting: one command, after the session, with the finished
-// transcript. Client and session id are detected server-side from the
-// transcript; flags override when detection cannot.
+// transcript. Client and session id come straight from the transcript path —
+// agent clients keep sessions at well-known locations named by session id.
+export function transcriptIdentity(absolute) {
+  const basename = path.basename(absolute);
+  const stem = basename.replace(/\.(jsonl?|json)$/i, '');
+  const uuid = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (absolute.includes(`${path.sep}.codex${path.sep}sessions${path.sep}`) || stem.startsWith('rollout-')) {
+    const match = stem.match(uuid);
+    return { client: 'codex', session: match ? match[0] : stem };
+  }
+  if (absolute.includes(`${path.sep}.claude${path.sep}projects${path.sep}`) || uuid.test(stem)) {
+    const match = stem.match(uuid);
+    return { client: 'claude-code', session: match ? match[0] : stem };
+  }
+  return { client: null, session: null };
+}
+
 async function reportCommand(args, config, out) {
   const skill = takeOption(args, '--skill');
   const client = takeOption(args, '--client');
@@ -483,9 +476,37 @@ async function reportCommand(args, config, out) {
     throw new Error('Usage: constraint report <transcript-path> --skill <skill> [--client <client>] [--session <session-id>]');
   }
   const transcript = await readTranscript(args[0]);
-  const query = new URLSearchParams({ skill });
-  if (client) query.set('client', client);
-  if (session) query.set('session', session);
+  const identity = transcriptIdentity(transcript.absolute);
+  const resolvedClient = client || identity.client;
+  const resolvedSession = session || identity.session;
+  if (!resolvedClient || !resolvedSession) {
+    throw new Error('Could not tell the client and session from this path. Pass --client and --session.');
+  }
+
+  // Version attribution: hash the local skill folder and match it against the
+  // published versions, so the run records what actually ran — not "latest".
+  let detail;
+  try {
+    detail = await apiRequest(config, `/skills/${encodeURIComponent(skill)}`);
+  } catch (error) {
+    if (/not found/i.test(error.message)) {
+      const projectRoot = await findProjectRoot();
+      const hint = await identifyLocalSkill(config, { skill_id: skill, slug: skill, latest_version: 0 }, { projectRoot })
+        .then((found) => found.localPath)
+        .catch(() => null);
+      throw new Error(
+        `${skill} is not on Constraint.` +
+        (hint ? ` Found a local skill at ${hint} — upload it first:
+  constraint skills upload ${hint} --domain <domain>` : ' Upload it first with constraint skills upload.'),
+      );
+    }
+    throw error;
+  }
+  const projectRoot = await findProjectRoot();
+  const identified = await identifyLocalSkill(config, detail, { projectRoot });
+
+  const query = new URLSearchParams({ skill, client: resolvedClient, session: resolvedSession });
+  if (identified.verified) query.set('version', String(identified.version));
   const run = await apiRequest(config, `/skill-reports?${query.toString()}`, {
     method: 'POST',
     headers: { 'Content-Type': mediaType(transcript.absolute), 'X-Transcript-Filename': transcript.filename },
@@ -495,6 +516,10 @@ async function reportCommand(args, config, out) {
     run_id: run.run_id,
     skill: run.skill_slug,
     version: run.skill_version,
+    version_verified: identified.verified,
+    ...(identified.localPath && !identified.verified
+      ? { warning: `local copy at ${identified.localPath} does not match any published version` }
+      : {}),
     state: run.state,
     client: run.client,
     session: run.client_session_id,

package/src/files.js

@@ -43,7 +43,9 @@ export async function readSkillDirectory(input) {
 
 export function packageDigest(files) {
   const hash = crypto.createHash('sha256');
-  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+  // Sort by code points, not locale: this digest must match the server's,
+  // which sorts paths with plain string comparison.
+  for (const file of [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
     hash.update(file.path);
     hash.update('\0');
     hash.update(file.content);

package/src/paths.js

@@ -28,18 +28,15 @@ 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, '.agents', 'skills') };
     }
-    return { skills: path.join(projectRoot, '.claude', 'skills'), instructions: null };
+    return { skills: path.join(projectRoot, '.claude', 'skills') };
   }
   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 { skills: path.join(root, 'skills') };
   }
-  return {
-    instructions: path.join(os.homedir(), '.claude', 'CLAUDE.md'),
-    skills: path.join(os.homedir(), '.claude', 'skills'),
-  };
+  return { skills: path.join(os.homedir(), '.claude', 'skills') };
 }
 
 async function exists(candidate) {

package/src/setup.js

@@ -6,32 +6,6 @@ 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 -->';
-
-// Earlier releases injected a managed instruction block into the user's global
-// CLAUDE.md/AGENTS.md. Writing into user-owned instruction files was never
-// trustworthy behavior; setup now only removes that legacy block if present.
-export function stripInstructionBlock(existing) {
-  const start = existing.indexOf(BLOCK_START);
-  const end = existing.indexOf(BLOCK_END);
-  if (start < 0 && end < 0) return existing;
-  if ((start >= 0) !== (end >= 0)) {
-    throw new Error('The existing Constraint Skills instruction block is incomplete; fix it before running setup.');
-  }
-  const before = existing.slice(0, start).replace(/\n+$/, '\n');
-  const after = existing.slice(end + BLOCK_END.length).replace(/^\n+/, '\n');
-  const stripped = `${before}${after}`;
-  return stripped.trim() === '' ? '' : stripped.replace(/\n{3,}/g, '\n\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'));
@@ -44,19 +18,6 @@ export function expectedCompanionHash(config, selected, currentHash) {
   return currentHash && recorded.includes(currentHash) ? currentHash : null;
 }
 
-async function instructionPlan(selected, paths) {
-  let existing = '';
-  let mode = 0o644;
-  try {
-    existing = await fs.readFile(paths.instructions, 'utf8');
-    mode = (await fs.stat(paths.instructions)).mode & 0o777;
-  } catch (error) {
-    if (error && error.code !== 'ENOENT') throw error;
-  }
-  const content = stripInstructionBlock(existing);
-  return { path: paths.instructions, changed: content !== existing, content, mode };
-}
-
 async function skillPlan(selected, paths) {
   const files = await companionFiles();
   const bundledHash = packageDigest(files);
@@ -84,7 +45,6 @@ export async function setupPlan(agent) {
   const paths = agentPaths(selected);
   return {
     agent: selected,
-    instructions: await instructionPlan(selected, paths),
     skill: await skillPlan(selected, paths),
   };
 }
@@ -95,15 +55,6 @@ async function recordConfiguredAgent(selected, config = null) {
   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);
@@ -122,42 +73,25 @@ export async function installCompanionSkill(agent) {
 
 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(
-      `Remove the legacy Constraint block from ${plan.instructions.path}?`,
-    );
-    if (approved) instructionResult = await applyInstructionSetup(selected);
+    output(`Install constraint-skills globally at ${plan.skill.path} (${plan.skill.action}).`);
+    return { agent: selected, skill: plan.skill, applied: false };
   }
-  if (skill) skillResult = await installCompanionSkill(selected);
-  return { agent: selected, instructions: instructionResult, skill: skillResult, applied: true };
+  const skillResult = await installCompanionSkill(selected);
+  return { agent: selected, skill: skillResult, 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, legacy_instruction_block: instructions.includes(BLOCK_START), skill: skill.isFile() };
+    const skill = await fs.stat(path.join(paths.skills, 'constraint-skills', 'SKILL.md'));
+    return { agent: selected, skill: skill.isFile() };
   } catch {
-    return { agent: selected, legacy_instruction_block: false, skill: false };
+    return { agent: selected, skill: false };
   }
 }

package/src/skills.js

@@ -231,6 +231,42 @@ export async function installedSkills({ scope = 'project', projectRoot, agents }
   return Object.values(lock.installations || {}).filter((item) => !selected || selected.has(item.agent));
 }
 
+// Version attribution for reports: find the skill's local folder (managed
+// symlink or plain folder — agents read both from the same directories), hash
+// it with the registry's package digest, and match against published versions.
+export async function identifyLocalSkill(config, detail, { projectRoot = null } = {}) {
+  const candidates = [];
+  if (projectRoot) {
+    for (const agent of ['claude-code', 'codex']) {
+      candidates.push(path.join(agentPaths(agent, { scope: 'project', projectRoot }).skills, detail.slug));
+    }
+  }
+  for (const agent of ['claude-code', 'codex']) {
+    candidates.push(path.join(agentPaths(agent).skills, detail.slug));
+  }
+  let local = null;
+  for (const candidate of candidates) {
+    try {
+      const digest = packageDigest(await readSkillDirectory(candidate));
+      local = { path: candidate, digest };
+      break;
+    } catch {
+      // not present here; keep looking
+    }
+  }
+  if (!local) return { localPath: null, version: null, verified: false };
+  for (let version = detail.latest_version; version >= 1; version -= 1) {
+    const candidate = await apiRequest(
+      config,
+      `/skills/${encodeURIComponent(detail.skill_id)}/versions/${version}`,
+    );
+    if (candidate.version.content_sha256 === local.digest) {
+      return { localPath: local.path, version, verified: true };
+    }
+  }
+  return { localPath: local.path, version: null, verified: false };
+}
+
 export async function readTranscript(file) {
   const absolute = path.resolve(file);
   return { absolute, filename: path.basename(absolute), content: await fs.readFile(absolute) };