tokrepo 3.7.0 → 3.8.0

package/bin/tokrepo.js

@@ -25,7 +25,7 @@ const CONFIG_DIR = path.join(os.homedir(), '.tokrepo');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const PROJECT_CONFIG = '.tokrepo.json';
 const DEFAULT_API = 'https://api.tokrepo.com';
-const CLI_VERSION = '3.7.0';
+const CLI_VERSION = '3.8.0';
 const VERSION_CHECK_FILE = path.join(os.homedir(), '.tokrepo', '.version-check');
 const CODEX_DIR = path.join(os.homedir(), '.codex');
 const CODEX_SKILLS_DIR = path.join(CODEX_DIR, 'skills');
@@ -302,9 +302,9 @@ function parseArgs(argv) {
   }
 
   const valueFlags = new Set([
-    'title', 'desc', 'tag', 'target', 'targets', 'keyword', 'types',
+    'title', 'desc', 'tag', 'target', 'targets', 'keyword', 'query', 'types',
     'kind', 'install-mode', 'install_mode', 'entrypoint', 'asset-kind', 'asset_kind',
-    'version',
+    'version', 'uuid',
     'policy', 'session',
     'page', 'page-size', 'page_size', 'sort-by', 'sort_by',
     'time-window', 'time_window',
@@ -546,13 +546,152 @@ function browserAuthFlow() {
   });
 }
 
-async function cmdPush() {
-  const args = parseArgs(process.argv);
+function inferAssetKindFromPushFiles(files = []) {
+  const normalized = files.map(file => ({
+    ...file,
+    lowerName: String(file.name || '').toLowerCase(),
+    content: String(file.content || ''),
+  }));
+  if (normalized.some(file => /"mcpServers"\s*:/.test(file.content) || /\bmcpServers\s*:/.test(file.content))) return 'mcp_config';
+  if (normalized.some(file => file.type === 'script' || /\.(sh|py|js|mjs|ts|rb|go|rs|lua)$/.test(file.lowerName) || /^#!\//.test(file.content))) return 'script';
+  if (normalized.some(file => file.lowerName === 'package.json' && /"bin"\s*:/.test(file.content))) return 'cli_tool';
+  if (normalized.some(file => file.type === 'skill' || isCodexSkillDocument(file))) return 'skill';
+  if (normalized.some(file => file.type === 'prompt')) return 'prompt';
+  if (normalized.some(file => file.type === 'config')) return 'config';
+  if (normalized.some(file => file.lowerName.endsWith('.md'))) return 'knowledge';
+  return 'other';
+}
 
-  const config = readConfig();
-  if (!config || !config.token) {
-    error(`Not logged in. Run: ${C.cyan}tokrepo login${C.reset}`);
+function analyzePushMetadataQuality(files = [], metadata = {}) {
+  const issues = [];
+  const add = (severity, code, message, fix = '') => {
+    issues.push({ severity, code, message, fix });
+  };
+
+  const normalizedKind = normalizeToolName(metadata.kind || '');
+  const inferredKind = inferAssetKindFromPushFiles(files);
+  const targetTools = parseCsvList(metadata.targetTools).map(normalizeToolName);
+  const installMode = normalizeCodexInstallMode(metadata.installMode);
+  const rawInstallMode = String(metadata.installMode || '').trim();
+  const entrypoint = String(metadata.entrypoint || '').trim();
+  const fileNames = new Set(files.map(file => String(file.name || '').replace(/\\/g, '/')));
+  const lowerFileNames = new Set(Array.from(fileNames).map(name => name.toLowerCase()));
+  const multiFile = files.length > 1;
+  const riskFlags = Array.from(new Set(files.flatMap(file => analyzeInstallRisks(file.name, file.content, file.type))));
+  const containsCodex = targetTools.includes('codex');
+
+  if (!normalizedKind) {
+    add('warning', 'missing_asset_kind', `No asset_kind was provided; inferred "${inferredKind}".`, `Recommended: --kind ${inferredKind}`);
+  } else if (!['skill', 'prompt', 'knowledge', 'mcp_config', 'script', 'cli_tool', 'config', 'pack', 'other'].includes(normalizedKind)) {
+    add('warning', 'unknown_asset_kind', `Unknown asset_kind "${metadata.kind}".`, 'Recommended: use skill, prompt, knowledge, mcp_config, script, cli_tool, config, or pack.');
+  }
+
+  if (targetTools.length === 0) {
+    add('warning', 'missing_target_tools', 'No target_tools metadata was provided.', 'Recommended: --target codex or --targets codex,claude_code,gemini_cli.');
+  }
+
+  const invalidTargets = targetTools.filter(tool => !['codex', 'claude_code', 'gemini_cli', 'cursor', 'windsurf', 'opencode'].includes(tool));
+  if (invalidTargets.length > 0) {
+    add('info', 'unknown_target_tool', `Unknown target tool(s): ${invalidTargets.join(', ')}.`, 'Use stable ids when possible: codex, claude_code, gemini_cli, cursor, windsurf.');
+  }
+
+  if (rawInstallMode && !installMode) {
+    add('warning', 'unknown_install_mode', `Unknown install_mode "${metadata.installMode}".`, 'Recommended: single, bundle, split, or stage_only.');
+  } else if (!rawInstallMode && (multiFile || containsCodex)) {
+    add('warning', 'missing_install_mode', `No install_mode was provided for ${multiFile ? 'a multi-file asset' : 'a Codex-targeted asset'}.`, `Recommended: --install-mode ${multiFile ? 'bundle' : 'single'}.`);
+  }
+
+  if (entrypoint && !fileNames.has(entrypoint) && !lowerFileNames.has(entrypoint.toLowerCase())) {
+    add('warning', 'entrypoint_missing', `Entrypoint "${entrypoint}" is not included in the pushed files.`, 'Recommended: set --entrypoint to an included file, usually SKILL.md.');
+  }
+
+  if (!entrypoint && (installMode === 'single' || installMode === 'bundle' || containsCodex)) {
+    add('warning', 'missing_entrypoint', 'No entrypoint metadata was provided.', 'Recommended: --entrypoint SKILL.md or the main markdown file.');
+  }
+
+  const effectiveKind = normalizedKind || inferredKind;
+  if (containsCodex && ['script', 'cli_tool', 'mcp_config'].includes(effectiveKind) && installMode !== 'stage_only') {
+    add('warning', 'high_risk_codex_activation', `${effectiveKind} assets targeted at Codex should stage by default.`, 'Recommended: --install-mode stage_only or publish a markdown skill wrapper.');
+  }
+  if (riskFlags.includes('executable')) {
+    add('warning', 'executes_code_detected', 'Executable code was detected in the asset files.', 'Recommended: declare script/cli_tool or use stage_only for agent installs.');
+  }
+  if (riskFlags.includes('mcp')) {
+    add('warning', 'mcp_config_detected', 'MCP config content was detected.', 'Recommended: --kind mcp_config --install-mode stage_only.');
+  }
+  if (riskFlags.includes('env')) {
+    add('info', 'secret_or_env_mentions', 'Environment variable or secret-like words were mentioned.', 'Check this is documentation only and no real secret is included.');
+  }
+  if (riskFlags.includes('absolute-path')) {
+    add('warning', 'absolute_path_detected', 'Absolute local paths were detected.', 'Recommended: replace machine-specific paths with placeholders.');
+  }
+
+  if (containsCodex && effectiveKind === 'skill') {
+    const skillDocs = files.filter(file => isCodexSkillDocument(file));
+    if (installMode === 'split' && skillDocs.length !== files.length) {
+      add('warning', 'split_requires_skill_docs', 'install_mode=split works best when every markdown file has skill frontmatter.', 'Recommended: use bundle or add name/description frontmatter to each split skill.');
+    }
+    if (skillDocs.length === 0) {
+      add('warning', 'missing_codex_skill_frontmatter', 'No Codex skill frontmatter was found.', 'Recommended: add YAML frontmatter with name and description.');
+    }
+  }
+
+  const severityPenalty = issues.reduce((sum, issue) => {
+    if (issue.severity === 'warning') return sum + 10;
+    return sum + 2;
+  }, 0);
+  const score = Math.max(0, 100 - severityPenalty);
+  const status = issues.some(issue => issue.severity === 'warning') ? 'warn' : 'pass';
+
+  return {
+    score,
+    status,
+    inferredAssetKind: inferredKind,
+    assetKind: normalizedKind || '',
+    targetTools,
+    installMode: installMode || '',
+    entrypoint,
+    riskFlags,
+    issueCount: issues.length,
+    issues,
+  };
+}
+
+function formatMetadataQualityLabel(report) {
+  const color = report.status === 'pass' ? C.green : C.yellow;
+  return `${color}${report.status}${C.reset} ${C.bold}${report.score}/100${C.reset}`;
+}
+
+function printMetadataQualityReport(report, opts = {}) {
+  const compact = Boolean(opts.compact);
+  if (!compact) {
+    log(`\n${C.bold}Agent metadata quality${C.reset}`);
+    log(`  Status: ${formatMetadataQualityLabel(report)}`);
+    log(`  Inferred kind: ${report.inferredAssetKind}`);
+    if (report.targetTools.length) log(`  Targets: ${report.targetTools.join(', ')}`);
+    if (report.installMode) log(`  Install mode: ${report.installMode}`);
+    if (report.riskFlags.length) log(`  Risk flags: ${report.riskFlags.join(', ')}`);
+  } else {
+    log(`${C.bold}Agent metadata quality suggestions:${C.reset}`);
+  }
+
+  if (report.issues.length === 0) {
+    if (!compact) success('Metadata is agent-ready.');
+    return;
   }
+  for (const issue of report.issues.slice(0, compact ? 8 : report.issues.length)) {
+    const color = issue.severity === 'warning' ? C.yellow : C.dim;
+    log(`  ${color}${issue.severity.toUpperCase()}${C.reset} ${issue.code}: ${issue.message}`);
+    if (issue.fix) log(`    ${C.dim}${issue.fix}${C.reset}`);
+  }
+  if (compact && report.issues.length > 8) {
+    log(`  ${C.dim}...and ${report.issues.length - 8} more suggestion(s). Run --metadata-report for full detail.${C.reset}`);
+  }
+  if (!compact) log('');
+}
+
+async function cmdPush() {
+  const args = parseArgs(process.argv);
 
   const projectConfig = readProjectConfig();
   const baseDir = process.cwd();
@@ -623,6 +762,31 @@ async function cmdPush() {
     error('No readable text files found to push.');
   }
 
+  const metadataQuality = analyzePushMetadataQuality(pushFiles, {
+    kind,
+    targetTools,
+    installMode,
+    entrypoint,
+    title,
+    description,
+  });
+
+  if (args.flags.metadata_report || args.flags.metadataReport) {
+    if (args.flags.json) {
+      outputJson({ schemaVersion: 1, metadataQuality, files: pushFiles.map(file => ({ name: file.name, type: file.type, bytes: Buffer.byteLength(file.content || '') })) });
+    } else {
+      printMetadataQualityReport(metadataQuality);
+    }
+    return;
+  }
+
+  // Public registry policy: quality gates advise by default and never block user uploads.
+  // TokRepo-owned CI can opt into strict mode with TOKREPO_METADATA_STRICT=1.
+  if (process.env.TOKREPO_METADATA_STRICT === '1' && metadataQuality.issues.length > 0 && !args.flags.force) {
+    if (!args.flags.json) printMetadataQualityReport(metadataQuality);
+    error(`Internal metadata quality gate failed. Fix the issues or re-run with --force to push anyway.`);
+  }
+
   // Show summary
   log(`\n${C.bold}tokrepo push${C.reset}\n`);
   log(`  ${C.bold}Title:${C.reset}      ${title}`);
@@ -640,6 +804,7 @@ async function cmdPush() {
   if (metadataSummary.length > 0) {
     log(`  ${C.bold}Agent meta:${C.reset} ${metadataSummary.join(' · ')}`);
   }
+  log(`  ${C.bold}Agent quality:${C.reset} ${formatMetadataQualityLabel(metadataQuality)}`);
   log('');
 
   for (const f of pushFiles) {
@@ -650,9 +815,18 @@ async function cmdPush() {
 
   const totalChars = pushFiles.reduce((sum, f) => sum + f.content.length, 0);
 
+  if (metadataQuality.issues.length > 0) {
+    printMetadataQualityReport(metadataQuality, { compact: true });
+  }
+
   // Push
   info('Pushing...');
 
+  const config = readConfig();
+  if (!config || !config.token) {
+    error(`Not logged in. Run: ${C.cyan}tokrepo login${C.reset}`);
+  }
+
   try {
     const data = await apiRequest('POST', '/api/v1/tokenboard/push/upsert', {
       title,
@@ -2793,6 +2967,145 @@ async function fetchServerCodexInstallPlan(uuid, config, apiBase) {
   }
 }
 
+function runSelfCliJson(cliArgs, opts = {}) {
+  const childProcess = require('child_process');
+  const stdout = childProcess.execFileSync(process.execPath, [__filename, ...cliArgs], {
+    env: { ...process.env, ...(opts.env || {}), TOKREPO_NONINTERACTIVE: '1' },
+    cwd: opts.cwd || process.cwd(),
+    encoding: 'utf8',
+    maxBuffer: 50 * 1024 * 1024,
+  });
+  return JSON.parse(stdout);
+}
+
+function makeEvalResult(name, ok, details = {}) {
+  return {
+    name,
+    ok: Boolean(ok),
+    status: ok ? 'pass' : 'fail',
+    ...details,
+  };
+}
+
+function createTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+}
+
+async function cmdEvalAgent() {
+  const args = parseArgs(process.argv);
+  const json = Boolean(args.flags.json);
+  const sampleUuid = args.flags.uuid || '91aeb22d-eff0-4310-abc6-811d2394b420';
+  const query = args.flags.keyword || args.flags.query || 'video';
+  const keepTemp = Boolean(args.flags.keep_temp || args.flags.keepTemp);
+  const startedAt = new Date().toISOString();
+  const results = [];
+  const tempRoots = [];
+
+  if (!json) log(`\n${C.bold}tokrepo eval-agent${C.reset}\n`);
+
+  const runScenario = async (name, fn) => {
+    const start = Date.now();
+    try {
+      const details = await fn();
+      const result = makeEvalResult(name, true, { durationMs: Date.now() - start, ...details });
+      results.push(result);
+      if (!json) success(`${name} (${result.durationMs}ms)`);
+    } catch (e) {
+      const result = makeEvalResult(name, false, { durationMs: Date.now() - start, error: e.message });
+      results.push(result);
+      if (!json) warn(`${name}: ${e.message}`);
+    }
+  };
+
+  await runScenario('search_filters_codex_allow_skill', async () => {
+    const data = runSelfCliJson(['search', query, '--target', 'codex', '--kind', 'skill', '--policy', 'allow', '--json', '--page-size', '10']);
+    if (!data.count || !Array.isArray(data.list)) throw new Error('filtered search returned no list');
+    const bad = data.list.find(item => item.policyDecision?.decision && item.policyDecision.decision !== 'allow');
+    if (bad) throw new Error(`search returned non-allow asset ${bad.uuid}`);
+    return { count: data.count, firstUuid: data.list[0]?.uuid, firstTitle: data.list[0]?.title };
+  });
+
+  await runScenario('install_plan_contract', async () => {
+    const plan = runSelfCliJson(['plan', sampleUuid, '--target', 'codex']);
+    if (plan.schemaVersion !== 2) throw new Error(`expected schemaVersion 2, got ${plan.schemaVersion}`);
+    if (!plan.policyDecision?.decision) throw new Error('missing policyDecision');
+    if (!Array.isArray(plan.actions) || plan.actions.length === 0) throw new Error('missing actions');
+    if (!Array.isArray(plan.rollback) || plan.rollback.length === 0) throw new Error('missing rollback');
+    if (!Array.isArray(plan.postVerify) || plan.postVerify.length === 0) throw new Error('missing postVerify');
+    return {
+      sourceOfTruth: plan.sourceOfTruth,
+      concretePlanSource: plan.concretePlanSource,
+      policy: plan.policyDecision.decision,
+      actions: plan.actions.length,
+    };
+  });
+
+  await runScenario('metadata_quality_report_non_blocking', async () => {
+    const tmp = createTempDir('tokrepo-eval-quality');
+    tempRoots.push(tmp);
+    const skillPath = path.join(tmp, 'SKILL.md');
+    fs.writeFileSync(skillPath, `---\nname: eval-agent-sample\ndescription: \"Sample skill used by tokrepo eval-agent.\"\n---\n\n# Eval Agent Sample\n\nUse this to test metadata quality reporting.\n`);
+    const report = runSelfCliJson(['push', skillPath, '--metadata-report', '--json', '--kind', 'skill', '--target', 'codex', '--install-mode', 'single', '--entrypoint', 'SKILL.md']);
+    if (!report.metadataQuality) throw new Error('missing metadataQuality');
+    if (report.metadataQuality.status !== 'pass') throw new Error(`expected pass, got ${report.metadataQuality.status}`);
+    return { score: report.metadataQuality.score, status: report.metadataQuality.status };
+  });
+
+  await runScenario('codex_install_verify_and_rollback', async () => {
+    const tmpHome = createTempDir('tokrepo-eval-home');
+    tempRoots.push(tmpHome);
+    const env = { HOME: tmpHome };
+    const install = runSelfCliJson(['install', sampleUuid, '--target', 'codex', '--yes', '--json'], { env });
+    if (!install.sessionId) throw new Error('install did not create sessionId');
+    if (!install.verification?.ok) throw new Error('install verification failed');
+    if (!install.installedFiles?.length) throw new Error('no files installed');
+    const installed = runSelfCliJson(['installed', '--target', 'codex', '--json'], { env });
+    if (installed.count < 1) throw new Error('installed manifest did not record asset');
+    const rollback = runSelfCliJson(['rollback', '--last', '--target', 'codex', '--json'], { env });
+    if (!rollback.removedFiles?.length) throw new Error('rollback removed no files');
+    const after = runSelfCliJson(['installed', '--target', 'codex', '--json'], { env });
+    if (after.count !== 0) throw new Error(`manifest still has ${after.count} install(s) after rollback`);
+    return {
+      installedFiles: install.installedFiles.length,
+      sessionId: install.sessionId,
+      removedFiles: rollback.removedFiles.length,
+    };
+  });
+
+  if (!keepTemp) {
+    for (const dir of tempRoots) {
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+    }
+  }
+
+  const failed = results.filter(result => !result.ok);
+  const summary = {
+    schemaVersion: 1,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    cliVersion: CLI_VERSION,
+    targetTool: 'codex',
+    sampleUuid,
+    query,
+    status: failed.length === 0 ? 'pass' : 'fail',
+    passed: results.length - failed.length,
+    failed: failed.length,
+    count: results.length,
+    tempRoots: keepTemp ? tempRoots : [],
+    results,
+  };
+
+  if (json) {
+    outputJson(summary);
+  } else {
+    log('');
+    if (summary.status === 'pass') success(`Agent eval passed: ${summary.passed}/${summary.count}`);
+    else warn(`Agent eval failed: ${summary.failed}/${summary.count}`);
+  }
+
+  if (failed.length > 0) process.exitCode = 1;
+}
+
 async function cmdSyncInstalled() {
   const args = parseArgs(process.argv);
   const targetTool = validateInstallTarget(args.flags.target || 'codex');
@@ -3439,6 +3752,7 @@ ${C.bold}DISCOVER & INSTALL${C.reset}
   ${C.cyan}sync-installed${C.reset}       Update installed Codex assets from manifest
   ${C.cyan}uninstall${C.reset} <uuid>     Remove a managed Codex install
   ${C.cyan}rollback${C.reset} --last      Roll back the latest Codex install session
+  ${C.cyan}eval-agent${C.reset}           Run agent-native contract and lifecycle evals
 
 ${C.bold}PUBLISH${C.reset}
   ${C.cyan}push${C.reset} [files...]     Push files/directory (idempotent upsert)
@@ -3464,6 +3778,7 @@ ${C.bold}PUSH OPTIONS${C.reset}
   ${C.cyan}--kind${C.reset} skill         Set agent asset_kind
   ${C.cyan}--target${C.reset} codex       Add target tool metadata on push
   ${C.cyan}--install-mode${C.reset} bundle Set install_mode metadata
+  ${C.cyan}--metadata-report${C.reset}    Print agent metadata quality suggestions without pushing
 
 ${C.bold}INSTALL BEHAVIOR${C.reset}
   Skills   → .claude/skills/    (if .claude/ exists)
@@ -3489,7 +3804,9 @@ ${C.bold}EXAMPLES${C.reset}
   tokrepo sync-installed --target codex --dry-run
   tokrepo uninstall 91aeb22d --target codex --dry-run
   tokrepo rollback --last --target codex --dry-run
+  tokrepo eval-agent --json
   tokrepo push --private my-rules.md          # Save one file privately
+  tokrepo push . --metadata-report --json     # Check agent metadata without uploading
   tokrepo push . --kind skill --target codex --install-mode bundle
   tokrepo push --public skill.md              # Share one file publicly
   tokrepo push --private .                    # Push current dir as private
@@ -3666,6 +3983,25 @@ EXAMPLES
 `);
 }
 
+function showEvalAgentHelp() {
+  log(`
+${C.bold}tokrepo eval-agent${C.reset}
+
+USAGE
+  tokrepo eval-agent [--json] [--uuid <asset-uuid>] [--keyword video] [--keep-temp]
+
+BEHAVIOR
+  Runs agent-native smoke evals against search filters, install-plan contracts,
+  metadata quality reporting, Codex install verification, manifest state, and rollback.
+  Lifecycle tests use a temporary HOME and do not touch your real ~/.codex.
+
+EXAMPLES
+  tokrepo eval-agent
+  tokrepo eval-agent --json
+  tokrepo eval-agent --uuid 91aeb22d-eff0-4310-abc6-811d2394b420 --keyword video --json
+`);
+}
+
 function showCommandHelp(command) {
   switch (command) {
     case 'search':
@@ -3693,6 +4029,9 @@ function showCommandHelp(command) {
       showUninstallHelp(); break;
     case 'rollback':
       showRollbackHelp(); break;
+    case 'eval-agent':
+    case 'eval':
+      showEvalAgentHelp(); break;
     default:
       showHelp(); break;
   }
@@ -3725,6 +4064,7 @@ async function main() {
     case 'installed': await cmdInstalled(); break;
     case 'uninstall': case 'remove': case 'rm': await cmdUninstall(); break;
     case 'rollback': await cmdRollback(); break;
+    case 'eval-agent': case 'eval': await cmdEvalAgent(); break;
     case 'outdated': await cmdOutdated(); break;
     case 'sync-installed': case 'sync': await cmdSyncInstalled(); break;
     case 'tags': await cmdTags(); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokrepo",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "AI assets for humans and agents — search, install, push. Like GitHub, for AI experience.",
   "bin": {
     "tokrepo": "bin/tokrepo.js"