clean-room-skill 0.1.12 → 0.1.13

package/lib/install-status.cjs

@@ -0,0 +1,292 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const { assertManagedPath, fileHash } = require('./fs-utils.cjs');
+const {
+  configPathForRuntime,
+  hasManagedHookEntries,
+  hasManagedOpenCodePlugin,
+  pluginPathForRuntime,
+} = require('./hooks.cjs');
+const { buildDesiredFiles, packageVersion } = require('./install-artifacts.cjs');
+const {
+  manifestHash,
+  planInstall,
+  readManifest,
+} = require('./install-plan.cjs');
+const {
+  CLAUDE_PLUGIN_ID,
+  CLAUDE_PLUGIN_MARKETPLACE_NAME,
+} = require('./install-claude-plugin.cjs');
+const { isUpdateTargetStatus } = require('./install-runtime-selection.cjs');
+const {
+  RUNTIMES,
+  resolveRuntimeLayout,
+} = require('./runtime-layout.cjs');
+
+function runtimeInstallStatuses(scope, configDir) {
+  return RUNTIMES.map((runtime) => runtimeInstallStatus(runtime, scope, configDir));
+}
+
+function runtimeInstallStatus(runtime, scope, configDir) {
+  const layout = resolveRuntimeLayout(runtime, scope, { configDir });
+  const status = {
+    runtime,
+    targetRoot: layout.targetRoot,
+    state: 'not-installed',
+    detail: 'not installed',
+  };
+  try {
+    const manifest = readManifest(layout.targetRoot);
+    if (manifest) {
+      const phase = manifest.phase ? `phase ${manifest.phase}` : 'manifest present';
+      const hooksMode = manifest.hooks_mode ? `, hooks ${manifest.hooks_mode}` : '';
+      return {
+        ...status,
+        state: 'installed',
+        detail: `${phase}${hooksMode}`,
+      };
+    }
+  } catch (err) {
+    return {
+      ...status,
+      state: 'error',
+      detail: err.message,
+    };
+  }
+
+  if (!layout.supportsHookRegistration) {
+    return status;
+  }
+  const hookState = detectHookRegistration(layout, configPathForRuntime(runtime, layout.targetRoot));
+  if (hookState === 'present') {
+    return {
+      ...status,
+      state: 'hooks-only',
+      detail: 'managed hooks without install manifest',
+    };
+  }
+  if (hookState.startsWith('error: ')) {
+    return {
+      ...status,
+      state: 'error',
+      detail: hookState.slice('error: '.length),
+    };
+  }
+  return status;
+}
+
+function collectRuntimeStatus(runtime, scope, configDir) {
+  const layout = resolveRuntimeLayout(runtime, scope, { configDir });
+  const base = {
+    runtime,
+    scope,
+    targetRoot: layout.targetRoot,
+    supportsHookRegistration: layout.supportsHookRegistration,
+    state: 'not-installed',
+    detail: 'not installed',
+    installedVersion: null,
+    currentVersion: packageVersion(),
+    hooksMode: null,
+    phase: null,
+    files: 0,
+    missing: 0,
+    modified: 0,
+    stale: 0,
+    unknownConflicts: 0,
+    hookRegistration: layout.supportsHookRegistration ? 'none' : 'unsupported',
+    updateAvailable: false,
+    claudePlugin: null,
+    issues: [],
+  };
+
+  let manifest;
+  try {
+    manifest = readManifest(layout.targetRoot);
+  } catch (err) {
+    return {
+      ...base,
+      state: 'error',
+      detail: err.message,
+      issues: [err.message],
+    };
+  }
+
+  const configPath = configPathForRuntime(runtime, layout.targetRoot);
+  const hookState = detectHookRegistration(layout, configPath);
+  if (!manifest) {
+    if (hookState === 'present') {
+      return {
+        ...base,
+        state: 'hooks-only',
+        detail: 'managed hooks without install manifest',
+        hookRegistration: 'present',
+        issues: ['managed hooks exist without an install manifest'],
+      };
+    }
+    return base;
+  }
+
+  const hooksMode = manifest.hooks_mode || 'safe';
+  let desired;
+  let plan;
+  let fileStats;
+  try {
+    desired = buildDesiredFiles(layout, hooksMode);
+    plan = planInstall(layout.targetRoot, desired, manifest);
+    fileStats = manifestFileStats(layout.targetRoot, manifest);
+  } catch (err) {
+    return {
+      ...base,
+      state: 'error',
+      detail: err.message,
+      installedVersion: manifest.version || null,
+      hooksMode,
+      phase: manifest.phase || null,
+      hookRegistration: hookState,
+      issues: [err.message],
+    };
+  }
+  const issues = [];
+  if (manifest.phase && manifest.phase !== 'complete') {
+    issues.push(`manifest phase is ${manifest.phase}`);
+  }
+  if (fileStats.missing > 0) {
+    issues.push(`${fileStats.missing} managed file(s) missing`);
+  }
+  if (fileStats.modified > 0) {
+    issues.push(`${fileStats.modified} managed file(s) locally modified`);
+  }
+  if (plan.removals.length > 0) {
+    issues.push(`${plan.removals.length} stale managed file(s)`);
+  }
+  if (plan.unknownConflicts.length > 0) {
+    issues.push(`${plan.unknownConflicts.length} unmanaged package-path conflict(s)`);
+  }
+  if (layout.supportsHookRegistration && hooksMode !== 'copy-only' && hookState !== 'present') {
+    issues.push('managed hook registration missing');
+  }
+
+  const updateAvailable = manifest.version !== packageVersion() ||
+    plan.removals.length > 0 ||
+    plan.unknownConflicts.length > 0 ||
+    fileStats.missing > 0;
+
+  return {
+    ...base,
+    state: updateAvailable ? 'update-available' : 'installed',
+    detail: updateAvailable ? 'update available' : 'installed',
+    installedVersion: manifest.version || null,
+    hooksMode,
+    phase: manifest.phase || null,
+    files: Object.keys(manifest.files || {}).length,
+    missing: fileStats.missing,
+    modified: fileStats.modified,
+    stale: plan.removals.length,
+    unknownConflicts: plan.unknownConflicts.length,
+    hookRegistration: hookState,
+    updateAvailable,
+    claudePlugin: manifest.claude_plugin || null,
+    issues,
+  };
+}
+
+function detectHookRegistration(layout, configPath) {
+  if (!layout.supportsHookRegistration) {
+    return 'unsupported';
+  }
+  if (layout.hookRegistration === 'local-plugin') {
+    try {
+      return hasManagedOpenCodePlugin(pluginPathForRuntime(layout.runtime, layout.targetRoot)) ? 'present' : 'missing';
+    } catch (err) {
+      return `error: ${err.message}`;
+    }
+  }
+  if (layout.hookRegistration !== 'json-config' || !configPath) {
+    return 'unsupported';
+  }
+  try {
+    return hasManagedHookEntries(configPath) ? 'present' : 'missing';
+  } catch (err) {
+    return `error: ${err.message}`;
+  }
+}
+
+function manifestFileStats(targetRoot, manifest) {
+  let missing = 0;
+  let modified = 0;
+  for (const relPath of Object.keys(manifest?.files || {})) {
+    const fullPath = assertManagedPath(targetRoot, relPath);
+    if (!fs.existsSync(fullPath)) {
+      missing += 1;
+      continue;
+    }
+    const expected = manifestHash(manifest, relPath);
+    if (expected && fileHash(fullPath) !== expected) {
+      modified += 1;
+    }
+  }
+  return { missing, modified };
+}
+
+function printStatusReport(statuses) {
+  console.log(`clean-room-skill package version: ${packageVersion()}`);
+  for (const status of statuses) {
+    console.log(`${status.runtime} (${status.scope}) ${status.state}`);
+    console.log(`  target: ${status.targetRoot}`);
+    if (status.installedVersion) {
+      console.log(`  version: ${status.installedVersion}${status.installedVersion !== status.currentVersion ? ` -> ${status.currentVersion}` : ''}`);
+      console.log(`  phase: ${status.phase || 'unknown'}`);
+      console.log(`  hooks: ${status.hooksMode || 'unknown'}; registration ${status.hookRegistration}`);
+      console.log(`  files: ${status.files}; missing ${status.missing}; modified ${status.modified}; stale ${status.stale}; conflicts ${status.unknownConflicts}`);
+      if (status.claudePlugin) {
+        console.log(`  plugin: ${status.claudePlugin.plugin_id || CLAUDE_PLUGIN_ID}; marketplace ${status.claudePlugin.marketplace_name || CLAUDE_PLUGIN_MARKETPLACE_NAME}`);
+      }
+    } else if (status.hookRegistration === 'present') {
+      console.log('  hooks: managed hook registration present without install manifest');
+    }
+    if (status.issues.length > 0) {
+      console.log(`  issues: ${status.issues.join('; ')}`);
+    }
+  }
+}
+
+function selectedStatusRuntimes(options) {
+  return options.runtimes.length > 0 ? options.runtimes : [...RUNTIMES];
+}
+
+function selectedUpdateRuntimes(options) {
+  if (options.runtimes.length > 0) {
+    return options.runtimes;
+  }
+  return runtimeInstallStatuses(options.scope, options.configDir)
+    .filter((status) => isUpdateTargetStatus(status))
+    .map((status) => status.runtime);
+}
+
+function runStatus(options) {
+  const runtimes = selectedStatusRuntimes(options);
+  const statuses = runtimes.map((runtime) =>
+    collectRuntimeStatus(runtime, options.scope, options.configDir)
+  );
+  printStatusReport(statuses);
+  return statuses;
+}
+
+function resolveTargetRoot(runtime, scope, configDir) {
+  return resolveRuntimeLayout(runtime, scope, { configDir }).targetRoot;
+}
+
+module.exports = {
+  collectRuntimeStatus,
+  detectHookRegistration,
+  manifestFileStats,
+  printStatusReport,
+  resolveTargetRoot,
+  runStatus,
+  runtimeInstallStatus,
+  runtimeInstallStatuses,
+  selectedStatusRuntimes,
+  selectedUpdateRuntimes,
+};

package/lib/install-tui.cjs

@@ -0,0 +1,359 @@
+'use strict';
+
+const { operationForOptions } = require('./install-options.cjs');
+const {
+  defaultRuntimeSelections,
+  detectedRuntimeSelections,
+  displayPath,
+  emptyRuntimeSelectionMessage,
+  isSelectableRuntimeStatus,
+  selectableRuntimeSelections,
+  unavailableRuntimeSelectionMessage,
+} = require('./install-runtime-selection.cjs');
+const { runtimeInstallStatuses } = require('./install-status.cjs');
+const { RUNTIMES } = require('./runtime-layout.cjs');
+
+async function resolveInteractiveOptions(options) {
+  if (options.runtimes.length > 0 && options.scope) {
+    return options;
+  }
+  if (!process.stdin.isTTY || options.yes) {
+    throw new Error('specify runtime and scope flags when running non-interactively');
+  }
+  return runInstallerTui(options);
+}
+
+async function runInstallerTui(options) {
+  const React = await import('react');
+  const ink = await import('ink');
+  const h = React.createElement;
+
+  return new Promise((resolve, reject) => {
+    let result = null;
+    let error = null;
+
+    function complete(nextOptions) {
+      result = nextOptions;
+    }
+
+    function abort(err) {
+      error = err;
+    }
+
+    function App() {
+      return h(InstallerTui, {
+        React,
+        ink,
+        h,
+        initialOptions: options,
+        onComplete: complete,
+        onAbort: abort,
+      });
+    }
+
+    const instance = ink.render(h(App), {
+      stdin: process.stdin,
+      stdout: process.stdout,
+      stderr: process.stderr,
+      exitOnCtrlC: false,
+    });
+
+    instance.waitUntilExit().then(() => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(result || options);
+    }, reject);
+  });
+}
+
+function InstallerTui({ React, ink, h, initialOptions, onComplete, onAbort }) {
+  const { Box, Text, useApp, useInput } = ink;
+  const { useMemo, useState } = React;
+  const { exit } = useApp();
+  const initialFlags = useMemo(() => ({
+    actionResolved: !!initialOptions.operation ||
+      !(initialOptions.runtimes.length === 0 && !initialOptions.uninstall),
+    promptedRuntimes: false,
+    uninstallConfirmed: true,
+  }), [initialOptions]);
+  const [draft, setDraft] = useState(() => ({
+    ...initialOptions,
+    runtimes: [...initialOptions.runtimes],
+  }));
+  const [flags, setFlags] = useState(initialFlags);
+  const [stage, setStage] = useState(() => nextTuiStage(initialOptions, initialFlags));
+
+  function fail(message) {
+    onAbort(new Error(message));
+    exit();
+  }
+
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') {
+      fail('aborted by user');
+    }
+  });
+
+  function advance(nextDraft, nextFlags = {}) {
+    const mergedFlags = { ...flags, ...nextFlags };
+    const nextStage = nextTuiStage(nextDraft, mergedFlags);
+    setDraft(nextDraft);
+    setFlags(mergedFlags);
+    if (nextStage === 'complete') {
+      onComplete(nextDraft);
+      exit();
+      return;
+    }
+    setStage(nextStage);
+  }
+
+  const action = operationForOptions(draft);
+
+  return h(Box, { flexDirection: 'column', gap: 1 },
+    h(Box, { flexDirection: 'column' },
+      h(Text, { bold: true }, 'clean-room-skill installer'),
+      h(Text, { dimColor: true }, 'Use arrows or j/k to move. Enter selects. Ctrl+C cancels.')
+    ),
+    stage === 'action' && h(SingleChoice, {
+      React,
+      Box,
+      Text,
+      useInput,
+      h,
+      title: 'Action',
+      initialIndex: defaultActionIndex(draft),
+      items: [
+        { label: 'Update', value: 'update', detail: 'refresh installed runtimes without onboarding' },
+        { label: 'Install', value: 'install', detail: 'add or repair runtime files' },
+        { label: 'Uninstall', value: 'uninstall', detail: 'remove managed files and generated hooks' },
+        { label: 'Status', value: 'status', detail: 'inspect runtime installs without changing files' },
+      ],
+      onSubmit: (item) => advance({
+        ...draft,
+        operation: item.value,
+        uninstall: item.value === 'uninstall',
+      }, {
+        actionResolved: true,
+        uninstallConfirmed: item.value !== 'uninstall',
+      }),
+    }),
+    stage === 'scope' && h(SingleChoice, {
+      React,
+      Box,
+      Text,
+      useInput,
+      h,
+      title: 'Scope',
+      items: [
+        { label: 'Global', value: 'global', detail: 'runtime user config' },
+        { label: 'Local', value: 'local', detail: 'current project config' },
+      ],
+      onSubmit: (item) => advance({ ...draft, scope: item.value }),
+    }),
+    stage === 'runtimes' && h(RuntimeMultiSelect, {
+      React,
+      Box,
+      Text,
+      useInput,
+      h,
+      action,
+      statuses: runtimeInstallStatuses(draft.scope, draft.configDir),
+      onSubmit: (runtimes) => advance({ ...draft, runtimes }, {
+        promptedRuntimes: true,
+        uninstallConfirmed: operationForOptions(draft) !== 'uninstall',
+      }),
+    }),
+    stage === 'confirm-uninstall' && h(ConfirmUninstall, {
+      React,
+      Box,
+      Text,
+      useInput,
+      h,
+      runtimes: draft.runtimes,
+      onSubmit: () => advance(draft, { uninstallConfirmed: true }),
+    }),
+    stage === 'hooks' && h(SingleChoice, {
+      React,
+      Box,
+      Text,
+      useInput,
+      h,
+      title: 'Hook mode',
+      items: [
+        { label: 'Safe', value: 'safe', detail: 'enforces during clean-room role sessions' },
+        { label: 'Copy-only', value: 'copy-only', detail: 'copy scripts without host hook registration' },
+        { label: 'Strict', value: 'strict', detail: 'fail closed in dedicated Codex, Claude, or OpenCode homes' },
+      ],
+      onSubmit: (item) => advance({ ...draft, hookMode: item.value, hookModeSpecified: true }),
+    })
+  );
+}
+
+function defaultActionIndex(options) {
+  if (operationForOptions(options) === 'status') return 3;
+  if (operationForOptions(options) === 'uninstall') return 2;
+  if (runtimeInstallStatuses(options.scope || 'global', options.configDir).some((status) => status.state === 'installed')) {
+    return 0;
+  }
+  return 1;
+}
+
+function nextTuiStage(options, flags) {
+  if (!options.scope) {
+    return 'scope';
+  }
+  if (!flags.actionResolved) {
+    return 'action';
+  }
+  if (operationForOptions(options) === 'status') {
+    return 'complete';
+  }
+  if (options.runtimes.length === 0) {
+    return 'runtimes';
+  }
+  if (operationForOptions(options) === 'uninstall' && flags.promptedRuntimes && !flags.uninstallConfirmed) {
+    return 'confirm-uninstall';
+  }
+  if (operationForOptions(options) === 'install' && !options.hookModeSpecified) {
+    return 'hooks';
+  }
+  return 'complete';
+}
+
+function SingleChoice({ React, Box, Text, useInput, h, title, items, initialIndex = 0, onSubmit }) {
+  const [index, setIndex] = React.useState(initialIndex);
+  useInput((input, key) => {
+    if (key.upArrow || input === 'k') {
+      setIndex((current) => Math.max(0, current - 1));
+    } else if (key.downArrow || input === 'j') {
+      setIndex((current) => Math.min(items.length - 1, current + 1));
+    } else if (key.home) {
+      setIndex(0);
+    } else if (key.end) {
+      setIndex(items.length - 1);
+    } else if (key.return || /[\r\n]/.test(input)) {
+      onSubmit(items[index]);
+    }
+  });
+
+  return h(Box, { flexDirection: 'column' },
+    h(Text, { bold: true }, title),
+    ...items.map((item, itemIndex) => h(Text, {
+      key: item.value,
+      color: itemIndex === index ? 'cyan' : undefined,
+    }, `${itemIndex === index ? '>' : ' '} ${item.label.padEnd(10)} ${item.detail}`))
+  );
+}
+
+function RuntimeMultiSelect({ React, Box, Text, useInput, h, action, statuses, onSubmit }) {
+  const initialSelected = React.useMemo(() => new Set(defaultRuntimeSelections(statuses, action)), [statuses, action]);
+  const [index, setIndex] = React.useState(0);
+  const [selected, setSelected] = React.useState(initialSelected);
+  const [error, setError] = React.useState('');
+
+  function toggle(status) {
+    setError('');
+    if (!isSelectableRuntimeStatus(status, action)) {
+      setError(unavailableRuntimeSelectionMessage(status, action));
+      return;
+    }
+    setSelected((current) => {
+      const next = new Set(current);
+      if (next.has(status.runtime)) {
+        next.delete(status.runtime);
+      } else {
+        next.add(status.runtime);
+      }
+      return next;
+    });
+  }
+
+  useInput((input, key) => {
+    if (key.upArrow || input === 'k') {
+      setIndex((current) => Math.max(0, current - 1));
+    } else if (key.downArrow || input === 'j') {
+      setIndex((current) => Math.min(statuses.length - 1, current + 1));
+    } else if (key.home) {
+      setIndex(0);
+    } else if (key.end) {
+      setIndex(statuses.length - 1);
+    } else if (input === ' ') {
+      toggle(statuses[index]);
+    } else if (input === 'a') {
+      setError('');
+      setSelected(new Set(action === 'update' ? selectableRuntimeSelections(statuses, action) : RUNTIMES));
+    } else if (input === 'i') {
+      setError('');
+      setSelected(new Set(detectedRuntimeSelections(statuses, action)));
+    } else if (key.return || /[\r\n]/.test(input)) {
+      const runtimes = RUNTIMES.filter((runtime) => selected.has(runtime));
+      if (runtimes.length === 0) {
+        setError(emptyRuntimeSelectionMessage(statuses, action));
+        return;
+      }
+      onSubmit(runtimes);
+    }
+  });
+
+  return h(Box, { flexDirection: 'column' },
+    h(Text, { bold: true }, `Runtimes to ${action}`),
+    h(Text, { dimColor: true }, `${action === 'update' ? 'Space toggles installed runtimes. a selects installed runtimes.' : 'Space toggles. a selects all.'} i selects detected installs. Enter continues.`),
+    ...statuses.map((status, itemIndex) => {
+      const checked = selected.has(status.runtime) ? '[x]' : '[ ]';
+      const cursor = itemIndex === index ? '>' : ' ';
+      return h(Text, {
+        key: status.runtime,
+        color: itemIndex === index ? 'cyan' : undefined,
+      }, `${cursor} ${checked} ${status.runtime.padEnd(12)} ${status.detail} (${displayPath(status.targetRoot)})`);
+    }),
+    error ? h(Text, { color: 'red' }, error) : null
+  );
+}
+
+function ConfirmUninstall({ React, Box, Text, useInput, h, runtimes, onSubmit }) {
+  const [text, setText] = React.useState('');
+  const [error, setError] = React.useState('');
+
+  useInput((input, key) => {
+    const submit = key.return || /[\r\n]/.test(input);
+    if (submit) {
+      const printable = input.replace(/[^\x20-\x7E]/g, '');
+      const nextText = `${text}${printable}`;
+      if (nextText.trim().toLowerCase() === 'uninstall') {
+        onSubmit();
+        return;
+      }
+      setError('Type uninstall to continue.');
+    } else if (key.backspace || key.delete) {
+      setError('');
+      setText((current) => current.slice(0, -1));
+    } else if (!key.ctrl && input) {
+      const printable = input.replace(/[^\x20-\x7E]/g, '');
+      if (printable) {
+        setError('');
+        setText((current) => `${current}${printable}`);
+      }
+    }
+  });
+
+  return h(Box, { flexDirection: 'column' },
+    h(Text, { bold: true, color: 'yellow' }, 'Confirm uninstall'),
+    h(Text, null, `Selected runtimes: ${runtimes.join(', ')}`),
+    h(Text, { dimColor: true }, 'Only manifest-managed files and generated clean-room hook entries are removed.'),
+    h(Text, null, `Type uninstall: ${text}`),
+    error ? h(Text, { color: 'red' }, error) : null
+  );
+}
+
+module.exports = {
+  ConfirmUninstall,
+  InstallerTui,
+  RuntimeMultiSelect,
+  SingleChoice,
+  defaultActionIndex,
+  nextTuiStage,
+  resolveInteractiveOptions,
+  runInstallerTui,
+};

package/lib/preflight-bootstrap.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+const { resolveGoalPath } = require('./preflight-paths.cjs');
+
+/**
+ * Apply bootstrap output policy values to the preflight goal object.
+ * @param {object} goal - Preflight goal object.
+ * @param {object} bootstrap - Verified bootstrap metadata and roots.
+ */
+function applyBootstrapOutputPolicy(goal, bootstrap) {
+  goal.output_policy.artifact_base_root = bootstrap.outputRoot;
+  goal.output_policy.implementation_root = bootstrap.roots.implementation;
+}
+
+/**
+ * Validate that the preflight goal output policy matches bootstrap paths.
+ * @param {object} goal - Preflight goal object.
+ * @param {object} bootstrap - Verified bootstrap metadata and roots.
+ * @param {string} cwd - Current working directory.
+ * @param {string} homeDir - User home directory.
+ * @returns {string[]} Validation error messages.
+ */
+function validateBootstrapOutputPolicy(goal, bootstrap, cwd, homeDir) {
+  const errors = [];
+  const artifactBaseRoot = resolveGoalPath(goal?.output_policy?.artifact_base_root, cwd, homeDir);
+  const implementationRoot = resolveGoalPath(goal?.output_policy?.implementation_root, cwd, homeDir);
+  if (artifactBaseRoot !== bootstrap.outputRoot) {
+    errors.push(`output_policy.artifact_base_root must match bootstrap task root: ${bootstrap.outputRoot}`);
+  }
+  if (implementationRoot !== bootstrap.roots.implementation) {
+    errors.push(`output_policy.implementation_root must match bootstrap implementation root: ${bootstrap.roots.implementation}`);
+  }
+  return errors;
+}
+
+module.exports = {
+  applyBootstrapOutputPolicy,
+  validateBootstrapOutputPolicy,
+};