@constraint/cli 0.2.0

package/LICENSE

@@ -0,0 +1,92 @@
+Constraint CLI Proprietary License
+
+Copyright (c) 2026 Constraint. All rights reserved.
+
+This Constraint CLI Proprietary License (the "License") governs use of the
+Constraint command-line software distributed with this License (the
+"Software"). By installing or using the Software, you agree to this License.
+
+1. Limited License
+
+Subject to this License and any applicable agreement governing your access to
+Constraint's products or services (a "Service Agreement"), Constraint grants
+you a limited, non-exclusive, non-transferable, non-sublicensable, revocable
+license to install and use the Software solely to access and use Constraint
+products and services that you are authorized to use.
+
+2. Restrictions
+
+Except where applicable law expressly permits otherwise, you may not:
+
+(a) copy the Software except as reasonably necessary to install, use, or make
+one backup copy of it;
+
+(b) modify, adapt, translate, or create derivative works of the Software;
+
+(c) distribute, publish, sublicense, sell, rent, lease, lend, transfer, or
+otherwise make the Software available to any third party;
+
+(d) reverse engineer, decompile, disassemble, or attempt to discover the source
+code, underlying ideas, algorithms, or non-public interfaces of the Software;
+
+(e) remove or alter proprietary notices contained in the Software; or
+
+(f) use the Software to bypass access controls, security controls, usage limits,
+or permissions of any Constraint product or service.
+
+3. Service Agreement
+
+Your access to Constraint products and services remains governed by the
+applicable Service Agreement. If this License conflicts with a signed Service
+Agreement, the signed Service Agreement controls to the extent of the conflict.
+The Software does not grant access to any product, service, data, skill, or
+other resource that you are not otherwise authorized to access.
+
+4. Ownership
+
+The Software is licensed, not sold. Constraint and its licensors retain all
+right, title, and interest in and to the Software, including all intellectual
+property rights. No rights are granted except those expressly stated in this
+License.
+
+5. Updates
+
+Constraint may provide updates, modifications, or replacement versions of the
+Software. Unless accompanied by different terms, those versions are governed
+by this License. Constraint is not obligated to provide any update, support, or
+maintenance.
+
+6. Term and Termination
+
+This License ends automatically if you materially breach it or if your
+authorization to use the applicable Constraint products and services ends.
+Upon termination, you must stop using and delete all copies of the Software in
+your possession or control. Sections 2, 4, 7, 8, and 9 survive termination.
+
+7. Disclaimer of Warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS" AND
+"AS AVAILABLE," WITHOUT WARRANTIES OF ANY KIND, WHETHER EXPRESS, IMPLIED,
+STATUTORY, OR OTHERWISE, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. CONSTRAINT DOES NOT WARRANT
+THAT THE SOFTWARE WILL BE UNINTERRUPTED, ERROR-FREE, OR SECURE.
+
+8. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, CONSTRAINT AND ITS LICENSORS WILL NOT BE
+LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR
+PUNITIVE DAMAGES, OR FOR ANY LOSS OF DATA, PROFITS, REVENUE, BUSINESS, OR
+GOODWILL, ARISING OUT OF OR RELATED TO THE SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF THOSE DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY LAW,
+CONSTRAINT'S TOTAL LIABILITY ARISING OUT OF OR RELATED TO THE SOFTWARE WILL NOT
+EXCEED THE AMOUNT PAID SPECIFICALLY FOR THE SOFTWARE DURING THE TWELVE MONTHS
+BEFORE THE EVENT GIVING RISE TO LIABILITY.
+
+9. General
+
+You may not assign this License without Constraint's prior written consent.
+Constraint may assign this License in connection with a merger, acquisition,
+reorganization, or sale of assets. If any provision is unenforceable, it will
+be enforced to the maximum extent permitted and the remaining provisions will
+remain in effect. A failure to enforce a provision is not a waiver. This
+License does not limit rights that cannot lawfully be limited.

package/README.md

@@ -0,0 +1,203 @@
+# Constraint CLI
+
+Install, publish, and report governed Agent Skills with Constraint.
+
+The package is named `@constraint/cli`; after installation, the terminal
+command is simply `constraint`.
+
+## Requirements
+
+- Node.js 20 or newer
+- A Constraint account with access to a WorkOS organization
+- Codex, Claude Code, or both
+
+## Install
+
+```bash
+npm install --global @constraint/cli
+```
+
+Confirm the installation:
+
+```bash
+constraint --version
+constraint --help
+```
+
+## Sign in
+
+```bash
+constraint login
+```
+
+The CLI displays a verification URL and code, then uses WorkOS device
+authorization to sign in. It never asks for a Constraint API key or client
+secret.
+
+Inspect or clear the current session:
+
+```bash
+constraint whoami
+constraint logout
+```
+
+## Configure agents
+
+Run the interactive setup:
+
+```bash
+constraint setup
+```
+
+Or target agents explicitly:
+
+```bash
+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.
+
+Preview the instruction change without applying it:
+
+```bash
+constraint setup --agent codex --dry-run
+```
+
+## Discover skills
+
+```bash
+constraint skills list
+constraint skills list --search research
+constraint skills inspect account-research
+constraint skills inspect account-research --files
+```
+
+The server returns only skills the signed-in user is authorized to access.
+There is no domain-selection flag for reading or installing skills.
+
+## Install skills
+
+Start the interactive installer:
+
+```bash
+constraint skills install account-research
+```
+
+Install for multiple agents in the current project:
+
+```bash
+constraint skills install account-research \
+  --agent codex \
+  --agent claude-code \
+  --project
+```
+
+Install globally:
+
+```bash
+constraint skills install account-research --agent codex --global
+```
+
+Project installations write a portable `skills-lock.json`. Global
+installations use Constraint's private per-user configuration directory. The
+installer prefers managed links so agents can share one package; pass `--copy`
+to install independent copies. If links are unavailable, the installer falls
+back to copying and records the mode that actually occurred.
+
+The installer stages changes, replaces managed paths atomically, and refuses
+to overwrite local edits.
+
+List local installation records:
+
+```bash
+constraint skills list --installed --project
+constraint skills list --installed --global
+```
+
+Update one skill or every skill in a scope:
+
+```bash
+constraint skills update account-research --project
+constraint skills update --all --project
+constraint skills update --all --global
+```
+
+## Upload a skill
+
+Create or edit a standard Agent Skill folder locally, then upload it:
+
+```bash
+constraint skills upload ./account-research
+```
+
+The folder must contain a root `SKILL.md` with `name` and `description` YAML
+frontmatter. If the user can manage more than one Constraint domain, the CLI
+asks which domain owns the skill. Skill versions are immutable; uploading
+changed content creates the next version.
+
+## Report skill runs
+
+The installed companion skill directs an agent to start a run after loading a
+governed skill:
+
+```bash
+constraint skills run start account-research \
+  --client codex \
+  --session <session-id>
+```
+
+The command prints a run ID. After completing the work, the agent uploads the
+real client transcript file for that run:
+
+```bash
+constraint skills run complete <run-id> <transcript-path>
+```
+
+The CLI uploads the transcript exactly as it exists on disk. It does not create
+a replacement transcript or modify the invoked skill.
+
+Inspect completed runs:
+
+```bash
+constraint skills run list
+constraint skills run list --skill account-research
+constraint skills run list --team sales_pipeline --user <user-id>
+constraint skills run get <run-id>
+constraint skills run get <run-id> --raw --output transcript.jsonl
+```
+
+Team and user filters are enforced by Constraint's domain permissions.
+
+## Automation
+
+Use `--json` for machine-readable output, `--quiet` to suppress normal output,
+and `--yes` to accept deterministic installer defaults. Non-interactive
+environments skip the terminal wizard.
+
+```bash
+constraint skills install account-research \
+  --agent codex \
+  --project \
+  --yes \
+  --json
+```
+
+## Diagnostics
+
+```bash
+constraint doctor
+constraint doctor --agent codex --agent claude-code
+```
+
+`doctor` reports API authentication and whether each agent has the companion
+skill and managed instruction block.
+
+## License
+
+Constraint CLI is proprietary software. Use is permitted only under the
+[Constraint CLI Proprietary License](./LICENSE) and any applicable agreement
+governing access to Constraint products and services.
+
+Copyright (c) 2026 Constraint. All rights reserved.

package/bin/constraint.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Error: ${message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@constraint/cli",
+  "version": "0.2.0",
+  "description": "Install, publish, and report Agent Skills with Constraint",
+  "type": "module",
+  "bin": { "constraint": "bin/constraint.js" },
+  "files": ["bin", "src", "skills"],
+  "scripts": {
+    "check": "node --check bin/constraint.js && node --check src/cli.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.7.0",
+    "picocolors": "1.1.1"
+  },
+  "engines": { "node": ">=20" },
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": { "access": "public", "provenance": true }
+}

package/skills/constraint-skills/SKILL.md

@@ -0,0 +1,44 @@
+---
+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.
+---
+
+# Constraint Skills
+
+Record each invocation without editing the invoked skill or changing its work.
+
+## Start a run
+
+Immediately after selecting and loading a 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.
+
+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:
+
+```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.
+
+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.

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

@@ -0,0 +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."

package/src/api.js

@@ -0,0 +1,37 @@
+import { accessToken } from './auth.js';
+
+export class ConstraintApiError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export async function apiRequest(config, requestPath, init = {}) {
+  const token = await accessToken(config);
+  const response = await fetch(`${config.apiUrl}${requestPath}`, {
+    ...init,
+    headers: { Accept: 'application/json', Authorization: `Bearer ${token}`, ...init.headers },
+  });
+  if (!response.ok) {
+    let data = null;
+    try {
+      data = await response.json();
+    } catch {
+      data = null;
+    }
+    throw new ConstraintApiError(
+      response.status,
+      data?.error?.code || 'request_failed',
+      data?.error?.message || `Constraint API request failed (${response.status})`,
+    );
+  }
+  if (init.rawResponse) return response;
+  if (response.status === 204) return null;
+  return response.json();
+}
+
+export function jsonRequest(body) {
+  return { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) };
+}

package/src/arguments.js

@@ -0,0 +1,26 @@
+export function takeFlag(args, name) {
+  const index = args.indexOf(name);
+  if (index < 0) return false;
+  args.splice(index, 1);
+  return true;
+}
+
+export function takeOption(args, name, { multiple = false } = {}) {
+  const values = [];
+  for (let index = 0; index < args.length; ) {
+    if (args[index] !== name) {
+      index += 1;
+      continue;
+    }
+    if (index + 1 >= args.length || args[index + 1].startsWith('--')) throw new Error(`${name} requires a value`);
+    values.push(args[index + 1]);
+    args.splice(index, 2);
+    if (!multiple) break;
+  }
+  return multiple ? values : values[0];
+}
+
+export function rejectUnknown(args) {
+  const unknown = args.find((value) => value.startsWith('-'));
+  if (unknown) throw new Error(`Unknown option: ${unknown}`);
+}

package/src/auth-store.js

@@ -0,0 +1,58 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { configDirectory } from './paths.js';
+
+const SERVICE = 'com.constraint.cli';
+
+function useKeychain() {
+  return process.platform === 'darwin' && process.env.CONSTRAINT_TOKEN_STORE !== 'file';
+}
+
+function account(apiUrl) {
+  return new URL(apiUrl).host;
+}
+
+function keychain(args) {
+  return spawnSync('security', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function tokenFile() {
+  return path.join(configDirectory(), 'auth.json');
+}
+
+export async function readTokens(apiUrl) {
+  if (useKeychain()) {
+    const result = keychain(['find-generic-password', '-s', SERVICE, '-a', account(apiUrl), '-w']);
+    if (result.status === 0 && result.stdout.trim()) return JSON.parse(result.stdout.trim());
+    return null;
+  }
+  try {
+    return JSON.parse(await fs.readFile(tokenFile(), 'utf8'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function writeTokens(apiUrl, tokens) {
+  if (useKeychain()) {
+    const result = keychain([
+      'add-generic-password', '-U', '-s', SERVICE, '-a', account(apiUrl), '-w', JSON.stringify(tokens),
+    ]);
+    if (result.status !== 0) throw new Error(`Could not store login in macOS Keychain: ${result.stderr.trim()}`);
+    return;
+  }
+  await fs.mkdir(configDirectory(), { recursive: true, mode: 0o700 });
+  await fs.writeFile(tokenFile(), `${JSON.stringify(tokens)}\n`, { mode: 0o600 });
+  await fs.chmod(tokenFile(), 0o600);
+}
+
+export async function deleteTokens(apiUrl) {
+  if (useKeychain()) {
+    keychain(['delete-generic-password', '-s', SERVICE, '-a', account(apiUrl)]);
+    return;
+  }
+  await fs.rm(tokenFile(), { force: true });
+}

package/src/auth.js

@@ -0,0 +1,103 @@
+import { spawn } from 'node:child_process';
+
+import { deleteTokens, readTokens, writeTokens } from './auth-store.js';
+import { fetchCliConfig } from './config.js';
+
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function openBrowser(url) {
+  if (process.env.CONSTRAINT_NO_BROWSER === '1') return;
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.unref();
+  } catch {
+    // The printed URL is always the fallback.
+  }
+}
+
+async function formPost(url, values) {
+  return fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams(values),
+  });
+}
+
+export async function login(config, output) {
+  const oauth = await fetchCliConfig(config.apiUrl);
+  const authorization = await formPost(oauth.device_authorization_endpoint, { client_id: oauth.workos_client_id });
+  const request = await authorization.json();
+  if (!authorization.ok) throw new Error(request.error_description || request.error || 'Device authorization failed');
+
+  output(`Open ${request.verification_uri}`);
+  output(`Enter code: ${request.user_code}`);
+  if (request.verification_uri_complete) openBrowser(request.verification_uri_complete);
+
+  let interval = Number(request.interval || 5);
+  const expiresAt = Date.now() + Number(request.expires_in || 300) * 1000;
+  while (Date.now() < expiresAt) {
+    await sleep(interval * 1000);
+    const response = await formPost(oauth.token_endpoint, {
+      grant_type: DEVICE_GRANT,
+      device_code: request.device_code,
+      client_id: oauth.workos_client_id,
+    });
+    const data = await response.json();
+    if (response.ok) {
+      await writeTokens(config.apiUrl, {
+        ...data,
+        client_id: oauth.workos_client_id,
+        token_endpoint: oauth.token_endpoint,
+      });
+      return data;
+    }
+    if (data.error === 'authorization_pending') continue;
+    if (data.error === 'slow_down') {
+      interval += 5;
+      continue;
+    }
+    throw new Error(data.error_description || data.error || 'Authentication failed');
+  }
+  throw new Error('Authentication timed out. Run constraint login again.');
+}
+
+function tokenExpiresSoon(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8'));
+    return !payload.exp || payload.exp * 1000 < Date.now() + 30_000;
+  } catch {
+    return false;
+  }
+}
+
+async function refresh(config, tokens) {
+  if (!tokens.refresh_token || !tokens.client_id || !tokens.token_endpoint) return null;
+  const response = await formPost(tokens.token_endpoint, {
+    grant_type: 'refresh_token',
+    refresh_token: tokens.refresh_token,
+    client_id: tokens.client_id,
+  });
+  if (!response.ok) return null;
+  const refreshed = await response.json();
+  const next = { ...tokens, ...refreshed };
+  await writeTokens(config.apiUrl, next);
+  return next;
+}
+
+export async function accessToken(config) {
+  let tokens = await readTokens(config.apiUrl);
+  if (!tokens?.access_token) throw new Error('Not logged in. Run constraint login.');
+  if (tokenExpiresSoon(tokens.access_token)) tokens = (await refresh(config, tokens)) || tokens;
+  if (tokenExpiresSoon(tokens.access_token)) throw new Error('Login expired. Run constraint login.');
+  return tokens.access_token;
+}
+
+export async function logout(config) {
+  await deleteTokens(config.apiUrl);
+}