@constraint/cli 0.3.5 → 0.3.7

package/package.json

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

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

@@ -49,11 +49,16 @@ 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
+constraint skills run get <run-id> --raw
 ```
 
 Repeat `--team`, `--user`, or `--skill` to request subsets. Review visibility is permission-controlled.
 
+`run get` never prints a transcript to stdout: it writes the run JSON (or the
+original transcript file with `--raw`) under the system temp directory and
+prints a one-object summary containing the file `path`. Read the file from
+that path. Pass `--output <path>` to choose the destination (single run only).
+
 ## Automation and recovery
 
 Global flags: `--json`, `--quiet`, `--no-color`, `--help`, and `--version`. Installer workflows also accept `--yes`.

package/src/cli.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 
@@ -35,7 +36,7 @@ import {
   uploadSkill,
 } from './skills.js';
 
-const VERSION = '0.3.5';
+const VERSION = '0.3.7';
 
 const HELP = `Constraint Skills CLI
 
@@ -56,7 +57,7 @@ Usage:
   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>]
+  constraint skills run get <run-id>... [--raw] [--output <path>]  (always writes a file, prints summary + path)
 
 Global options: --json --quiet --no-color --help --version`;
 
@@ -511,23 +512,50 @@ async function runList(args, config, out) {
   out.data(await apiRequest(config, `/skill-runs?${query.toString()}`));
 }
 
+// Run payloads are whole session transcripts — megabytes of JSON that would
+// flood a terminal or an agent's context. runGet therefore always writes to a
+// file and prints only a summary with the path; there is no stdout mode.
+async function runGetDestination(output, runId, extension) {
+  if (output) return path.resolve(output);
+  const directory = path.join(os.tmpdir(), 'constraint', 'runs');
+  await fs.mkdir(directory, { recursive: true });
+  return path.join(directory, `${runId}${extension}`);
+}
+
 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 (output && args.length !== 1) throw new Error('--output accepts exactly one 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);
+    const destination = await runGetDestination(output, args[0], '.transcript');
+    await fs.writeFile(destination, content);
+    out.data({ run_id: args[0], bytes: content.length, path: destination });
     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);
+  const summaries = [];
+  for (const runId of args) {
+    const run = await apiRequest(config, `/skill-runs/${encodeURIComponent(runId)}`);
+    const destination = await runGetDestination(output, runId, '.json');
+    await fs.writeFile(destination, `${JSON.stringify(run, null, 2)}\n`);
+    const events = Array.isArray(run.normalized_events) ? run.normalized_events : [];
+    summaries.push({
+      run_id: run.run_id,
+      skill: run.skill_slug,
+      version: run.skill_version,
+      state: run.state,
+      client: run.client,
+      completed_at: run.completed_at,
+      events: events.length,
+      events_with_text: events.filter((event) => event.content).length,
+      path: destination,
+    });
+  }
+  out.data(summaries.length === 1 ? summaries[0] : summaries);
 }
 
 async function runCommand(args, config, out) {

package/src/skills.js

@@ -45,6 +45,35 @@ async function loadLock(scope, projectRoot) {
   return scope === 'global' ? loadInstallations() : loadProjectInstallations(projectRoot);
 }
 
+// Installed skill files are per-machine (symlinks into the canonical store);
+// only skills-lock.json belongs in version control. Keep the project's
+// .gitignore covering the generated paths, npm-style.
+const GITIGNORE_ENTRIES = ['.constraint/', '.claude/skills/', '.agents/skills/'];
+
+async function ensureProjectGitignore(projectRoot) {
+  try {
+    await fs.stat(path.join(projectRoot, '.git'));
+  } catch {
+    return; // not a git repository; nothing to manage
+  }
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  let existing = '';
+  try {
+    existing = await fs.readFile(gitignorePath, 'utf8');
+  } catch {
+    existing = '';
+  }
+  const lines = new Set(existing.split('\n').map((line) => line.trim()));
+  const missing = GITIGNORE_ENTRIES.filter(
+    (entry) => !lines.has(entry) && !lines.has(entry.slice(0, -1)),
+  );
+  if (!missing.length) return;
+  const block = `${missing.join('\n')}\n`;
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+  const header = existing ? '\n# Constraint skill installs (commit skills-lock.json instead)\n' : '# Constraint skill installs (commit skills-lock.json instead)\n';
+  await fs.writeFile(gitignorePath, `${existing}${prefix}${header}${block}`);
+}
+
 async function saveLock(scope, projectRoot, value) {
   if (scope === 'global') return saveInstallations(value);
   return saveProjectInstallations(projectRoot, value);
@@ -96,6 +125,7 @@ export async function installSkill(config, identifier, {
   const lock = await loadLock(scope, root);
   lock.lockfile_version = 1;
   lock.installations ||= {};
+  if (scope === 'project') await ensureProjectGitignore(root);
   const packageFiles = filesFromDetail(detail);
   const contentHash = packageDigest(packageFiles);
   const canonical = copy === true ? null : canonicalSkillPath({