tokrepo 3.4.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.4.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');
@@ -236,6 +236,12 @@ function guessTag(fileType) {
   return map[fileType] || null;
 }
 
+function parseCsvList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.flatMap(parseCsvList);
+  return String(value).split(',').map(s => s.trim()).filter(Boolean);
+}
+
 // ─── Glob matching ───
 
 function matchGlob(pattern, filename) {
@@ -295,7 +301,9 @@ function parseArgs(argv) {
   }
 
   const valueFlags = new Set([
-    'title', 'desc', 'tag', 'target', 'keyword', 'types',
+    'title', 'desc', 'tag', 'target', 'targets', 'keyword', 'types',
+    'kind', 'install-mode', 'install_mode', 'entrypoint', 'asset-kind', 'asset_kind',
+    'version',
     'page', 'page-size', 'page_size', 'sort-by', 'sort_by',
     'time-window', 'time_window',
   ]);
@@ -318,6 +326,10 @@ function parseArgs(argv) {
       args.flags.dryRun = value;
     } else if (normalized === 'approve_mcp') {
       args.flags.approveMcp = value;
+    } else if (normalized === 'install_mode') {
+      args.flags.installMode = value;
+    } else if (normalized === 'asset_kind') {
+      args.flags.assetKind = value;
     }
     args.flags[normalized] = value;
   };
@@ -574,6 +586,10 @@ async function cmdPush() {
   description = args.flags.desc || description || '';
   visibility = args.flags.public ? 1 : (args.flags.private ? 0 : (projectConfig?.visibility ?? 0));
   tags = args.flags.tags || tags || [];
+  const kind = args.flags.kind || args.flags.assetKind || projectConfig?.kind || projectConfig?.asset_kind || '';
+  const targetTools = parseCsvList(args.flags.targets || args.flags.target || projectConfig?.target_tools || projectConfig?.targetTools);
+  const installMode = args.flags.installMode || projectConfig?.install_mode || projectConfig?.installMode || '';
+  const entrypoint = args.flags.entrypoint || projectConfig?.entrypoint || '';
 
   // Read files and detect types
   const pushFiles = [];
@@ -613,6 +629,15 @@ async function cmdPush() {
   if (detectedTags.size > 0) {
     log(`  ${C.bold}Tags:${C.reset}       ${Array.from(detectedTags).join(', ')}`);
   }
+  const metadataSummary = [
+    kind ? `kind=${kind}` : '',
+    targetTools.length ? `target_tools=${targetTools.join(',')}` : '',
+    installMode ? `install_mode=${installMode}` : '',
+    entrypoint ? `entrypoint=${entrypoint}` : '',
+  ].filter(Boolean);
+  if (metadataSummary.length > 0) {
+    log(`  ${C.bold}Agent meta:${C.reset} ${metadataSummary.join(' · ')}`);
+  }
   log('');
 
   for (const f of pushFiles) {
@@ -634,6 +659,10 @@ async function cmdPush() {
       tags: Array.from(detectedTags),
       token_cost: String(Math.round(totalChars / 4)),
       visibility: visibility,
+      kind,
+      target_tools: targetTools,
+      install_mode: installMode,
+      entrypoint,
     }, config.token, config.api);
 
     log('');
@@ -1095,11 +1124,13 @@ function explicitInstallMode(workflow) {
   const candidates = [
     workflow?.installMode,
     workflow?.install_mode,
+    workflow?.agent_metadata?.install_mode,
+    workflow?.agentMetadata?.installMode,
     workflow?.metadata?.installMode,
     workflow?.metadata?.install_mode,
   ].filter(Boolean);
   const mode = String(candidates[0] || '').toLowerCase();
-  return ['single', 'bundle', 'split'].includes(mode) ? mode : '';
+  return ['single', 'bundle', 'split', 'stage_only'].includes(mode) ? mode : '';
 }
 
 function inferCodexInstallMode(workflow, contents) {
@@ -1157,6 +1188,7 @@ function addPlanFile(plan, destPath, content, sourceName, type) {
 
 function buildCodexInstallPlan(workflow, contents, opts = {}) {
   const installMode = opts.installMode || inferCodexInstallMode(workflow, contents);
+  const agentMetadata = workflow?.agent_metadata || workflow?.agentMetadata || {};
   const plan = {
     uuid: workflow.uuid,
     title: workflow.title,
@@ -1166,8 +1198,20 @@ function buildCodexInstallPlan(workflow, contents, opts = {}) {
     manifestPath: CODEX_MANIFEST_FILE,
     files: [],
     risks: [],
+    agentMetadata,
+    contentHash: workflow.content_hash || workflow.contentHash || agentMetadata.content_hash || '',
   };
 
+  if (installMode === 'stage_only') {
+    const stageDir = path.join(CODEX_TOKREPO_DIR, 'staged', workflow.uuid);
+    plan.baseDir = stageDir;
+    contents.forEach((item, index) => {
+      const relName = sanitizeRelativePath(item.name || `file-${index + 1}.md`);
+      addPlanFile(plan, path.join(stageDir, relName), `${String(item.content || '').trim()}\n`, item.name, item.type);
+    });
+    return plan;
+  }
+
   if (installMode === 'split') {
     const usedDirs = new Set();
     contents.forEach((item, index) => {
@@ -1234,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,
@@ -1244,6 +1441,14 @@ function publicInstallPlan(plan) {
     manifestPath: plan.manifestPath,
     baseDir: plan.baseDir,
     risks: plan.risks,
+    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 => ({
       path: file.path,
       sourceName: file.sourceName,
@@ -1256,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) {
@@ -1265,14 +1471,19 @@ function formatRiskLine(file) {
 }
 
 async function confirmCodexInstallRisks(plan, opts = {}) {
-  if (opts.dryRun || opts.stage || !hasCodexInstallRisks(plan)) return;
+  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 || 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)
@@ -1301,6 +1512,32 @@ function stageCodexInstallPlan(plan) {
   return stagePath;
 }
 
+function executeStageOnlyCodexPlan(plan) {
+  const installedFiles = [];
+  const stageRoot = path.join(CODEX_TOKREPO_DIR, 'staged', plan.uuid);
+  if (!fs.existsSync(stageRoot)) fs.mkdirSync(stageRoot, { recursive: true, mode: 0o700 });
+
+  for (const file of plan.files) {
+    if (!ensureInside(stageRoot, file.path)) {
+      throw new Error(`Stage path escaped TokRepo staging directory: ${file.path}`);
+    }
+    const destDir = path.dirname(file.path);
+    if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file.path, file.content, { mode: 0o600 });
+    installedFiles.push({
+      path: file.path,
+      sourceName: file.sourceName,
+      sha256: sha256(file.content),
+      bytes: Buffer.byteLength(String(file.content || '')),
+      riskFlags: file.riskFlags,
+    });
+  }
+
+  const stagePath = path.join(stageRoot, 'install-plan.json');
+  fs.writeFileSync(stagePath, `${JSON.stringify(publicInstallPlan(plan), null, 2)}\n`, { mode: 0o600 });
+  return { dryRun: true, staged: true, stageOnly: true, stagePath, plan: publicInstallPlan(plan), installedFiles };
+}
+
 function readCodexManifest() {
   try {
     const parsed = JSON.parse(fs.readFileSync(CODEX_MANIFEST_FILE, 'utf8'));
@@ -1322,6 +1559,8 @@ function writeCodexManifestRecord(plan, installedFiles) {
     targetTool: 'codex',
     installMode: plan.installMode,
     installedAt,
+    contentHash: plan.contentHash || '',
+    agentMetadata: plan.agentMetadata || {},
     installedFiles: installedFiles.map(file => ({
       path: file.path,
       sourceName: file.sourceName,
@@ -1340,6 +1579,7 @@ function writeCodexManifestRecord(plan, installedFiles) {
 
 function executeCodexInstallPlan(plan, opts = {}) {
   if (opts.dryRun) return { dryRun: true, plan: publicInstallPlan(plan), installedFiles: [] };
+  if (plan.installMode === 'stage_only') return executeStageOnlyCodexPlan(plan);
   if (opts.stage) {
     const stagePath = stageCodexInstallPlan(plan);
     return { dryRun: true, staged: true, stagePath, plan: publicInstallPlan(plan), installedFiles: [] };
@@ -1411,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}...`);
@@ -1547,9 +1814,13 @@ async function installOneAsset(target, config, apiBase, opts) {
 
     if (!opts.json) {
       const plan = result.plan;
-      if (opts.stage) {
+      if (result.staged || opts.stage) {
         info(`Staged install plan: ${result.stagePath}`);
-        info(`No Codex skill files were written. Re-run with --approve-mcp or --yes to install.`);
+        if (result.stageOnly) {
+          info(`stage_only asset: files were written only under ${path.dirname(result.stagePath)}; no Codex skill was activated.`);
+        } else {
+          info(`No Codex skill files were written. Re-run with --approve-mcp or --yes to install.`);
+        }
       } else if (opts.dryRun) {
         info(`Dry run: ${plan.files.length} file(s) would be installed to ${CODEX_SKILLS_DIR}`);
         for (const file of plan.files) {
@@ -1764,6 +2035,12 @@ async function cmdList() {
 }
 
 async function cmdUpdate() {
+  const args = parseArgs(process.argv);
+  if (args.flags.target || args.flags.all || args.flags.force) {
+    await cmdSyncInstalled();
+    return;
+  }
+
   const uuid = process.argv[3];
   if (!uuid) error('Usage: tokrepo update <uuid> [file]');
 
@@ -1833,9 +2110,11 @@ function tagMatchesTypes(workflow, requestedTypes) {
   if (!requestedTypes || requestedTypes.length === 0) return true;
   const tags = (workflow.tags || []).flatMap(t => [t.slug, t.name]).filter(Boolean).map(t => String(t).toLowerCase());
   const assetType = getWorkflowAssetType(workflow);
+  const metadataKind = String(workflow.asset_kind || workflow.agent_metadata?.asset_kind || workflow.agentMetadata?.assetKind || '').toLowerCase();
   return requestedTypes.some(type => {
     const needle = String(type).trim().toLowerCase();
     if (!needle) return false;
+    if (metadataKind === needle || metadataKind === `${needle}s`) return true;
     if (assetType === needle || assetType === `${needle}s`) return true;
     return tags.some(tag => tag === needle || tag === `${needle}s` || tag.includes(needle));
   });
@@ -2116,17 +2395,17 @@ async function cmdSyncInstalled() {
 
   const manifest = readCodexManifest();
   const installed = (manifest.installs || []).filter(item => (item.targetTool || item.target_tool) === 'codex');
+  const dryRun = Boolean(args.flags.dryRun || args.flags.dry_run);
+  const stage = Boolean(args.flags.stage);
   if (installed.length === 0) {
-    if (json) outputJson({ targetTool: 'codex', count: 0, results: [] });
+    if (json) outputJson({ targetTool: 'codex', manifestPath: CODEX_MANIFEST_FILE, dryRun, stage, count: 0, results: [] });
     else info(`No Codex installs found in ${CODEX_MANIFEST_FILE}`);
     return;
   }
 
   const config = readConfig();
   const apiBase = config?.api || DEFAULT_API;
-  const dryRun = Boolean(args.flags.dryRun || args.flags.dry_run);
-  const stage = Boolean(args.flags.stage);
-  const force = Boolean(args.flags.update || args.flags.force);
+  const force = Boolean(args.flags.update || args.flags.force || args.flags.all);
   const results = [];
 
   for (let i = 0; i < installed.length; i++) {
@@ -2218,6 +2497,126 @@ async function cmdSyncInstalled() {
   }
 }
 
+async function cmdInstalled() {
+  const args = parseArgs(process.argv);
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') error(`installed currently supports --target codex only`);
+
+  const json = Boolean(args.flags.json);
+  if (!json) log(`\n${C.bold}tokrepo installed${C.reset}\n`);
+
+  const manifest = readCodexManifest();
+  const records = (manifest.installs || []).filter(item => (item.targetTool || item.target_tool) === 'codex');
+  const list = records.map(record => {
+    const files = (record.installedFiles || record.installed_files || []).map(file => {
+      const actualSha = file.path && fs.existsSync(file.path) ? currentFileSha(file.path) : '';
+      return {
+        path: file.path,
+        sourceName: file.sourceName || file.source_name,
+        sha256: file.sha256,
+        exists: Boolean(file.path && fs.existsSync(file.path)),
+        changed: Boolean(actualSha && file.sha256 && actualSha !== file.sha256),
+      };
+    });
+    return {
+      uuid: record.uuid,
+      title: record.title,
+      sourceUrl: record.sourceUrl || record.source_url,
+      targetTool: 'codex',
+      installMode: record.installMode || record.install_mode,
+      installedAt: record.installedAt || record.installed_at,
+      contentHash: record.contentHash || record.content_hash || '',
+      risks: record.risks || [],
+      files,
+      status: files.some(file => !file.exists) ? 'missing-files' : files.some(file => file.changed) ? 'local-changes' : 'installed',
+    };
+  });
+
+  if (json) {
+    outputJson({ targetTool: 'codex', manifestPath: CODEX_MANIFEST_FILE, count: list.length, list });
+    return;
+  }
+
+  if (list.length === 0) {
+    info(`No Codex installs found in ${CODEX_MANIFEST_FILE}`);
+    return;
+  }
+
+  for (const item of list) {
+    const color = item.status === 'installed' ? C.green : C.yellow;
+    log(`  ${color}${item.status}${C.reset}  ${C.bold}${item.title || item.uuid}${C.reset}`);
+    log(`  ${C.dim}${item.uuid} · ${item.installMode || 'unknown'} · ${item.files.length} file(s)${C.reset}\n`);
+  }
+}
+
+async function cmdOutdated() {
+  const args = parseArgs(process.argv);
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') error(`outdated currently supports --target codex only`);
+
+  const json = Boolean(args.flags.json);
+  if (!json) log(`\n${C.bold}tokrepo outdated${C.reset}\n`);
+
+  const manifest = readCodexManifest();
+  const installed = (manifest.installs || []).filter(item => (item.targetTool || item.target_tool) === 'codex');
+  if (installed.length === 0) {
+    if (json) outputJson({ targetTool: 'codex', count: 0, outdated: 0, list: [] });
+    else info(`No Codex installs found in ${CODEX_MANIFEST_FILE}`);
+    return;
+  }
+
+  const config = readConfig();
+  const apiBase = config?.api || DEFAULT_API;
+  const list = [];
+  let unchanged = 0;
+  let failed = 0;
+
+  for (const record of installed) {
+    try {
+      const { workflow, contents } = await fetchWorkflowForInstall(record.uuid, config, apiBase);
+      const plan = buildCodexInstallPlan(workflow, contents, { installMode: record.installMode || record.install_mode });
+      const diff = diffCodexPlanWithLocal(plan, record);
+      if (diff.needsUpdate) {
+        list.push({
+          uuid: record.uuid,
+          title: workflow.title,
+          status: 'outdated',
+          reasons: diff.reasons,
+          plan: publicInstallPlan(plan),
+        });
+      } else {
+        unchanged++;
+      }
+    } catch (e) {
+      failed++;
+      list.push({ uuid: record.uuid, title: record.title || record.uuid, status: 'failed', error: e.message });
+    }
+  }
+
+  if (json) {
+    outputJson({ targetTool: 'codex', manifestPath: CODEX_MANIFEST_FILE, count: installed.length, outdated: list.filter(i => i.status === 'outdated').length, unchanged, failed, list });
+    return;
+  }
+
+  const outdated = list.filter(item => item.status === 'outdated');
+  if (outdated.length === 0 && failed === 0) {
+    success(`All ${unchanged} Codex install(s) are up to date.`);
+    return;
+  }
+  for (const item of list) {
+    if (item.status === 'failed') {
+      warn(`${item.title}: ${item.error}`);
+    } else {
+      log(`  ${C.yellow}outdated${C.reset}  ${C.bold}${item.title}${C.reset}`);
+      for (const reason of item.reasons.slice(0, 3)) {
+        log(`    ${C.dim}${reason.type}: ${reason.path || ''}${C.reset}`);
+      }
+    }
+  }
+  log('');
+  info(`Run ${C.cyan}tokrepo update --target codex --all${C.reset} to update installed Codex assets.`);
+}
+
 async function cmdTags() {
   log(`\n${C.bold}tokrepo tags${C.reset}\n`);
 
@@ -2337,16 +2736,20 @@ ${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
+  ${C.cyan}installed${C.reset}            List installed Codex assets from manifest
+  ${C.cyan}outdated${C.reset}             Check installed Codex assets for updates
   ${C.cyan}sync-installed${C.reset}       Update installed Codex assets from manifest
 
 ${C.bold}PUBLISH${C.reset}
   ${C.cyan}push${C.reset} [files...]     Push files/directory (idempotent upsert)
   ${C.cyan}status${C.reset}              Compare local vs remote (like git status)
   ${C.cyan}init${C.reset}                Create .tokrepo.json project config
-  ${C.cyan}update${C.reset} <uuid> [f]   Update existing asset
+  ${C.cyan}update${C.reset} <uuid> [f]   Update existing remote asset
+  ${C.cyan}update${C.reset} --target codex --all   Update installed Codex assets
   ${C.cyan}delete${C.reset} <uuid>       Delete an asset
 
 ${C.bold}ACCOUNT${C.reset}
@@ -2362,6 +2765,9 @@ ${C.bold}PUSH OPTIONS${C.reset}
   ${C.cyan}--title${C.reset} "..."       Set title (auto-detected from README or dir name)
   ${C.cyan}--desc${C.reset} "..."        Set description
   ${C.cyan}--tag${C.reset} Skills        Add tag (repeatable)
+  ${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.bold}INSTALL BEHAVIOR${C.reset}
   Skills   → .claude/skills/    (if .claude/ exists)
@@ -2376,12 +2782,17 @@ ${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
   tokrepo clone @henuwangkai --target codex --keyword video
+  tokrepo installed --target codex --json
+  tokrepo outdated --target codex --json
+  tokrepo update --target codex --all
   tokrepo sync-installed --target codex --dry-run
   tokrepo push --private my-rules.md          # Save one file privately
+  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
   tokrepo push --public --title "My MCP" .    # Push dir publicly with title
@@ -2451,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}
@@ -2484,6 +2912,9 @@ ${C.bold}tokrepo sync-installed${C.reset}
 
 USAGE
   tokrepo sync-installed --target codex [--dry-run] [--stage] [--update] [--approve-mcp] [--json]
+  tokrepo installed --target codex [--json]
+  tokrepo outdated --target codex [--json]
+  tokrepo update --target codex --all [--stage] [--approve-mcp] [--json]
 
 BEHAVIOR
   Reads ~/.codex/tokrepo/install-manifest.json, fetches each TokRepo asset again,
@@ -2491,6 +2922,9 @@ BEHAVIOR
   changed or missing files. Use --update to force reinstall unchanged assets.
 
 EXAMPLES
+  tokrepo installed --target codex --json
+  tokrepo outdated --target codex --json
+  tokrepo update --target codex --all
   tokrepo sync-installed --target codex --dry-run --json
   tokrepo sync-installed --target codex --stage
   tokrepo sync-installed --target codex --update --approve-mcp
@@ -2504,6 +2938,8 @@ function showCommandHelp(command) {
       showSearchHelp(); break;
     case 'detail':
       showDetailHelp(); break;
+    case 'plan':
+      showPlanHelp(); break;
     case 'install':
     case 'i':
       showInstallHelp(); break;
@@ -2513,6 +2949,8 @@ function showCommandHelp(command) {
       showCloneHelp(); break;
     case 'sync-installed':
     case 'sync':
+    case 'installed':
+    case 'outdated':
       showSyncInstalledHelp(); break;
     default:
       showHelp(); break;
@@ -2537,11 +2975,14 @@ 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;
     case 'delete': await cmdDelete(); break;
     case 'clone': await cmdClone(); break;
+    case 'installed': await cmdInstalled(); break;
+    case 'outdated': await cmdOutdated(); break;
     case 'sync-installed': case 'sync': await cmdSyncInstalled(); break;
     case 'tags': await cmdTags(); break;
     case 'status': case 'diff': await cmdStatus(); break;
@@ -2555,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.4.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"