@rover-studio/answer-me 0.1.0-rc.1

package/lib/npm-cli/usage-validation.mjs

@@ -0,0 +1,349 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  MAX_BUFFER,
+  OFFICIAL_API_ROOT,
+  USAGE_VALIDATION_TIMEOUT_SECONDS,
+} from './constants.mjs';
+import { normalizePath, pathExists } from './filesystem.mjs';
+
+const ENROLLMENT_EVENT = 'answerme.creator-enrollment.verification-url';
+const ENROLLMENT_STAGE = 'verification-handoff';
+const MAX_ENROLLMENT_EVENT_BYTES = 4096;
+const SELF_TEST_OUTPUT_KEYS = Object.freeze([
+  'cleanupWarning',
+  'code',
+  'message',
+  'networkCalled',
+  'ok',
+  'resultTokenCleanup',
+  'stage',
+  'status',
+]);
+const SELF_TEST_ISSUES = Object.freeze({
+  'self-test-dependency-missing': Object.freeze({
+    stage: 'preflight',
+    message: 'A required AnswerMe self-test adapter is missing.',
+  }),
+  'self-test-resume-unsupported': Object.freeze({
+    stage: 'preflight',
+    message: 'Installation usage validation must create and wait for its own fixed questionnaire.',
+  }),
+  'self-test-create-stderr-invalid': Object.freeze({
+    stage: 'create',
+    message: 'The AnswerMe create adapter emitted an untrusted stderr record.',
+  }),
+  'self-test-create-validation-failed': Object.freeze({
+    stage: 'create',
+    message: 'The AnswerMe self-test questionnaire contract could not be validated.',
+  }),
+  'self-test-create-failed': Object.freeze({
+    stage: 'create',
+    message: 'The AnswerMe self-test questionnaire could not be created and verified.',
+  }),
+  'self-test-wait-failed': Object.freeze({
+    stage: 'wait',
+    message: 'The AnswerMe self-test did not reach a readable terminal result.',
+  }),
+  'self-test-result-invalid': Object.freeze({
+    stage: 'mapping',
+    message: 'The AnswerMe self-test result did not match the fixed three-question contract.',
+  }),
+});
+const CLEANUP_WARNING = Object.freeze({
+  code: 'self-test-cleanup-failed',
+  message: 'The protected self-test Result Token could not be confirmed removed.',
+});
+
+function isExactOfficialApiRoot(value = OFFICIAL_API_ROOT) {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:'
+      && url.origin === value
+      && url.pathname === '/'
+      && !url.username
+      && !url.password
+      && !url.search
+      && !url.hash;
+  } catch {
+    return false;
+  }
+}
+
+if (!isExactOfficialApiRoot()) throw new Error('invalid official AnswerMe API root');
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasExactKeys(value, keys) {
+  return isRecord(value)
+    && JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...keys].sort());
+}
+
+function exactCleanup(value, attempted, removed) {
+  return hasExactKeys(value, ['attempted', 'removed'])
+    && value.attempted === attempted
+    && value.removed === removed;
+}
+
+function exactCleanupWarning(value) {
+  return hasExactKeys(value, ['code', 'message'])
+    && value.code === CLEANUP_WARNING.code
+    && value.message === CLEANUP_WARNING.message;
+}
+
+function validateSelfTestOutput(value) {
+  if (!hasExactKeys(value, SELF_TEST_OUTPUT_KEYS) || typeof value.networkCalled !== 'boolean') return false;
+  if (value.ok === true
+    && value.status === 'passed'
+    && value.stage === 'complete'
+    && value.code === null
+    && value.message === null
+    && value.networkCalled === true
+    && (exactCleanup(value.resultTokenCleanup, true, true)
+      || exactCleanup(value.resultTokenCleanup, true, false))) {
+    return value.resultTokenCleanup.removed === true
+      ? value.cleanupWarning === null
+      : value.resultTokenCleanup.removed === false && exactCleanupWarning(value.cleanupWarning);
+  }
+  const issue = typeof value.code === 'string' ? SELF_TEST_ISSUES[value.code] : null;
+  return value.ok === false
+    && value.status === 'issue'
+    && issue !== null
+    && value.stage === issue.stage
+    && value.message === issue.message
+    && exactCleanup(value.resultTokenCleanup, false, false)
+    && value.cleanupWarning === null;
+}
+
+function parseSingleJson(stdout) {
+  const lines = String(stdout ?? '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.length !== 1 || Buffer.byteLength(lines[0], 'utf8') > MAX_BUFFER) return null;
+  try {
+    const value = JSON.parse(lines[0]);
+    return isRecord(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseEnrollmentEvent(line) {
+  const text = String(line ?? '').trim();
+  if (!text || Buffer.byteLength(text, 'utf8') > MAX_ENROLLMENT_EVENT_BYTES) return null;
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(value)
+    || JSON.stringify(Object.keys(value).sort()) !== JSON.stringify(['event', 'stage', 'verificationUrl'])
+    || value.event !== ENROLLMENT_EVENT
+    || value.stage !== ENROLLMENT_STAGE
+    || typeof value.verificationUrl !== 'string') {
+    return null;
+  }
+  let verificationUrl;
+  try {
+    verificationUrl = new URL(value.verificationUrl);
+  } catch {
+    return null;
+  }
+  if (verificationUrl.protocol !== 'https:'
+    || verificationUrl.origin !== OFFICIAL_API_ROOT
+    || verificationUrl.username
+    || verificationUrl.password
+    || verificationUrl.hash) {
+    return null;
+  }
+  return JSON.stringify({
+    event: ENROLLMENT_EVENT,
+    stage: ENROLLMENT_STAGE,
+    verificationUrl: verificationUrl.href,
+  });
+}
+
+function safeProcessError(code) {
+  return Object.assign(new Error(code), { code });
+}
+
+function invokeValidationProcess(executable, args, options, dependencies = {}) {
+  return new Promise((resolve, reject) => {
+    const spawn = dependencies.spawn ?? nodeSpawn;
+    const stderrWriter = dependencies.stderrWriter ?? ((text) => process.stderr.write(text));
+    let child;
+    try {
+      child = spawn(executable, args, {
+        shell: false,
+        windowsHide: true,
+        env: options.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch {
+      reject(safeProcessError('usage-validation-process-start-failed'));
+      return;
+    }
+    if (!child?.stdout || !child?.stderr || typeof child.kill !== 'function') {
+      try { child?.kill?.(); } catch { /* the process handle is already invalid */ }
+      reject(safeProcessError('usage-validation-process-invalid'));
+      return;
+    }
+
+    let settled = false;
+    let stdout = '';
+    let stdoutBytes = 0;
+    let stderrPending = '';
+    let stderrBytes = 0;
+    let enrollmentEventCount = 0;
+    let failureCode = null;
+    let timedOut = false;
+
+    const stop = (code) => {
+      if (!failureCode) failureCode = code;
+      try { child.kill(); } catch { /* close/error settles the result */ }
+    };
+    const consumeStderrLine = (line) => {
+      if (!line) {
+        stop('usage-validation-stderr-invalid');
+        return;
+      }
+      const safeEvent = parseEnrollmentEvent(line);
+      if (!safeEvent || enrollmentEventCount !== 0) {
+        stop('usage-validation-stderr-invalid');
+        return;
+      }
+      enrollmentEventCount += 1;
+      try {
+        stderrWriter(`${safeEvent}\n`);
+      } catch {
+        stop('usage-validation-stderr-relay-failed');
+      }
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stop('ETIMEDOUT');
+    }, options.timeoutMs);
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(error);
+      else resolve(value);
+    };
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdoutBytes += Buffer.byteLength(chunk, 'utf8');
+      if (stdoutBytes > options.maxBuffer) {
+        stop('usage-validation-stdout-too-large');
+        return;
+      }
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderrBytes += Buffer.byteLength(chunk, 'utf8');
+      if (stderrBytes > options.maxBuffer) {
+        stop('usage-validation-stderr-too-large');
+        return;
+      }
+      stderrPending += chunk;
+      let newline;
+      while ((newline = stderrPending.indexOf('\n')) !== -1) {
+        const line = stderrPending.slice(0, newline).replace(/\r$/, '');
+        stderrPending = stderrPending.slice(newline + 1);
+        consumeStderrLine(line);
+      }
+    });
+    child.stdout.once('error', () => stop('usage-validation-stdout-read-failed'));
+    child.stderr.once('error', () => stop('usage-validation-stderr-read-failed'));
+    child.once('error', () => finish(safeProcessError('usage-validation-process-error')));
+    child.once('close', (code, signal) => {
+      if (stderrPending) stop('usage-validation-stderr-invalid');
+      if (timedOut) {
+        finish(safeProcessError('ETIMEDOUT'));
+      } else if (failureCode) {
+        finish(safeProcessError(failureCode));
+      } else if (code !== 0 || signal) {
+        finish(safeProcessError('usage-validation-process-exit'));
+      } else {
+        finish(null, { stdout });
+      }
+    });
+  });
+}
+
+async function validatePowerShell(candidate, dependencies) {
+  if (typeof candidate !== 'string' || !path.isAbsolute(candidate) || path.basename(candidate).toLowerCase() !== 'powershell.exe') {
+    return false;
+  }
+  if (typeof dependencies.inspectPowerShell === 'function') return dependencies.inspectPowerShell(candidate);
+  const info = await lstat(candidate).catch(() => null);
+  if (!info?.isFile() || info.isSymbolicLink()) return false;
+  return normalizePath(await realpath(candidate)) === normalizePath(candidate);
+}
+
+function result(status, code, cleanupWarning = null) {
+  return { status, code, cleanupWarning };
+}
+
+function windowsPowerShellEnvironment(powershellExecutable, source = process.env) {
+  const environment = {};
+  for (const [key, value] of Object.entries(source ?? {})) {
+    if (key.toLowerCase() !== 'psmodulepath' && value !== undefined) environment[key] = value;
+  }
+  environment.PSModulePath = path.join(path.dirname(powershellExecutable), 'Modules');
+  return environment;
+}
+
+export async function runUsageValidation({ skillsRoot, timeoutSeconds = USAGE_VALIDATION_TIMEOUT_SECONDS }, dependencies = {}) {
+  const script = path.join(skillsRoot, 'answerme', 'scripts', 'test-answerme-installation.ps1');
+  const powershell = dependencies.powershellExecutable
+    ?? path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  if (timeoutSeconds !== USAGE_VALIDATION_TIMEOUT_SECONDS
+    || !(await pathExists(script))
+    || !(await validatePowerShell(powershell, dependencies))) {
+    return result('issue', 'usage-validation-runner-unavailable');
+  }
+  try {
+    const runner = dependencies.invokeProcess ?? invokeValidationProcess;
+    const executed = await runner(powershell, [
+      '-NoLogo',
+      '-NoProfile',
+      '-NonInteractive',
+      '-ExecutionPolicy', 'Bypass',
+      '-File', script,
+      '-ApiBaseUrl', OFFICIAL_API_ROOT,
+      '-WaitTimeoutSeconds', String(USAGE_VALIDATION_TIMEOUT_SECONDS),
+    ], {
+      timeoutMs: (USAGE_VALIDATION_TIMEOUT_SECONDS + 30) * 1000,
+      maxBuffer: MAX_BUFFER,
+      env: windowsPowerShellEnvironment(powershell, dependencies.environment ?? process.env),
+    }, dependencies);
+    const parsed = parseSingleJson(executed?.stdout ?? executed);
+    if (!parsed || !validateSelfTestOutput(parsed)) return result('issue', 'usage-validation-output-invalid');
+    const cleanupWarning = parsed.cleanupWarning ? 'cleanup-warning' : null;
+    if (parsed.status === 'passed' && parsed.ok === true) {
+      return result('passed', 'usage-validation-passed', cleanupWarning);
+    }
+    if (parsed.status === 'issue' && parsed.ok === false) {
+      return result('issue', 'usage-validation-issue', cleanupWarning);
+    }
+    return result('issue', 'usage-validation-output-invalid', cleanupWarning);
+  } catch (error) {
+    const timedOut = error?.code === 'ETIMEDOUT' || error?.killed === true || error?.signal === 'SIGTERM';
+    return result('issue', timedOut ? 'usage-validation-timeout' : 'usage-validation-issue');
+  }
+}
+
+export const __test = Object.freeze({
+  parseSingleJson,
+  parseEnrollmentEvent,
+  validateSelfTestOutput,
+  isExactOfficialApiRoot,
+  invokeValidationProcess,
+  validatePowerShell,
+  windowsPowerShellEnvironment,
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@rover-studio/answer-me",
+  "version": "0.1.0-rc.1",
+  "description": "Deterministic AnswerMe Toolkit installer for Codex on Windows x64",
+  "type": "module",
+  "bin": {
+    "answerme-toolkit": "bin/answerme-toolkit.mjs"
+  },
+  "engines": {
+    "node": ">=20",
+    "npm": ">=7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}