@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-token-interaction-command.mjs

@@ -0,0 +1,381 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readonlyLocalStatePresent } from './runtime-readonly-local-json-output-envelope.mjs';
+import {
+  buildTokenAuditSummaryModel,
+  buildTokenAdviceModel,
+  buildTokenCompactorCatalogModel,
+  buildTokenProfileModel,
+  buildTokenRewritePreviewModel,
+  compactLinesForDefinition,
+  estimateTokenCount,
+  normalizeTokenCommandName,
+  tokenCompactorDefinition,
+  tokenEconomyBoundaryAssertions,
+  tokenProfileNames,
+} from './runtime-token-economy-model.mjs';
+
+// Contract surface marker: tools/vibe-runtime-check/index.mjs validates this owner through runtime-entry-size-contracts.
+export function createRuntimeTokenInteractionCommands(deps) {
+  const {
+    jsonSchemaVersion,
+    tokenEconomyDirectory,
+    tokenCompactionFilePath,
+    tokenMetricsFilePath,
+    readJsonArtifact,
+    fileDigest,
+    digestObject,
+    persistStateArtifact,
+  } = deps;
+
+function tokenCompactionSnapshotPath(root) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(tokenEconomyDirectory(root), `${timestamp}.token-compaction.json`);
+}
+
+function tokenMetricsSnapshotPath(root) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(tokenEconomyDirectory(root), `${timestamp}.token-metrics.json`);
+}
+
+function tokenCompactorCatalogSnapshot() {
+  return buildTokenCompactorCatalogModel({ digestObject });
+}
+function tokenRootRelativeOutputFilePath(root, outputPath, label) {
+  const raw = String(outputPath || '').trim();
+  if (!raw) throw new Error(`${label} is required`);
+  if (raw.includes('\\')) throw new Error(`${label} must use forward slashes: ${raw}`);
+  if (!path.isAbsolute(raw) && raw.split('/').some((part) => part === '' || part === '.' || part === '..')) throw new Error(`${label} must not include traversal: ${raw}`);
+  const absolute = path.isAbsolute(raw) ? path.resolve(raw) : path.join(root, ...raw.split('/'));
+  const relative = path.relative(root, absolute).replace(/\\/g, '/');
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`${label} escapes root: ${raw}`);
+  if (relative.split('/').some((part) => part === '' || part === '.' || part === '..')) throw new Error(`${label} must not include traversal: ${relative}`);
+  const file = path.join(root, ...relative.split('/'));
+  if (!fs.existsSync(file)) throw new Error(`token output file not found: ${relative}`);
+  return { file, relative };
+}
+
+function tokenCompactionPayload(root, { commandName, outputFile, createdAt = new Date().toISOString() } = {}) {
+  const definition = tokenCompactorDefinition(commandName);
+  const output = tokenRootRelativeOutputFilePath(root, outputFile, 'token.output_file');
+  const rawText = fs.readFileSync(output.file, 'utf8');
+  const compactedText = compactLinesForDefinition(definition, rawText).filter(Boolean).join('\n');
+  const inputTokens = estimateTokenCount(rawText);
+  const outputTokens = estimateTokenCount(compactedText);
+  const payload = {
+    version: 1,
+    stage: 'Stage 63',
+    artifact_kind: 'token-compaction',
+    optional: true,
+    sidecar_only: true,
+    default_enabled: false,
+    release_chain_required: false,
+    created_at: createdAt,
+    command_name: String(commandName || '').trim(),
+    normalized_command: normalizeTokenCommandName(commandName),
+    command_family: definition.family,
+    compactor_id: definition.id,
+    compactor_version: 1,
+    source_file: output.relative,
+    source_digest: fileDigest(output.file),
+    full_output_digest: fileDigest(output.file),
+    input_bytes: Buffer.byteLength(rawText, 'utf8'),
+    input_lines: rawText.length === 0 ? 0 : rawText.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n').length,
+    compacted_text: compactedText,
+    compacted_digest: digestObject({ compactor_id: definition.id, compacted_text: compactedText }),
+    dropped_categories: [...definition.dropped_categories].sort(),
+    metrics: {
+      estimated_input_tokens: inputTokens,
+      estimated_output_tokens: outputTokens,
+      estimated_tokens_saved: Math.max(0, inputTokens - outputTokens),
+      savings_ratio: inputTokens === 0 ? 0 : Number((Math.max(0, inputTokens - outputTokens) / inputTokens).toFixed(3)),
+    },
+    deterministic: true,
+    pure_function: true,
+    original_output_retained_by_digest: true,
+    boundary_assertions: tokenEconomyBoundaryAssertions(),
+    allowed_followup: ['manual_review', 'token_metrics_preview'],
+    local_only: true,
+  };
+  return { ...payload, token_compaction_digest: digestObject(payload) };
+}
+
+function tokenCompactionEnvelope(root, { commandName, outputFile, persist = false } = {}) {
+  const compaction = tokenCompactionPayload(root, { commandName, outputFile });
+  return {
+    mode: 'token-compaction',
+    ok: true,
+    state_present: readonlyLocalStatePresent(root),
+    token_compaction: { ...compaction, writes: Boolean(persist) },
+    safety: {
+      stage: 'Stage 63',
+      writes: Boolean(persist),
+      token_compaction_artifact: Boolean(persist),
+      optional: true,
+      sidecar_only: true,
+      default_enabled: false,
+      release_chain_required: false,
+      ...tokenEconomyBoundaryAssertions(),
+    },
+    quality: [],
+    action: persist
+      ? 'token compaction sidecar was written from a local output file. No shell interception, command execution, output mutation, hidden original output, external network, model, platform API, git, worktree, subagent, MCP, or business source mutation occurred.'
+      : 'token compaction was previewed read-only from a local output file. No state directory, shell interception, command execution, output mutation, hidden original output, external network, model, platform API, git, worktree, subagent, MCP, or business source mutation occurred.',
+  };
+}
+
+function validateTokenCompactionArtifact(root, artifact) {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'tokens') failures.push('command must be tokens');
+  if (artifact.mode !== 'token-compaction') failures.push('mode must be token-compaction');
+  const compaction = artifact.token_compaction || {};
+  if (compaction.stage !== 'Stage 63') failures.push('token_compaction.stage must be Stage 63');
+  if (compaction.artifact_kind !== 'token-compaction') failures.push('token_compaction.artifact_kind must be token-compaction');
+  if (compaction.optional !== true) failures.push('token_compaction.optional must be true');
+  if (compaction.sidecar_only !== true) failures.push('token_compaction.sidecar_only must be true');
+  if (compaction.default_enabled !== false) failures.push('token_compaction.default_enabled must be false');
+  if (compaction.release_chain_required !== false) failures.push('token_compaction.release_chain_required must be false');
+  if (compaction.deterministic !== true) failures.push('token_compaction.deterministic must be true');
+  if (compaction.pure_function !== true) failures.push('token_compaction.pure_function must be true');
+  if (compaction.original_output_retained_by_digest !== true) failures.push('token_compaction.original_output_retained_by_digest must be true');
+  try {
+    const expected = tokenCompactionPayload(root, { commandName: compaction.command_name, outputFile: compaction.source_file, createdAt: compaction.created_at });
+    for (const key of ['normalized_command', 'command_family', 'compactor_id', 'source_digest', 'full_output_digest', 'input_bytes', 'input_lines', 'compacted_text', 'compacted_digest', 'token_compaction_digest']) {
+      if (compaction[key] !== expected[key]) failures.push(`token_compaction.${key} drift`);
+    }
+    if (digestObject(compaction.metrics || {}) !== digestObject(expected.metrics)) failures.push('token_compaction.metrics drift');
+    if (digestObject(compaction.dropped_categories || []) !== digestObject(expected.dropped_categories)) failures.push('token_compaction.dropped_categories drift');
+  } catch (error) {
+    failures.push(error.message);
+  }
+  for (const [key, expected] of Object.entries(tokenEconomyBoundaryAssertions())) {
+    if (compaction.boundary_assertions?.[key] !== expected) failures.push(`token_compaction.boundary_assertions.${key} must be false`);
+    if (artifact.safety?.[key] !== expected) failures.push(`safety.${key} must be false`);
+  }
+  if (artifact.safety?.token_compaction_artifact !== true) failures.push('safety.token_compaction_artifact must be true');
+  const digestPayload = { ...compaction };
+  delete digestPayload.writes;
+  delete digestPayload.token_compaction_digest;
+  if (compaction.token_compaction_digest !== digestObject(digestPayload)) failures.push('token compaction digest mismatch');
+  return { ok: failures.length === 0, failures };
+}
+
+function writeTokenCompaction(root, envelope) {
+  const file = tokenCompactionSnapshotPath(root);
+  const payload = { schema_version: jsonSchemaVersion, command: 'tokens', ...envelope, safety: { ...envelope.safety, token_compaction_artifact: true } };
+  const verification = validateTokenCompactionArtifact(root, payload);
+  if (!verification.ok) throw new Error(`token compaction verification failed: ${verification.failures.join('; ')}`);
+  return persistStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function tokenProfileSnapshot(profileName) {
+  return buildTokenProfileModel(profileName, { digestObject });
+}
+
+function tokenProfileEnvelope(profileName) {
+  const profile = tokenProfileSnapshot(profileName);
+  return {
+    mode: 'token-profile',
+    ok: true,
+    profile,
+    available_profiles: tokenProfileNames(),
+    quality: [],
+    action: 'read-only token profile was selected from builtin deterministic data. No state directory, shell interception, command execution, output mutation, external network, model, platform API, git, worktree, subagent, MCP, or business source mutation occurred.',
+  };
+}
+
+function tokenMetricsPayload(root, { compactionFiles, createdAt = new Date().toISOString() } = {}) {
+  const files = [...new Set((compactionFiles || []).map((file) => String(file || '').trim()).filter(Boolean))];
+  if (files.length === 0) throw new Error('tokens --metrics requires --from-compactions <token-compaction-file...>');
+  const sourceCompactions = files.map((tokenFile) => {
+    const file = tokenCompactionFilePath(root, tokenFile);
+    const artifact = readJsonArtifact(file, 'Token compaction');
+    const verification = validateTokenCompactionArtifact(root, artifact);
+    if (!verification.ok) throw new Error(`token compaction verification failed for ${path.basename(file)}: ${verification.failures.join('; ')}`);
+    const compaction = artifact.token_compaction || {};
+    return {
+      file: path.basename(file),
+      file_digest: fileDigest(file),
+      token_compaction_digest: compaction.token_compaction_digest || '',
+      command_name: compaction.command_name || '',
+      command_family: compaction.command_family || '',
+      compactor_id: compaction.compactor_id || '',
+      estimated_input_tokens: compaction.metrics?.estimated_input_tokens || 0,
+      estimated_output_tokens: compaction.metrics?.estimated_output_tokens || 0,
+      estimated_tokens_saved: compaction.metrics?.estimated_tokens_saved || 0,
+      savings_ratio: compaction.metrics?.savings_ratio || 0,
+    };
+  }).sort((left, right) => left.file.localeCompare(right.file));
+  const totalInput = sourceCompactions.reduce((sum, item) => sum + item.estimated_input_tokens, 0);
+  const totalOutput = sourceCompactions.reduce((sum, item) => sum + item.estimated_output_tokens, 0);
+  const totalSaved = sourceCompactions.reduce((sum, item) => sum + item.estimated_tokens_saved, 0);
+  const families = [...new Set(sourceCompactions.map((item) => item.command_family).filter(Boolean))].sort().map((family) => ({
+    family,
+    count: sourceCompactions.filter((item) => item.command_family === family).length,
+  }));
+  const payload = {
+    version: 1,
+    stage: 'Stage 64',
+    artifact_kind: 'token-metrics',
+    optional: true,
+    sidecar_only: true,
+    default_enabled: false,
+    release_chain_required: false,
+    created_at: createdAt,
+    source_compactions: sourceCompactions,
+    totals: {
+      compaction_count: sourceCompactions.length,
+      estimated_input_tokens: totalInput,
+      estimated_output_tokens: totalOutput,
+      estimated_tokens_saved: totalSaved,
+      savings_ratio: totalInput === 0 ? 0 : Number((totalSaved / totalInput).toFixed(3)),
+      command_family_count: families.length,
+    },
+    command_families: families,
+    deterministic: true,
+    pure_function: true,
+    original_output_retained_by_digest: true,
+    boundary_assertions: tokenEconomyBoundaryAssertions(),
+    allowed_followup: ['manual_review', 'rewrite_preview_only'],
+    local_only: true,
+  };
+  return { ...payload, token_metrics_digest: digestObject(payload) };
+}
+
+function tokenMetricsEnvelope(root, { compactionFiles, persist = false } = {}) {
+  const metrics = tokenMetricsPayload(root, { compactionFiles });
+  return {
+    mode: 'token-metrics',
+    ok: true,
+    state_present: readonlyLocalStatePresent(root),
+    token_metrics: { ...metrics, writes: Boolean(persist) },
+    safety: {
+      stage: 'Stage 64',
+      writes: Boolean(persist),
+      token_metrics_artifact: Boolean(persist),
+      optional: true,
+      sidecar_only: true,
+      default_enabled: false,
+      release_chain_required: false,
+      ...tokenEconomyBoundaryAssertions(),
+    },
+    quality: [],
+    action: persist
+      ? 'token metrics sidecar was written from verified local token compaction sidecars. No shell interception, command execution, output mutation, hidden original output, external network, model, platform API, git, worktree, subagent, MCP, or business source mutation occurred.'
+      : 'token metrics were previewed read-only from verified local token compaction sidecars. No state directory, shell interception, command execution, output mutation, hidden original output, external network, model, platform API, git, worktree, subagent, MCP, or business source mutation occurred.',
+  };
+}
+
+function validateTokenMetricsArtifact(root, artifact) {
+  const failures = [];
+  if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+  if (artifact.command !== 'tokens') failures.push('command must be tokens');
+  if (artifact.mode !== 'token-metrics') failures.push('mode must be token-metrics');
+  const metrics = artifact.token_metrics || {};
+  if (metrics.stage !== 'Stage 64') failures.push('token_metrics.stage must be Stage 64');
+  if (metrics.artifact_kind !== 'token-metrics') failures.push('token_metrics.artifact_kind must be token-metrics');
+  if (metrics.optional !== true) failures.push('token_metrics.optional must be true');
+  if (metrics.sidecar_only !== true) failures.push('token_metrics.sidecar_only must be true');
+  if (metrics.default_enabled !== false) failures.push('token_metrics.default_enabled must be false');
+  if (metrics.release_chain_required !== false) failures.push('token_metrics.release_chain_required must be false');
+  if (metrics.deterministic !== true) failures.push('token_metrics.deterministic must be true');
+  if (metrics.pure_function !== true) failures.push('token_metrics.pure_function must be true');
+  if (metrics.original_output_retained_by_digest !== true) failures.push('token_metrics.original_output_retained_by_digest must be true');
+  try {
+    const expected = tokenMetricsPayload(root, { compactionFiles: (metrics.source_compactions || []).map((item) => item.file), createdAt: metrics.created_at });
+    if (digestObject(metrics.source_compactions || []) !== digestObject(expected.source_compactions)) failures.push('token_metrics.source_compactions drift');
+    if (digestObject(metrics.totals || {}) !== digestObject(expected.totals)) failures.push('token_metrics.totals drift');
+    if (digestObject(metrics.command_families || []) !== digestObject(expected.command_families)) failures.push('token_metrics.command_families drift');
+    if (metrics.token_metrics_digest !== expected.token_metrics_digest) failures.push('token_metrics.token_metrics_digest drift');
+  } catch (error) {
+    failures.push(error.message);
+  }
+  for (const [key, expected] of Object.entries(tokenEconomyBoundaryAssertions())) {
+    if (metrics.boundary_assertions?.[key] !== expected) failures.push(`token_metrics.boundary_assertions.${key} must be false`);
+    if (artifact.safety?.[key] !== expected) failures.push(`safety.${key} must be false`);
+  }
+  if (artifact.safety?.token_metrics_artifact !== true) failures.push('safety.token_metrics_artifact must be true');
+  const digestPayload = { ...metrics };
+  delete digestPayload.writes;
+  delete digestPayload.token_metrics_digest;
+  if (metrics.token_metrics_digest !== digestObject(digestPayload)) failures.push('token metrics digest mismatch');
+  return { ok: failures.length === 0, failures };
+}
+
+function writeTokenMetrics(root, envelope) {
+  const file = tokenMetricsSnapshotPath(root);
+  const payload = { schema_version: jsonSchemaVersion, command: 'tokens', ...envelope, safety: { ...envelope.safety, token_metrics_artifact: true } };
+  const verification = validateTokenMetricsArtifact(root, payload);
+  if (!verification.ok) throw new Error(`token metrics verification failed: ${verification.failures.join('; ')}`);
+  return persistStateArtifact(path.dirname(file), path.basename(file), payload);
+}
+
+function tokenAdviceEnvelope(root, { intent = '', commandName = '' } = {}) {
+  return buildTokenAdviceModel({
+    intent,
+    commandName,
+    statePresent: readonlyLocalStatePresent(root),
+    digestObject,
+  });
+}
+
+function tokenRewritePreview(commandName) {
+  return buildTokenRewritePreviewModel(commandName, { digestObject });
+}
+
+function tokenRewritePreviewEnvelope(commandName) {
+  return {
+    mode: 'token-rewrite-preview',
+    ok: true,
+    rewrite_preview: tokenRewritePreview(commandName),
+    quality: [],
+    action: 'read-only token rewrite preview suggested a safer compact command form without executing, intercepting, or mutating the user command.',
+  };
+}
+
+function tokenAuditEnvelope(root, mode, tokenFile = '') {
+  if (mode === 'catalog') {
+    return { mode: 'token-compactor-catalog', ok: true, catalog: tokenCompactorCatalogSnapshot(), quality: [], action: 'read-only token compactor catalog listed deterministic builtin compactors. No state directory was created.' };
+  }
+  if (String(tokenFile || '').endsWith('.token-metrics.json')) {
+    const file = tokenMetricsFilePath(root, tokenFile);
+    const artifact = readJsonArtifact(file, 'Token metrics');
+    const verification = validateTokenMetricsArtifact(root, artifact);
+    if (mode === 'verify' && !verification.ok) throw new Error(`token metrics verification failed: ${verification.failures.join('; ')}`);
+    return {
+      mode: 'token-metrics-verify',
+      ok: verification.ok,
+      summary: buildTokenAuditSummaryModel('token-metrics', path.basename(file), artifact),
+      verification,
+      artifact,
+      quality: verification.failures,
+      action: 'read-only token metrics audit verified one local sidecar. No shell interception, command execution, output mutation, external network, model, platform API, git, worktree, subagent, MCP, or business source mutation occurred.',
+    };
+  }
+  const file = tokenCompactionFilePath(root, tokenFile);
+  const artifact = readJsonArtifact(file, 'Token compaction');
+  const verification = validateTokenCompactionArtifact(root, artifact);
+  if (mode === 'verify' && !verification.ok) throw new Error(`token compaction verification failed: ${verification.failures.join('; ')}`);
+  return {
+    mode: 'token-compaction-verify',
+    ok: verification.ok,
+    summary: buildTokenAuditSummaryModel('token-compaction', path.basename(file), artifact),
+    verification,
+    artifact,
+    quality: verification.failures,
+    action: 'read-only token compaction audit verified one local sidecar. No shell interception, command execution, output mutation, external network, model, platform API, git, worktree, subagent, MCP, or business source mutation occurred.',
+  };
+}
+
+  return {
+    tokenAdviceEnvelope,
+    tokenAuditEnvelope,
+    tokenCompactionEnvelope,
+    tokenMetricsEnvelope,
+    tokenProfileEnvelope,
+    tokenRewritePreviewEnvelope,
+    writeTokenCompaction,
+    writeTokenMetrics,
+  };
+}