atris 3.52.0 → 3.55.0

package/scripts/det/checklist-score.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+'use strict';
+
+// Pareto-3 checklist quality score.
+//
+// Measures the three front doors a brand-new person actually hits, the way
+// they would hit them: from an empty folder, with no context, reading only
+// what the tool prints. Every point is earned by a live probe, never opinion.
+//
+//   1. onboard  - `atris init --yes` in a fresh folder
+//   2. chat     - one real answered message through `ax`
+//   3. mission  - the end-to-end loop drill in its own sandbox
+//
+// Rubric per feature (100 points):
+//   cold start works, zero setup ......... 40
+//   speed to first value ................. 20  (full marks at target, 0 at 4x)
+//   plain language on the first screen ... 20  (fraction of clean lines)
+//   graceful failure on wrong input ...... 20  (honest exit + plain reason,
+//                                               no stack trace)
+//
+// Usage: node scripts/det/checklist-score.js [--json]
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+const cliPath = path.join(repoRoot, 'bin', 'atris.js');
+const axPath = path.join(repoRoot, 'ax');
+const { scanText } = require(path.join(repoRoot, 'lib', 'voice-gate'));
+
+// System nouns a person with no idea should never have to decode on a first
+// screen. Backticked command examples are exempt (they are copy targets).
+const SYSTEM_NOUNS = /\b(?:verifier|worktree|subagent|jsonl|projection|runner[- ]profile|heartbeat|orchestrat\w+|frontmatter|monorepo)\b/i;
+const STACK_FRAME = /^\s+at .+:\d+:\d+\)?$/;
+
+function run(cmd, args, options = {}) {
+  const started = Date.now();
+  const result = spawnSync(cmd, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    timeout: options.timeoutMs || 180000,
+    env: { ...process.env, ATRIS_SKIP_UPDATE_CHECK: '1', ...(options.env || {}) },
+  });
+  return {
+    status: result.status,
+    error: result.error || null,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    ms: Date.now() - started,
+  };
+}
+
+function speedPoints(ms, targetMs) {
+  if (ms <= targetMs) return 20;
+  const over = (ms - targetMs) / (targetMs * 3);
+  return Math.max(0, Math.round(20 * (1 - over)));
+}
+
+function plainPoints(text) {
+  const lines = String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 30);
+  if (!lines.length) return { points: 0, dirty: ['(no output at all)'] };
+  const dirty = [];
+  for (const line of lines) {
+    // Command examples are copy targets, not prose; the reader with no idea
+    // reads the description column, so scan only the human words.
+    if (/^`.*`$/.test(line) || /^\$\s/.test(line) || /^(?:ax|atris|npx)\s/.test(line)) continue;
+    const bare = line
+      .replace(/`[^`]*`/g, '')
+      .replace(/--[\w-]+/g, '')
+      .replace(/\[[^\]]*\]/g, '')
+      .replace(/<[^>]*>/g, '');
+    if (STACK_FRAME.test(line) || /\u2014/.test(bare) || SYSTEM_NOUNS.test(bare) || scanText(bare).length) {
+      dirty.push(line.slice(0, 80));
+    }
+  }
+  const clean = lines.length - dirty.length;
+  return { points: Math.round((20 * clean) / lines.length), dirty };
+}
+
+function failurePoints(result) {
+  const text = `${result.stdout}\n${result.stderr}`;
+  const honest = result.status !== 0 && !result.error;
+  const noStack = !text.split(/\r?\n/).some((line) => STACK_FRAME.test(line))
+    && !/\b(?:TypeError|ReferenceError|SyntaxError)\b/.test(text);
+  const saysWhy = /\b(?:unknown|not found|no such|missing|usage|help|try|error)\b/i.test(text);
+  let points = 0;
+  if (honest) points += 8;
+  if (noStack) points += 6;
+  if (saysWhy) points += 6;
+  return points;
+}
+
+function scoreOnboard(base) {
+  const dir = fs.mkdtempSync(path.join(base, 'onboard-'));
+  const cold = run(process.execPath, [cliPath, 'init', '--yes'], { cwd: dir });
+  const artifact = fs.existsSync(path.join(dir, 'atris'));
+  const coldPoints = cold.status === 0 && artifact ? 40 : 0;
+  const plain = plainPoints(cold.stdout);
+  const bad = run(process.execPath, [cliPath, 'definitely-not-a-command'], { cwd: dir });
+  return {
+    feature: 'onboard: atris init in an empty folder',
+    dir,
+    cold: coldPoints,
+    speed: speedPoints(cold.ms, 10000),
+    plain: plain.points,
+    failure: failurePoints(bad),
+    ms: cold.ms,
+    dirty_lines: plain.dirty,
+  };
+}
+
+function scoreChat(base, workspaceDir) {
+  const cold = run(process.execPath, [axPath, '--fast', '--print', 'Reply with exactly: checklist-ok'], {
+    cwd: workspaceDir,
+    timeoutMs: 120000,
+  });
+  let answered = false;
+  try {
+    const payload = JSON.parse(cold.stdout.slice(cold.stdout.indexOf('{')));
+    answered = payload.ok === true && /checklist-ok/.test(String(payload.output || ''));
+  } catch {}
+  const helpScreen = run(process.execPath, [axPath, '--help'], { cwd: workspaceDir, timeoutMs: 30000 });
+  const plain = plainPoints(helpScreen.stdout);
+  const bad = run(process.execPath, [axPath, '--fast', '--print'], { cwd: workspaceDir, timeoutMs: 30000 });
+  return {
+    feature: 'chat: one real answered message through ax',
+    cold: cold.status !== null && answered ? 40 : 0,
+    speed: speedPoints(cold.ms, 15000),
+    plain: plain.points,
+    failure: failurePoints(bad),
+    ms: cold.ms,
+    dirty_lines: plain.dirty,
+  };
+}
+
+function scoreMission(base, workspaceDir) {
+  const cold = run(process.execPath, [cliPath, 'drill', '--json'], { cwd: workspaceDir, timeoutMs: 300000 });
+  let passed = false;
+  let stages = 0;
+  try {
+    const payload = JSON.parse(cold.stdout.slice(cold.stdout.indexOf('{')));
+    passed = payload.pass === true;
+    stages = Array.isArray(payload.stages) ? payload.stages.length : 0;
+  } catch {}
+  const status = run(process.execPath, [cliPath, 'mission'], { cwd: workspaceDir, timeoutMs: 60000 });
+  const plain = plainPoints(status.stdout);
+  const bad = run(process.execPath, [cliPath, 'mission', 'run', '9999'], { cwd: workspaceDir, timeoutMs: 60000 });
+  return {
+    feature: `mission: full loop drill (${stages} stages) plus status screen`,
+    cold: passed ? 40 : 0,
+    speed: speedPoints(cold.ms, 90000),
+    plain: plain.points,
+    failure: failurePoints(bad),
+    ms: cold.ms,
+    dirty_lines: plain.dirty,
+  };
+}
+
+function main() {
+  const asJson = process.argv.includes('--json');
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'atris-checklist-'));
+  const onboard = scoreOnboard(base);
+  const chat = scoreChat(base, onboard.dir);
+  const mission = scoreMission(base, onboard.dir);
+  const features = [onboard, chat, mission].map((f) => ({
+    ...f,
+    total: f.cold + f.speed + f.plain + f.failure,
+  }));
+  const overall = Math.round(features.reduce((sum, f) => sum + f.total, 0) / features.length);
+  const report = { schema: 'atris.checklist_score.v1', overall, features };
+  fs.rmSync(base, { recursive: true, force: true });
+  if (asJson) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log('Pareto-3 checklist quality score\n');
+  for (const f of features) {
+    console.log(`  ${f.feature}`);
+    console.log(`    cold start ${f.cold}/40 · speed ${f.speed}/20 (${(f.ms / 1000).toFixed(1)}s) · plain words ${f.plain}/20 · graceful failure ${f.failure}/20  =>  ${f.total}/100`);
+    if (f.dirty_lines.length) console.log(`    lines that need plain words: ${f.dirty_lines.length}`);
+  }
+  console.log(`\n  overall: ${overall}/100`);
+}
+
+main();

package/scripts/det/ytsearch

@@ -0,0 +1,31 @@
+#!/bin/bash
+# ytsearch <query> [limit]: free YouTube discovery via yt-dlp ytsearchN.
+# Zero Atris credits. Prints one line per video:
+#   title | channel | duration | views | upload_date | https://youtu.be/ID
+# upload_date is YYYYMMDD (or NA) so callers can apply a freshness gate.
+set -euo pipefail
+
+USAGE='usage: ytsearch "<query>" [limit]'
+
+QUERY="${1:-}"
+LIMIT="${2:-5}"
+
+if [ -z "$QUERY" ] || [ "$QUERY" = '-h' ] || [ "$QUERY" = '--help' ] || [ "$QUERY" = 'help' ]; then
+  echo "$USAGE" >&2
+  exit 2
+fi
+
+if ! [[ "$LIMIT" =~ ^[1-9][0-9]*$ ]]; then
+  echo "limit must be a positive integer" >&2
+  exit 2
+fi
+
+if ! command -v yt-dlp >/dev/null 2>&1; then
+  echo "yt-dlp not found on PATH" >&2
+  exit 2
+fi
+
+# flat-playlist keeps this a metadata-only discovery call (no download).
+yt-dlp --no-update --flat-playlist --no-warnings \
+  --print '%(title)s | %(channel)s | %(duration_string)s | %(view_count)s | %(upload_date)s | https://youtu.be/%(id)s' \
+  "ytsearch${LIMIT}:${QUERY}"

package/scripts/outbound-artifact-gate.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+
+const HTML_TAG_RE = /<!doctype\s+html|<\/?(?:html|head|body|div|section|article|main|table|thead|tbody|tr|td|th|p|br|span|h[1-6]|ul|ol|li|style|script|a|img|strong|em)\b[^>]*>/i;
+const ENCODED_HTML_RE = /&lt;\/?(?:html|head|body|div|table|tr|td|p|span|h[1-6]|ul|ol|li|style|script|svg)\b/i;
+const RENDERED_SOURCE_FENCE_RE = /```\s*(?:html|xml|jsx|tsx|css|svg|mermaid)\b/i;
+const COACH_INTERNAL_RE = /(?:\b(?:CLI|WEB|BE)-\d+\b|\b[0-9A-HJKMNP-TV-Z]{26}\b|\bmission-[a-z0-9-]+|(?:^|\s)--[a-z][a-z-]*\b|(?:^|\s)(?:\.atris|atris\/runs)\/|(?:^|\s)\/(?:Users|home|workspace|tmp)\/\S+)/im;
+const COACH_PRESSURE_RE = /\b(?:asap|urgent|time-sensitive|immediately|friendly reminder|just checking in|you still haven'?t|don'?t forget|why haven'?t you|you need to|productive day|great work|nice work|good job|keep the streak)\b/i;
+
+const SLOP_RULES = [
+  {
+    id: 'copy-slop-corporate-filler',
+    re: /\b(?:revolutionary|game[- ]changing|cutting[- ]edge|seamlessly|effortlessly|robust|powerful|comprehensive|leverage|utilize|facilitate|synergy|holistic|pivotal|crucial|unlock|supercharge)\b/i,
+    message: 'copy contains corporate filler or hype',
+  },
+  {
+    id: 'copy-slop-ai-tell',
+    re: /\b(?:it'?s worth noting that|as you can see|in order to|at the end of the day|great question|absolutely)\b/i,
+    message: 'copy contains an AI-tell phrase',
+  },
+  {
+    id: 'copy-slop-punctuation',
+    re: /[\u2014\u2728\u{1F680}\u{1F4A1}\u{1F3AF}]/u,
+    message: 'copy contains punctuation or decorative symbols blocked by the anti-slop gate',
+  },
+];
+
+const VALID_FORMATS = new Set(['plain', 'html', 'markdown', 'visual', 'source']);
+const VALID_COACH_SURFACES = new Set(['morning', 'evening', 'warm-ping']);
+
+function usage() {
+  return [
+    'Usage:',
+    '  node scripts/outbound-artifact-gate.js --channel email --format plain --body-file body.txt',
+    '  node scripts/outbound-artifact-gate.js --channel email --format html --body-file body.html --proof-file render.txt',
+    '',
+    'Options:',
+    '  --channel <email|slack|doc|deck|web|other>',
+    '  --format <plain|html|markdown|visual|source>',
+    '  --body <text>',
+    '  --body-file <path>',
+    '  --proof-file <path>   Required for html and visual formats',
+    '  --coach-surface <morning|evening|warm-ping>',
+    '  --signal-proof <path> Required for a warm-ping coach surface',
+    '  --visual              Require visual proof even when format is not visual',
+    '  --allow-slop          Skip anti-slop copy checks',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const options = {
+    channel: 'other',
+    format: 'plain',
+    body: '',
+    bodyFile: null,
+    proofFile: null,
+    coachSurface: null,
+    signalProof: null,
+    visual: false,
+    allowSlop: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+
+    const eq = arg.indexOf('=');
+    const key = (eq === -1 ? arg.slice(2) : arg.slice(2, eq)).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const inlineValue = eq === -1 ? null : arg.slice(eq + 1);
+
+    if (key === 'help') {
+      options.help = true;
+      continue;
+    }
+    if (key === 'visual' || key === 'allowSlop') {
+      options[key] = true;
+      continue;
+    }
+
+    const value = inlineValue !== null ? inlineValue : argv[i + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new Error(`Missing value for --${arg.slice(2)}`);
+    }
+    i += inlineValue === null ? 1 : 0;
+
+    if (!Object.prototype.hasOwnProperty.call(options, key)) {
+      throw new Error(`Unknown option: --${arg.slice(2)}`);
+    }
+    options[key] = value;
+  }
+
+  return options;
+}
+
+function readBody(options) {
+  if (options.bodyFile) {
+    return fs.readFileSync(options.bodyFile, 'utf8');
+  }
+  return String(options.body || '');
+}
+
+function proofExists(proofFile) {
+  if (!proofFile) return false;
+  try {
+    fs.statSync(proofFile);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+function addError(errors, id, message) {
+  errors.push({ id, message });
+}
+
+function scanOutboundArtifact(options, body) {
+  const errors = [];
+  const format = String(options.format || 'plain').toLowerCase();
+  const channel = String(options.channel || 'other').toLowerCase();
+  const coachSurface = options.coachSurface ? String(options.coachSurface).toLowerCase() : null;
+
+  if (!VALID_FORMATS.has(format)) {
+    addError(errors, 'invalid-format', `format must be one of ${Array.from(VALID_FORMATS).join(', ')}`);
+    return errors;
+  }
+
+  if (coachSurface && !VALID_COACH_SURFACES.has(coachSurface)) {
+    addError(errors, 'invalid-coach-surface', `coach surface must be one of ${Array.from(VALID_COACH_SURFACES).join(', ')}`);
+  }
+
+  const sendsSource = format === 'source';
+  const needsRenderProof = format === 'html' || format === 'visual' || options.visual;
+
+  if (format === 'plain' && (HTML_TAG_RE.test(body) || ENCODED_HTML_RE.test(body))) {
+    addError(errors, 'raw-html-in-plain-body', 'plain body contains HTML source; send rendered HTML or rewrite as plain text');
+  }
+
+  if (!sendsSource && RENDERED_SOURCE_FENCE_RE.test(body)) {
+    addError(errors, 'rendered-source-fence', 'body contains source that should be rendered before sending');
+  }
+
+  if (channel === 'email' && format === 'markdown' && RENDERED_SOURCE_FENCE_RE.test(body)) {
+    addError(errors, 'markdown-email-source', 'email body contains fenced rendered source; attach source intentionally or render it first');
+  }
+
+  if (needsRenderProof && !proofExists(options.proofFile)) {
+    addError(errors, 'render-proof-missing', 'HTML or visual sends need --proof-file with preview, screenshot, PDF, or rendered-email receipt');
+  }
+
+  if (coachSurface) {
+    if (COACH_INTERNAL_RE.test(body)) {
+      addError(errors, 'coach-internal-language', 'coach copy contains an internal id, flag, or path');
+    }
+    if (COACH_PRESSURE_RE.test(body)) {
+      addError(errors, 'coach-pressure-language', 'coach copy contains urgency, guilt, nagging, or generic productivity praise');
+    }
+    if (coachSurface === 'warm-ping' && !proofExists(options.signalProof)) {
+      addError(errors, 'coach-signal-proof-missing', 'warm pings need --signal-proof for the fresh human event');
+    }
+  }
+
+  if (!options.allowSlop) {
+    for (const rule of SLOP_RULES) {
+      if (rule.re.test(body)) {
+        addError(errors, rule.id, rule.message);
+      }
+    }
+  }
+
+  return errors;
+}
+
+function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    console.error(err.message);
+    console.error(usage());
+    process.exitCode = 2;
+    return;
+  }
+
+  if (options.help) {
+    console.log(usage());
+    return;
+  }
+
+  let body;
+  try {
+    body = readBody(options);
+  } catch (err) {
+    console.error(`failed to read body: ${err.message}`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const errors = scanOutboundArtifact(options, body);
+  if (errors.length) {
+    console.error('outbound artifact gate failed');
+    for (const error of errors) {
+      console.error(`- ${error.id}: ${error.message}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log('outbound artifact gate passed');
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  HTML_TAG_RE,
+  RENDERED_SOURCE_FENCE_RE,
+  SLOP_RULES,
+  COACH_INTERNAL_RE,
+  COACH_PRESSURE_RE,
+  parseArgs,
+  scanOutboundArtifact,
+};

package/utils/update-check.js

@@ -293,6 +293,20 @@ function formatInstallGitWarning(state) {
     'npm install -g atris@latest may not change the code currently on PATH; resolve that checkout before trusting upgrade status.';
 }
 
+/**
+ * Human version line. Published/sealed installs stay plain.
+ * Git checkouts append `(git <sha> [dirty] <branch>)`.
+ */
+function formatCliVersionLine(version, packageRoot = path.join(__dirname, '..')) {
+  const base = String(version || 'unknown').replace(/^v/, '');
+  if (!isGitCheckout(packageRoot)) return `atris v${base}`;
+  const state = inspectInstallGitState(packageRoot);
+  const sha = state.head || 'unknown';
+  const branch = state.detached ? 'detached' : (state.branch || 'unknown');
+  if (state.dirty) return `atris v${base} (git ${sha} dirty ${branch})`;
+  return `atris v${base} (git ${sha} ${branch})`;
+}
+
 function normalizeAutoUpdateMode(env = process.env) {
   const raw = String(env.ATRIS_AUTO_UPDATE || '').trim().toLowerCase();
   if (['0', 'false', 'no', 'off', 'notify'].includes(raw)) return 'off';
@@ -349,6 +363,7 @@ module.exports = {
   shouldAutoUpdate,
   inspectInstallGitState,
   formatInstallGitWarning,
+  formatCliVersionLine,
   isGitCheckout,
   getNpmSelfUpdateCommand,
   getNpmSelfUpdateSpawnArgs,