tokrepo 3.5.0 → 3.6.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.5.0';
+const CLI_VERSION = '3.6.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');
@@ -1278,8 +1278,161 @@ function buildCodexInstallPlan(workflow, contents, opts = {}) {
   return plan;
 }
 
+function metadataValue(metadata, snakeName, camelName, fallback) {
+  if (!metadata) return fallback;
+  if (metadata[snakeName] !== undefined) return metadata[snakeName];
+  if (metadata[camelName] !== undefined) return metadata[camelName];
+  return fallback;
+}
+
+function normalizeToolName(value) {
+  return String(value || '').trim().toLowerCase().replace(/-/g, '_');
+}
+
+function riskProfileFromFlags(flags = []) {
+  const set = new Set(flags || []);
+  return {
+    executes_code: set.has('executable'),
+    modifies_global_config: set.has('mcp'),
+    requires_secrets: set.has('env') ? ['ENV'] : [],
+    uses_absolute_paths: set.has('absolute-path'),
+    network_access: set.has('network'),
+  };
+}
+
+function mergedPlanRiskProfile(plan) {
+  const metadata = plan.agentMetadata || {};
+  const rp = metadataValue(metadata, 'risk_profile', 'riskProfile', {}) || {};
+  const flags = new Set(plan.risks || []);
+  return {
+    executes_code: Boolean(rp.executes_code || rp.executesCode || flags.has('executable')),
+    modifies_global_config: Boolean(rp.modifies_global_config || rp.modifiesGlobalConfig || flags.has('mcp')),
+    requires_secrets: rp.requires_secrets || rp.requiresSecrets || (flags.has('env') ? ['ENV'] : []),
+    uses_absolute_paths: Boolean(rp.uses_absolute_paths || rp.usesAbsolutePaths || flags.has('absolute-path')),
+    network_access: Boolean(rp.network_access || rp.networkAccess || flags.has('network')),
+  };
+}
+
+function decideCodexPolicy(plan) {
+  const metadata = plan.agentMetadata || {};
+  const targetTools = metadataValue(metadata, 'target_tools', 'targetTools', []) || [];
+  const assetKind = normalizeToolName(metadataValue(metadata, 'asset_kind', 'assetKind', ''));
+  const risk = mergedPlanRiskProfile(plan);
+  let decision = 'allow';
+  const reasons = [];
+  const raise = (next) => {
+    const rank = { allow: 0, confirm: 1, stage_only: 2, deny: 3 };
+    if ((rank[next] || 0) > (rank[decision] || 0)) decision = next;
+  };
+
+  if (targetTools.length && !targetTools.map(normalizeToolName).includes('codex')) {
+    raise('confirm');
+    reasons.push('metadata target_tools does not include codex');
+  }
+  if (['script', 'cli_tool', 'mcp_config'].includes(assetKind)) {
+    raise('stage_only');
+    reasons.push(`asset_kind ${assetKind} is not activated directly for Codex`);
+  }
+  if (plan.installMode === 'stage_only') {
+    raise('stage_only');
+    reasons.push('install_mode is stage_only');
+  }
+  if (risk.executes_code) {
+    raise('stage_only');
+    reasons.push('risk_profile.executes_code is true');
+  }
+  if (risk.modifies_global_config) {
+    raise('stage_only');
+    reasons.push('risk_profile.modifies_global_config is true');
+  }
+  if ((risk.requires_secrets || []).length) {
+    raise('stage_only');
+    reasons.push('risk_profile.requires_secrets is not empty');
+  }
+  if (risk.uses_absolute_paths) {
+    raise('confirm');
+    reasons.push('risk_profile.uses_absolute_paths is true');
+  }
+  if (risk.network_access) {
+    raise('confirm');
+    reasons.push('risk_profile.network_access is true');
+  }
+  if (reasons.length === 0) reasons.push('safe markdown-only Codex install');
+
+  return {
+    decision,
+    requiresConfirmation: decision === 'confirm',
+    reasons: Array.from(new Set(reasons)),
+  };
+}
+
+function buildPublicPlanActions(plan) {
+  const stage = plan.installMode === 'stage_only';
+  return plan.files.map(file => ({
+    type: stage ? 'stage_file' : 'write_file',
+    path: file.path,
+    sourceName: file.sourceName,
+    sha256: file.sha256,
+    bytes: file.bytes,
+    ifExists: 'overwrite',
+    entrypoint: path.basename(file.path).toLowerCase() === 'skill.md',
+    risk: riskProfileFromFlags(file.riskFlags || []),
+  }));
+}
+
+function buildPublicPlanPreconditions(plan, policyDecision) {
+  const metadata = plan.agentMetadata || {};
+  const targetTools = metadataValue(metadata, 'target_tools', 'targetTools', []) || [];
+  const out = [
+    { type: 'target_supported', status: 'pass', message: 'codex install target is supported' },
+    { type: 'install_root', status: 'pass', message: '~/.codex/skills for activated skills; ~/.codex/tokrepo/staged for staged assets' },
+  ];
+  if (!targetTools.length || targetTools.map(normalizeToolName).includes('codex')) {
+    out.push({ type: 'target_tool_metadata', status: 'pass', message: 'metadata allows codex' });
+  } else {
+    out.push({ type: 'target_tool_metadata', status: 'warn', message: 'metadata target_tools does not include codex' });
+  }
+  out.push({
+    type: 'content_hash',
+    status: plan.contentHash ? 'pass' : 'warn',
+    message: plan.contentHash ? 'asset metadata includes content_hash' : 'asset metadata does not include content_hash',
+  });
+  const policyStatus = policyDecision.decision === 'deny' ? 'block'
+    : policyDecision.decision === 'allow' ? 'pass'
+    : 'warn';
+  out.push({ type: 'policy_decision', status: policyStatus, message: `${policyDecision.decision} for ${plan.uuid}` });
+  return out;
+}
+
+function buildPublicPlanRollback(plan) {
+  const seen = new Set();
+  const rollback = [];
+  for (const file of plan.files) {
+    if (!file.path || seen.has(file.path)) continue;
+    seen.add(file.path);
+    rollback.push({ type: 'remove_file', path: file.path });
+  }
+  return rollback;
+}
+
+function buildPublicPlanPostVerify(plan) {
+  const metadata = plan.agentMetadata || {};
+  const verification = metadataValue(metadata, 'verification', 'verification', {}) || {};
+  const out = plan.files.map(file => ({ type: 'file_sha256', path: file.path, sha256: file.sha256 }));
+  for (const expected of (verification.expected_files || verification.expectedFiles || [])) {
+    out.push({ type: 'expected_file', path: expected });
+  }
+  for (const command of (verification.commands || [])) {
+    out.push({ type: 'command', command });
+  }
+  return out;
+}
+
 function publicInstallPlan(plan) {
+  const policyDecision = decideCodexPolicy(plan);
+  const actions = buildPublicPlanActions(plan);
   return {
+    schemaVersion: 2,
     uuid: plan.uuid,
     title: plan.title,
     sourceUrl: plan.sourceUrl,
@@ -1288,7 +1441,12 @@ function publicInstallPlan(plan) {
     manifestPath: plan.manifestPath,
     baseDir: plan.baseDir,
     risks: plan.risks,
-    requiresConfirmation: hasCodexInstallRisks(plan),
+    preconditions: buildPublicPlanPreconditions(plan, policyDecision),
+    actions,
+    policyDecision,
+    requiresConfirmation: policyDecision.requiresConfirmation,
+    rollback: buildPublicPlanRollback(plan),
+    postVerify: buildPublicPlanPostVerify(plan),
     contentHash: plan.contentHash || '',
     agentMetadata: plan.agentMetadata || {},
     files: plan.files.map(file => ({
@@ -1303,7 +1461,8 @@ function publicInstallPlan(plan) {
 }
 
 function hasCodexInstallRisks(plan) {
-  return (plan.risks || []).some(risk => ['mcp', 'executable', 'env', 'absolute-path'].includes(risk));
+  const decision = decideCodexPolicy(plan).decision;
+  return decision === 'confirm' || decision === 'stage_only' || decision === 'deny';
 }
 
 function formatRiskLine(file) {
@@ -1312,15 +1471,19 @@ function formatRiskLine(file) {
 }
 
 async function confirmCodexInstallRisks(plan, opts = {}) {
+  const policy = decideCodexPolicy(plan);
+  if (policy.decision === 'deny') {
+    throw new Error(`Install policy denied this asset: ${policy.reasons.join('; ')}`);
+  }
   if (plan.installMode === 'stage_only') return;
-  if (opts.dryRun || opts.stage || !hasCodexInstallRisks(plan)) return;
+  if (opts.dryRun || opts.stage || policy.decision === 'allow') return;
   if (opts.approveMcp || opts.approve_mcp || opts.yes) return;
 
   if (opts.json || opts.throwOnError || process.env.TOKREPO_NONINTERACTIVE === '1') {
-    throw new Error(`Install plan includes risky content (${plan.risks.join(', ')}). Re-run with --dry-run to inspect or --approve-mcp to approve writing the Codex skill bundle.`);
+    throw new Error(`Install policy is ${policy.decision}: ${policy.reasons.join('; ')}. Re-run with --dry-run to inspect, --stage to stage the plan, or --approve-mcp to approve writing the Codex skill bundle.`);
   }
 
-  warn(`This asset contains ${plan.risks.join(', ')} content.`);
+  warn(`Install policy is ${policy.decision}: ${policy.reasons.join('; ')}`);
   log(`  ${C.dim}TokRepo will only write files under ${CODEX_SKILLS_DIR}; it will not merge MCP configs, modify PATH, or execute scripts.${C.reset}`);
   const riskyFiles = plan.files
     .map(formatRiskLine)
@@ -1488,6 +1651,33 @@ async function cmdInstall() {
   }
 }
 
+async function cmdPlan() {
+  const args = parseArgs(process.argv);
+  const target = args.positional[0];
+  if (!target) {
+    showPlanHelp();
+    process.exit(1);
+  }
+
+  const config = readConfig();
+  const apiBase = config?.api || DEFAULT_API;
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') {
+    error(`plan currently supports --target codex only`);
+  }
+  const result = await installOneAsset(target, config, apiBase, {
+    targetTool,
+    dryRun: true,
+    stage: Boolean(args.flags.stage),
+    installMode: args.flags.installMode,
+    json: true,
+    manifest: true,
+    throwOnError: true,
+  });
+
+  outputJson(result.plan);
+}
+
 // Install all assets in a theme pack — sequentially, continue past per-item errors
 async function installPack(slug, config, apiBase, opts) {
   info(`Fetching pack ${C.bold}${slug}${C.reset}...`);
@@ -2546,6 +2736,7 @@ ${C.bold}USAGE${C.reset}
 ${C.bold}DISCOVER & INSTALL${C.reset}
   ${C.cyan}search${C.reset} <query>      Search assets by keyword
   ${C.cyan}detail${C.reset} <name|uuid>  Show full asset metadata
+  ${C.cyan}plan${C.reset} <name|uuid>    Print agent-native Codex install plan
   ${C.cyan}install${C.reset} <name|uuid> Smart install (auto-detects type & placement)
   ${C.cyan}pull${C.reset} <url|uuid|@u/n> Download raw asset files
   ${C.cyan}clone${C.reset} @username      Clone all assets from a user
@@ -2591,6 +2782,7 @@ ${C.bold}EXAMPLES${C.reset}
   tokrepo search "mcp server"                 # Find MCP configs
   tokrepo search video --json                 # Machine-readable search
   tokrepo detail ca000374-f5d8-... --json     # Machine-readable detail
+  tokrepo plan 91aeb22d-eff0-4310-...         # Install plan v2 for agents
   tokrepo install ca000374-f5d8-...           # Install by UUID
   tokrepo install ca000374-f5d8-... --target codex
   tokrepo install c4b18aeb --target gemini    # Install for Gemini CLI
@@ -2670,6 +2862,23 @@ EXAMPLES
 `);
 }
 
+function showPlanHelp() {
+  log(`
+${C.bold}tokrepo plan${C.reset}
+
+USAGE
+  tokrepo plan <uuid|url|name> [--target codex] [--stage]
+
+OUTPUT
+  Machine-readable install plan v2 with preconditions, actions, policyDecision,
+  rollback, postVerify, risk metadata, and destination file hashes.
+
+EXAMPLES
+  tokrepo plan 91aeb22d-eff0-4310-abc6-811d2394b420
+  tokrepo plan https://tokrepo.com/en/workflows/91aeb22d-eff0-4310-abc6-811d2394b420
+`);
+}
+
 function showListHelp() {
   log(`
 ${C.bold}tokrepo list${C.reset}
@@ -2729,6 +2938,8 @@ function showCommandHelp(command) {
       showSearchHelp(); break;
     case 'detail':
       showDetailHelp(); break;
+    case 'plan':
+      showPlanHelp(); break;
     case 'install':
     case 'i':
       showInstallHelp(); break;
@@ -2764,6 +2975,7 @@ async function main() {
     case 'pull': await cmdPull(); break;
     case 'search': case 'find': await cmdSearch(); break;
     case 'detail': await cmdDetail(); break;
+    case 'plan': await cmdPlan(); break;
     case 'install': case 'i': await cmdInstall(); break;
     case 'list': await cmdList(); break;
     case 'update': await cmdUpdate(); break;
@@ -2784,7 +2996,7 @@ async function main() {
   }
 
   // Non-blocking update check after command completes
-  if (!wantsJson(process.argv) && !args.flags.help) {
+  if (command !== 'plan' && !wantsJson(process.argv) && !args.flags.help) {
     checkForUpdate();
   }
 }

package/package.json

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