clean-room-skill 0.1.12 → 0.1.13

package/lib/preflight-cli.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Print the help/usage message for the clean-room-skill preflight command.
+ */
+function printPreflightHelp() {
+  console.log(`Usage: clean-room-skill preflight (--template | --input <path>) (--output <path> | --bootstrap <path>) [options]
+
+Create or validate a clean-room preflight goal contract.
+
+Options:
+  --template             Write an attended draft with blocking open questions
+  --input <path>         Validate and normalize/copy a completed preflight goal
+  --output <path>        Destination preflight-goal.json
+  --bootstrap <path>     Generated task root or clean-room-bootstrap.json
+  --mode <mode>          attended or unattended (template supports attended only)
+  --dry-run              Print actions without writing files
+  --force                Overwrite output if it already exists
+  -h, --help             Show this help
+`);
+}
+
+/**
+ * Parse command line arguments for the preflight command.
+ * @param {string[]} argv - The command line arguments.
+ * @returns {object} The parsed options.
+ */
+function parsePreflightArgs(argv) {
+  const options = {
+    template: false,
+    input: null,
+    output: null,
+    bootstrap: null,
+    mode: 'attended',
+    dryRun: false,
+    force: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '--template') {
+      options.template = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--force') {
+      options.force = true;
+    } else if (arg === '--input') {
+      index += 1;
+      options.input = requiredValue(argv, index, '--input');
+    } else if (arg.startsWith('--input=')) {
+      options.input = arg.slice('--input='.length);
+    } else if (arg === '--output') {
+      index += 1;
+      options.output = requiredValue(argv, index, '--output');
+    } else if (arg.startsWith('--output=')) {
+      options.output = arg.slice('--output='.length);
+    } else if (arg === '--bootstrap') {
+      index += 1;
+      options.bootstrap = requiredValue(argv, index, '--bootstrap');
+    } else if (arg.startsWith('--bootstrap=')) {
+      options.bootstrap = arg.slice('--bootstrap='.length);
+    } else if (arg === '--mode') {
+      index += 1;
+      options.mode = requiredValue(argv, index, '--mode');
+    } else if (arg.startsWith('--mode=')) {
+      options.mode = arg.slice('--mode='.length);
+    } else {
+      throw new Error(`unknown preflight option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Get a required argument value or throw an error.
+ * @param {string[]} argv - The command line arguments.
+ * @param {number} index - The index of the argument.
+ * @param {string} flag - The name of the flag.
+ * @returns {string} The flag's value.
+ */
+function requiredValue(argv, index, flag) {
+  if (index >= argv.length || argv[index] === '') {
+    throw new Error(`${flag} requires a value`);
+  }
+  return argv[index];
+}
+
+module.exports = {
+  parsePreflightArgs,
+  printPreflightHelp,
+};

package/lib/preflight-constants.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+const VALID_MODES = new Set(['attended', 'unattended']);
+const VALID_INTENTS = new Set([
+  'clean-room-reimplementation',
+  'behavior-compatible-port',
+  'api-compatible-clone',
+  'modernization',
+  'partial-feature-extraction',
+  'test-spec-generation-only',
+  'other',
+]);
+const VALID_EXECUTION_BACKENDS = new Set(['host', 'docker', 'podman']);
+const VALID_CONTAINER_PROFILES = new Set(['node22', 'python312', 'go126', 'rust-stable']);
+const VALID_NETWORK_POLICIES = new Set(['off', 'deps-only', 'on']);
+const VALID_DEPENDENCY_INSTALL_POLICIES = new Set(['offline', 'locked', 'allow-new']);
+
+module.exports = {
+  VALID_CONTAINER_PROFILES,
+  VALID_DEPENDENCY_INSTALL_POLICIES,
+  VALID_EXECUTION_BACKENDS,
+  VALID_INTENTS,
+  VALID_MODES,
+  VALID_NETWORK_POLICIES,
+};

package/lib/preflight-output.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+const {
+  atomicWriteFile,
+  atomicWriteFileNoOverwrite,
+} = require('./fs-utils.cjs');
+
+/**
+ * Write preflight goal object to file or dry-run print it.
+ * @param {string} outputPath - Target file path.
+ * @param {object} goal - Preflight goal object.
+ * @param {object} options - Write options (force, dryRun).
+ */
+function writePreflightOutput(outputPath, goal, options) {
+  const data = `${JSON.stringify(goal, null, 2)}\n`;
+  if (options.dryRun) {
+    console.log(`Would write preflight goal: ${outputPath}`);
+    return;
+  }
+  try {
+    if (options.force) {
+      atomicWriteFile(outputPath, data, 'utf8');
+    } else {
+      atomicWriteFileNoOverwrite(outputPath, data, 'utf8');
+    }
+  } catch (err) {
+    if (err?.code === 'EEXIST') {
+      throw new Error(`preflight output already exists; use --force to overwrite: ${outputPath}`);
+    }
+    throw err;
+  }
+  console.log(`Wrote preflight goal: ${outputPath}`);
+}
+
+module.exports = {
+  writePreflightOutput,
+};

package/lib/preflight-paths.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+
+/**
+ * Expand tilde character `~` to home directory.
+ * @param {string} value - Path value which may start with `~`.
+ * @param {string} [homeDir=os.homedir()] - User home directory.
+ * @returns {string} The expanded path.
+ */
+function expandTilde(value, homeDir = os.homedir()) {
+  if (value === '~') return homeDir;
+  if (typeof value === 'string' && value.startsWith('~/')) return path.join(homeDir, value.slice(2));
+  return value;
+}
+
+/**
+ * Resolve the destination preflight output path.
+ * @param {string} value - Path value.
+ * @param {string} [cwd=process.cwd()] - Current working directory.
+ * @param {string} [homeDir=os.homedir()] - User home directory.
+ * @returns {string} The resolved absolute path.
+ */
+function resolveOutputPath(value, cwd = process.cwd(), homeDir = os.homedir()) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('--output requires a path');
+  }
+  const expanded = expandTilde(value, homeDir);
+  return path.resolve(cwd, expanded);
+}
+
+/**
+ * Resolve the input preflight goal path.
+ * @param {string} value - Path value.
+ * @param {string} [cwd=process.cwd()] - Current working directory.
+ * @param {string} [homeDir=os.homedir()] - User home directory.
+ * @returns {string} The resolved absolute path.
+ */
+function resolveInputPath(value, cwd = process.cwd(), homeDir = os.homedir()) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('--input requires a path');
+  }
+  const expanded = expandTilde(value, homeDir);
+  return path.resolve(cwd, expanded);
+}
+
+/**
+ * Resolve a path value within the preflight goal configuration.
+ * @param {string|null|undefined} value - Path value to resolve.
+ * @param {string} cwd - Current working directory.
+ * @param {string} homeDir - User home directory.
+ * @returns {string|null} Resolved absolute path or null.
+ */
+function resolveGoalPath(value, cwd, homeDir) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return null;
+  }
+  return path.resolve(cwd, expandTilde(value, homeDir));
+}
+
+module.exports = {
+  expandTilde,
+  resolveGoalPath,
+  resolveInputPath,
+  resolveOutputPath,
+};

package/lib/preflight-template.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * Build a default attended preflight goal template object.
+ * @param {string} [mode='attended'] - Controller mode.
+ * @returns {object} The preflight goal template object.
+ */
+function buildTemplate(mode = 'attended') {
+  if (mode !== 'attended') {
+    throw new Error('preflight --template supports attended mode only');
+  }
+  return {
+    goal_id: 'goal-task-xxxxxxxx',
+    created_at: new Date().toISOString(),
+    end_goal: {
+      intent: 'clean-room-reimplementation',
+      success_definition: 'TBD: define the observable result the clean implementation must achieve.',
+      destination_kind: 'new-project',
+      existing_destination_policy: 'inspect-and-preserve',
+    },
+    target_stack: {
+      language: 'TBD',
+      runtime: null,
+      framework: null,
+      package_manager: null,
+      test_framework: null,
+    },
+    license_policy: {
+      source_license_notes: 'unknown',
+      destination_license: 'TBD',
+      dependency_license_allowlist: ['MIT', 'Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause'],
+      dependency_license_blocklist: ['GPL-3.0', 'AGPL-3.0'],
+    },
+    dependency_policy: {
+      allow_new_dependencies: true,
+      prefer_stdlib: true,
+      require_user_approval_for_native_deps: true,
+      blocked_dependencies: [],
+    },
+    compatibility_policy: {
+      mirror_public_behavior: true,
+      mirror_public_api_names: true,
+      mirror_private_structure: false,
+      mirror_comments_or_internal_names: false,
+      allowed_exactness: [
+        'public API names',
+        'CLI flags',
+        'serialized outputs',
+        'documented protocol behavior',
+        'public error codes',
+      ],
+    },
+    feature_policy: {
+      preserve_features: [],
+      remove_features: [],
+      add_features: [],
+      non_goals: [],
+    },
+    code_hygiene_policy: {
+      max_lines_per_code_file: 500,
+      max_lines_per_test_file: 800,
+      max_files_per_iteration: 12,
+      split_large_files_by: ['module boundary', 'public type', 'feature area'],
+      exceptions: ['generated files', 'fixtures', 'snapshots'],
+      forbidden_patterns: ['god file', 'source-shaped layout'],
+    },
+    output_policy: {
+      artifact_base_root: '~/Documents/CleanRoom/<task-id>/',
+      implementation_root: '~/Documents/CleanRoom/<task-id>/implementation/',
+      assumed_output_directory: 'implementation/',
+      write_mode: 'create-or-preserve-existing',
+    },
+    execution_policy: {
+      backend: 'host',
+      preferred_container_profile: 'node22',
+      network_policy: 'off',
+      dependency_install_policy: 'locked',
+      allow_native_toolchain: false,
+      resource_limits: {
+        cpus: 2,
+        memory_mb: 2048,
+        timeout_seconds: 300,
+      },
+    },
+    controller_policy: {
+      mode: 'attended',
+      unattended_allowed_after_preflight: false,
+      max_iterations: 10,
+    },
+    open_questions: [
+      {
+        question_id: 'goal-end-state',
+        question: 'Define the end goal, target stack, compatibility exactness, dependency policy, license policy, and output root before execution.',
+        blocking: true,
+        default_assumption: 'Do not start source analysis until this is answered.',
+      },
+    ],
+  };
+}
+
+module.exports = {
+  buildTemplate,
+};

package/lib/preflight-validation.cjs

@@ -0,0 +1,276 @@
+'use strict';
+
+const {
+  VALID_CONTAINER_PROFILES,
+  VALID_DEPENDENCY_INSTALL_POLICIES,
+  VALID_EXECUTION_BACKENDS,
+  VALID_INTENTS,
+  VALID_MODES,
+  VALID_NETWORK_POLICIES,
+} = require('./preflight-constants.cjs');
+
+/**
+ * Assert that a value is an object (not null and not an array), appending errors on failure.
+ * @param {any} value - Value to check.
+ * @param {string} label - Field label for error message.
+ * @param {string[]} errors - Array to push error messages into.
+ * @returns {boolean} True if validation passes, otherwise false.
+ */
+function expectObject(value, label, errors) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push(`${label} must be an object`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Assert that a value is an array, appending errors on failure.
+ * @param {any} value - Value to check.
+ * @param {string} label - Field label for error message.
+ * @param {string[]} errors - Array to push error messages into.
+ * @returns {boolean} True if validation passes, otherwise false.
+ */
+function expectArray(value, label, errors) {
+  if (!Array.isArray(value)) {
+    errors.push(`${label} must be an array`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Assert that a value is a string, appending errors on failure.
+ * @param {any} value - Value to check.
+ * @param {string} label - Field label for error message.
+ * @param {string[]} errors - Array to push error messages into.
+ * @param {boolean} [allowEmpty=false] - Whether to allow empty string.
+ * @returns {boolean} True if validation passes, otherwise false.
+ */
+function expectString(value, label, errors, allowEmpty = false) {
+  if (typeof value !== 'string' || (!allowEmpty && value.length === 0)) {
+    errors.push(`${label} must be a non-empty string`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Assert that a value is a boolean, appending errors on failure.
+ * @param {any} value - Value to check.
+ * @param {string} label - Field label for error message.
+ * @param {string[]} errors - Array to push error messages into.
+ * @returns {boolean} True if validation passes, otherwise false.
+ */
+function expectBoolean(value, label, errors) {
+  if (typeof value !== 'boolean') {
+    errors.push(`${label} must be a boolean`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Assert that a value is a positive integer, appending errors on failure.
+ * @param {any} value - Value to check.
+ * @param {string} label - Field label for error message.
+ * @param {string[]} errors - Array to push error messages into.
+ * @returns {boolean} True if validation passes, otherwise false.
+ */
+function expectPositiveInteger(value, label, errors) {
+  if (!Number.isInteger(value) || value < 1) {
+    errors.push(`${label} must be a positive integer`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Validate that an object property is a string array.
+ * @param {object} root - Object containing the field.
+ * @param {string} field - Field name.
+ * @param {string[]} errors - Array to push error messages into.
+ */
+function validateStringArray(root, field, errors) {
+  if (!expectArray(root?.[field], field, errors)) return;
+  for (const [index, item] of root[field].entries()) {
+    expectString(item, `${field}[${index}]`, errors);
+  }
+}
+
+/**
+ * Validate a preflight goal contract object.
+ * @param {object} goal - Goal contract object to validate.
+ * @param {object} [options={}] - Validation options (e.g. requireComplete).
+ * @returns {string[]} Array of validation error messages.
+ */
+function validateGoalContract(goal, options = {}) {
+  const errors = [];
+  if (!expectObject(goal, 'preflight goal', errors)) {
+    return errors;
+  }
+
+  expectString(goal.goal_id, 'goal_id', errors);
+  expectString(goal.created_at, 'created_at', errors);
+
+  if (expectObject(goal.end_goal, 'end_goal', errors)) {
+    if (!VALID_INTENTS.has(goal.end_goal.intent)) {
+      errors.push('end_goal.intent is not supported');
+    }
+    expectString(goal.end_goal.success_definition, 'end_goal.success_definition', errors);
+    expectString(goal.end_goal.destination_kind, 'end_goal.destination_kind', errors);
+    expectString(goal.end_goal.existing_destination_policy, 'end_goal.existing_destination_policy', errors);
+  }
+
+  if (expectObject(goal.target_stack, 'target_stack', errors)) {
+    expectString(goal.target_stack.language, 'target_stack.language', errors);
+    for (const field of ['runtime', 'framework', 'package_manager', 'test_framework']) {
+      if (goal.target_stack[field] !== null) {
+        expectString(goal.target_stack[field], `target_stack.${field}`, errors);
+      }
+    }
+  }
+
+  if (expectObject(goal.license_policy, 'license_policy', errors)) {
+    expectString(goal.license_policy.source_license_notes, 'license_policy.source_license_notes', errors, true);
+    expectString(goal.license_policy.destination_license, 'license_policy.destination_license', errors);
+    validateStringArray(goal.license_policy, 'dependency_license_allowlist', errors);
+    validateStringArray(goal.license_policy, 'dependency_license_blocklist', errors);
+  }
+
+  if (expectObject(goal.dependency_policy, 'dependency_policy', errors)) {
+    expectBoolean(goal.dependency_policy.allow_new_dependencies, 'dependency_policy.allow_new_dependencies', errors);
+    expectBoolean(goal.dependency_policy.prefer_stdlib, 'dependency_policy.prefer_stdlib', errors);
+    expectBoolean(
+      goal.dependency_policy.require_user_approval_for_native_deps,
+      'dependency_policy.require_user_approval_for_native_deps',
+      errors
+    );
+    validateStringArray(goal.dependency_policy, 'blocked_dependencies', errors);
+  }
+
+  if (expectObject(goal.compatibility_policy, 'compatibility_policy', errors)) {
+    expectBoolean(goal.compatibility_policy.mirror_public_behavior, 'compatibility_policy.mirror_public_behavior', errors);
+    expectBoolean(goal.compatibility_policy.mirror_public_api_names, 'compatibility_policy.mirror_public_api_names', errors);
+    if (goal.compatibility_policy.mirror_private_structure !== false) {
+      errors.push('compatibility_policy.mirror_private_structure must be false');
+    }
+    if (goal.compatibility_policy.mirror_comments_or_internal_names !== false) {
+      errors.push('compatibility_policy.mirror_comments_or_internal_names must be false');
+    }
+    validateStringArray(goal.compatibility_policy, 'allowed_exactness', errors);
+  }
+
+  if (expectObject(goal.feature_policy, 'feature_policy', errors)) {
+    for (const field of ['preserve_features', 'remove_features', 'add_features', 'non_goals']) {
+      validateStringArray(goal.feature_policy, field, errors);
+    }
+  }
+
+  validateCodeHygienePolicy(goal.code_hygiene_policy, errors);
+
+  if (expectObject(goal.output_policy, 'output_policy', errors)) {
+    expectString(goal.output_policy.artifact_base_root, 'output_policy.artifact_base_root', errors);
+    expectString(goal.output_policy.implementation_root, 'output_policy.implementation_root', errors);
+    expectString(goal.output_policy.assumed_output_directory, 'output_policy.assumed_output_directory', errors);
+    expectString(goal.output_policy.write_mode, 'output_policy.write_mode', errors);
+  }
+
+  if (goal.execution_policy !== undefined) {
+    validateExecutionPolicy(goal.execution_policy, errors);
+  }
+
+  if (expectObject(goal.controller_policy, 'controller_policy', errors)) {
+    if (!VALID_MODES.has(goal.controller_policy.mode)) {
+      errors.push('controller_policy.mode must be attended or unattended');
+    }
+    expectBoolean(
+      goal.controller_policy.unattended_allowed_after_preflight,
+      'controller_policy.unattended_allowed_after_preflight',
+      errors
+    );
+    expectPositiveInteger(goal.controller_policy.max_iterations, 'controller_policy.max_iterations', errors);
+  }
+
+  if (expectArray(goal.open_questions, 'open_questions', errors)) {
+    for (const [index, question] of goal.open_questions.entries()) {
+      if (!expectObject(question, `open_questions[${index}]`, errors)) continue;
+      expectString(question.question_id, `open_questions[${index}].question_id`, errors);
+      expectString(question.question, `open_questions[${index}].question`, errors);
+      expectBoolean(question.blocking, `open_questions[${index}].blocking`, errors);
+    }
+  }
+
+  if (goal.controller_policy?.mode === 'unattended') {
+    if (goal.controller_policy.unattended_allowed_after_preflight !== true) {
+      errors.push('unattended preflight requires unattended_allowed_after_preflight=true');
+    }
+    if (Array.isArray(goal.open_questions) && goal.open_questions.length > 0) {
+      errors.push('unattended preflight requires no open_questions');
+    }
+  }
+
+  if (options.requireComplete && Array.isArray(goal.open_questions)) {
+    const blocking = goal.open_questions.filter((question) => question?.blocking === true);
+    if (blocking.length > 0) {
+      errors.push('completed preflight input must not contain blocking open_questions');
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate the execution policy block of a preflight goal contract.
+ * @param {object} policy - Execution policy object.
+ * @param {string[]} errors - Array to push error messages into.
+ */
+function validateExecutionPolicy(policy, errors) {
+  if (!expectObject(policy, 'execution_policy', errors)) return;
+  if (!VALID_EXECUTION_BACKENDS.has(policy.backend)) {
+    errors.push('execution_policy.backend must be host, docker, or podman');
+  }
+  if (!VALID_CONTAINER_PROFILES.has(policy.preferred_container_profile)) {
+    errors.push('execution_policy.preferred_container_profile is not supported');
+  }
+  if (!VALID_NETWORK_POLICIES.has(policy.network_policy)) {
+    errors.push('execution_policy.network_policy must be off, deps-only, or on');
+  }
+  if (!VALID_DEPENDENCY_INSTALL_POLICIES.has(policy.dependency_install_policy)) {
+    errors.push('execution_policy.dependency_install_policy must be offline, locked, or allow-new');
+  }
+  expectBoolean(policy.allow_native_toolchain, 'execution_policy.allow_native_toolchain', errors);
+  if (!expectObject(policy.resource_limits, 'execution_policy.resource_limits', errors)) return;
+  expectPositiveInteger(policy.resource_limits.memory_mb, 'execution_policy.resource_limits.memory_mb', errors);
+  expectPositiveInteger(policy.resource_limits.timeout_seconds, 'execution_policy.resource_limits.timeout_seconds', errors);
+  if (typeof policy.resource_limits.cpus !== 'number' || policy.resource_limits.cpus < 1 || policy.resource_limits.cpus > 16) {
+    errors.push('execution_policy.resource_limits.cpus must be a number between 1 and 16');
+  }
+  if (Number.isInteger(policy.resource_limits.memory_mb) && policy.resource_limits.memory_mb > 65536) {
+    errors.push('execution_policy.resource_limits.memory_mb must be at most 65536');
+  }
+  if (Number.isInteger(policy.resource_limits.timeout_seconds) && policy.resource_limits.timeout_seconds > 600) {
+    errors.push('execution_policy.resource_limits.timeout_seconds must be at most 600');
+  }
+}
+
+/**
+ * Validate the code hygiene policy block of a preflight goal contract.
+ * @param {object} policy - Code hygiene policy object.
+ * @param {string[]} errors - Array to push error messages into.
+ */
+function validateCodeHygienePolicy(policy, errors) {
+  if (!expectObject(policy, 'code_hygiene_policy', errors)) return;
+  expectPositiveInteger(policy.max_lines_per_code_file, 'code_hygiene_policy.max_lines_per_code_file', errors);
+  expectPositiveInteger(policy.max_lines_per_test_file, 'code_hygiene_policy.max_lines_per_test_file', errors);
+  expectPositiveInteger(policy.max_files_per_iteration, 'code_hygiene_policy.max_files_per_iteration', errors);
+  validateStringArray(policy, 'split_large_files_by', errors);
+  validateStringArray(policy, 'exceptions', errors);
+  if (policy.forbidden_patterns !== undefined) {
+    validateStringArray(policy, 'forbidden_patterns', errors);
+  }
+}
+
+module.exports = {
+  validateGoalContract,
+};