genesis-compiler 1.0.0 → 1.2.0

package/src/index/stack-launch.js

@@ -0,0 +1,428 @@
+import { GenesisError } from './errors.js';
+import {
+  isCanonicalProjectWorkdir,
+  isSafeProcessExecutable,
+  parseBacktickedArguments,
+} from './stack-process.js';
+
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const PLACEHOLDER = /\{([a-z][a-z0-9-]*)\}/gu;
+const PREVIEW_IDENTITY_COMMAND_PATH = /^\.vibe64\/bin\/[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const PREVIEW_IDENTITY_ENVIRONMENT_NAME = /^[A-Z_][A-Z0-9_]*$/u;
+const PREVIEW_IDENTITY_PROTOCOL = 'vibe64.preview-identity.command.v1';
+const PREVIEW_IDENTITY_RESERVED_ENVIRONMENT_NAMES = new Set([
+  'HOME',
+  'LOGNAME',
+  'NODE_OPTIONS',
+  'PATH',
+  'TMPDIR',
+  'USER',
+  'VIBE64_PREVIEW_IDENTITY_ENABLED',
+  'VIBE64_PREVIEW_IDENTITY_SECRET',
+]);
+const PREVIEW_IDENTITY_TYPES = new Set(['email', 'login', 'user-id']);
+const PREVIEW_FIELDS = [
+  ['- Command: ', 'command', 'Command'],
+  ['- Protocol: ', 'protocol', 'Protocol'],
+  ['- Identity types: ', 'identityTypes', 'Identity types'],
+  ['- Enabled environment: ', 'enabledEnvironment', 'Enabled environment'],
+  ['- Secret environment: ', 'secretEnvironment', 'Secret environment'],
+  ['- Runtimes: ', 'runtimes', 'Runtimes'],
+  ['- Timeout ms: ', 'timeoutMs', 'Timeout ms'],
+];
+const TARGET_HEADING = /^### Target `([^`\r\n]+)`:[ \t]+(.+)$/u;
+
+function invalid(launchPath, message, line, details = {}) {
+  throw new GenesisError('STACK_LAUNCH_INVALID', message, {
+    path: launchPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+function text(value, launchPath, label, line) {
+  if (typeof value !== 'string' || !value.trim() || /[\0\r\n]/u.test(value)) {
+    invalid(launchPath, `${label} must be one non-empty line.`, line);
+  }
+  return value.trim();
+}
+
+function id(value, launchPath, label, line) {
+  const normalized = text(value, launchPath, label, line);
+  if (!ID_PATTERN.test(normalized)) {
+    invalid(launchPath, `${label} must use lowercase letters, digits, and single hyphens.`, line);
+  }
+  return normalized;
+}
+
+function tokenValues(source, prefix, launchPath, label, line) {
+  const values = parseBacktickedArguments(source.slice(prefix.length));
+  if (!values) {
+    invalid(launchPath, `${label} must contain separate non-empty backticked values.`, line);
+  }
+  return values;
+}
+
+function oneToken(source, prefix, launchPath, label, line) {
+  const values = tokenValues(source, prefix, launchPath, label, line);
+  if (values.length !== 1) invalid(launchPath, `${label} accepts exactly one value.`, line);
+  return values[0];
+}
+
+function runtimeRequirements(values, launchPath, label, line, { deduplicate = false } = {}) {
+  const requirements = values.map((entry) => id(entry, launchPath, label, line));
+  if (!deduplicate && new Set(requirements).size !== requirements.length) {
+    invalid(launchPath, `${label} contains a duplicate technology id.`, line);
+  }
+  return deduplicate ? [...new Set(requirements)] : requirements;
+}
+
+function normalizeLaunchArgv(values, launchPath, line) {
+  if (!values || values.some((entry) => entry.includes('\0'))) {
+    invalid(
+      launchPath,
+      'Every launch command and argument must be one separate non-empty backticked value.',
+      line,
+    );
+  }
+  for (const entry of values) {
+    if ([...entry.matchAll(PLACEHOLDER)].some((match) => !['host', 'port'].includes(match[1]))) {
+      invalid(launchPath, 'Launch argv supports only {host} and {port} placeholders.', line);
+    }
+  }
+  if (!isSafeProcessExecutable(values[0])) {
+    invalid(
+      launchPath,
+      'A launch executable must be a PATH name or project-relative path without traversal.',
+      line,
+    );
+  }
+  return values;
+}
+
+function launchArgv(source, launchPath, line) {
+  return normalizeLaunchArgv(parseBacktickedArguments(source), launchPath, line);
+}
+
+function setOnce(draft, field, value, launchPath, line, label) {
+  if (draft.seen.has(field)) invalid(launchPath, `Duplicate ${label}.`, line);
+  draft.seen.add(field);
+  draft[field] = value;
+}
+
+function targetDraft(match, launchPath, line) {
+  return {
+    id: id(match[1], launchPath, 'Launch target id', line),
+    label: text(match[2], launchPath, 'Launch target label', line),
+    default: false,
+    workdir: '.',
+    preferredPort: null,
+    urlPath: '/',
+    runtimeRequirements: [],
+    steps: [],
+    previewIdentity: null,
+    seen: new Set(),
+    line,
+  };
+}
+
+function parsePreferredPort(value, launchPath, line) {
+  if (!/^[0-9]+$/u.test(value)) {
+    invalid(launchPath, 'Launch target preferred port must be an integer from 1024 through 65535.', line);
+  }
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 1024 || port > 65_535) {
+    invalid(launchPath, 'Launch target preferred port must be an integer from 1024 through 65535.', line);
+  }
+  return port;
+}
+
+function parseUrlPath(value, launchPath, line) {
+  const normalized = text(value, launchPath, 'Launch target URL path', line);
+  if (!normalized.startsWith('/') || normalized.startsWith('//') || /[\\?#]/u.test(normalized)) {
+    invalid(
+      launchPath,
+      'Launch target URL path must be an application path beginning with one slash.',
+      line,
+    );
+  }
+  return normalized;
+}
+
+function parseTargetLine(draft, source, launchPath, line) {
+  if (source === '- Default.') {
+    setOnce(draft, 'default', true, launchPath, line, 'Launch target Default entry');
+    return;
+  }
+  if (source.startsWith('- Workdir: ')) {
+    const value = oneToken(source, '- Workdir: ', launchPath, 'Launch target Workdir', line);
+    if (!isCanonicalProjectWorkdir(value)) {
+      invalid(launchPath, 'Launch target workdir must be a canonical project-relative directory.', line);
+    }
+    setOnce(draft, 'workdir', value, launchPath, line, 'Launch target Workdir entry');
+    return;
+  }
+  if (source.startsWith('- Preferred port: ')) {
+    const value = oneToken(
+      source,
+      '- Preferred port: ',
+      launchPath,
+      'Launch target Preferred port',
+      line,
+    );
+    setOnce(
+      draft,
+      'preferredPort',
+      parsePreferredPort(value, launchPath, line),
+      launchPath,
+      line,
+      'Launch target Preferred port entry',
+    );
+    return;
+  }
+  if (source.startsWith('- URL path: ')) {
+    const value = oneToken(source, '- URL path: ', launchPath, 'Launch target URL path', line);
+    setOnce(
+      draft,
+      'urlPath',
+      parseUrlPath(value, launchPath, line),
+      launchPath,
+      line,
+      'Launch target URL path entry',
+    );
+    return;
+  }
+  if (source.startsWith('- Runtimes: ')) {
+    const values = tokenValues(source, '- Runtimes: ', launchPath, 'Launch target Runtimes', line);
+    setOnce(
+      draft,
+      'runtimeRequirements',
+      runtimeRequirements(values, launchPath, 'Launch target Runtimes', line),
+      launchPath,
+      line,
+      'Launch target Runtimes entry',
+    );
+    return;
+  }
+  const step = source.match(/^- (Prepare|Serve) `([^`\r\n]+)`:[ \t]+(.+)$/u);
+  if (step) {
+    draft.steps.push({
+      label: text(step[2], launchPath, 'Launch step label', line),
+      argv: launchArgv(step[3], launchPath, line),
+      role: step[1] === 'Serve' ? 'server' : 'prepare',
+    });
+    return;
+  }
+  invalid(launchPath, `Unknown Launch target entry: ${source}.`, line);
+}
+
+function previewIdentityEnvironmentName(value, launchPath, label, line) {
+  if (value === undefined) return '';
+  const name = text(value, launchPath, `Preview identity ${label} environment name`, line);
+  if (
+    !PREVIEW_IDENTITY_ENVIRONMENT_NAME.test(name)
+    || PREVIEW_IDENTITY_RESERVED_ENVIRONMENT_NAMES.has(name)
+    || name.startsWith('XDG_')
+  ) {
+    invalid(launchPath, `Preview identity ${label} environment name is invalid.`, line);
+  }
+  return name;
+}
+
+function previewDraft(line) {
+  return { seen: new Set(), line };
+}
+
+function parsePreviewLine(draft, source, launchPath, line) {
+  const field = PREVIEW_FIELDS.find(([prefix]) => source.startsWith(prefix));
+  if (!field) invalid(launchPath, `Unknown Preview identity entry: ${source}.`, line);
+  const [prefix, key, label] = field;
+  const values = tokenValues(source, prefix, launchPath, `Preview identity ${label}`, line);
+  if (!['command', 'identityTypes', 'runtimes'].includes(key) && values.length !== 1) {
+    invalid(launchPath, `Preview identity ${label} accepts exactly one value.`, line);
+  }
+  setOnce(draft, key, values, launchPath, line, `Preview identity ${label} entry`);
+}
+
+function normalizePreviewIdentity(draft, launchPath, targetId) {
+  if (!draft.command) {
+    invalid(launchPath, `Launch target ${targetId} Preview identity needs Command.`, draft.line);
+  }
+  if (!draft.protocol) {
+    invalid(launchPath, `Launch target ${targetId} Preview identity needs Protocol.`, draft.line);
+  }
+  if (!draft.identityTypes) {
+    invalid(launchPath, `Launch target ${targetId} Preview identity needs Identity types.`, draft.line);
+  }
+  const command = normalizeLaunchArgv(draft.command, launchPath, draft.line);
+  if (
+    command.length > 64
+    || command.some((entry) => !entry.trim() || entry.length > 4096 || /[\r\n]/u.test(entry))
+    || !PREVIEW_IDENTITY_COMMAND_PATH.test(command[0])
+    || command.some((entry) => /\{(?:host|port)\}/u.test(entry))
+  ) {
+    invalid(
+      launchPath,
+      'Preview identity command must use an app-owned executable under .vibe64/bin and contain at most 64 literal arguments.',
+      draft.line,
+    );
+  }
+  const protocol = text(draft.protocol[0], launchPath, 'Preview identity protocol', draft.line);
+  if (protocol !== PREVIEW_IDENTITY_PROTOCOL) {
+    invalid(launchPath, `Preview identity protocol must be ${PREVIEW_IDENTITY_PROTOCOL}.`, draft.line);
+  }
+  const identityTypes = [...new Set(draft.identityTypes.map((entry) => {
+    const type = text(entry, launchPath, 'Preview identity type', draft.line);
+    if (!PREVIEW_IDENTITY_TYPES.has(type)) {
+      invalid(launchPath, `Unsupported preview identity type: ${type}.`, draft.line);
+    }
+    return type;
+  }))];
+  const environment = {
+    enabled: previewIdentityEnvironmentName(
+      draft.enabledEnvironment?.[0],
+      launchPath,
+      'enabled',
+      draft.line,
+    ),
+    secret: previewIdentityEnvironmentName(
+      draft.secretEnvironment?.[0],
+      launchPath,
+      'secret',
+      draft.line,
+    ),
+  };
+  if (environment.enabled && environment.enabled === environment.secret) {
+    invalid(
+      launchPath,
+      'Preview identity enabled and secret environment names must differ.',
+      draft.line,
+    );
+  }
+  let timeoutMs = 10_000;
+  if (draft.timeoutMs) {
+    const value = draft.timeoutMs[0];
+    if (!/^[0-9]+$/u.test(value)) {
+      invalid(launchPath, 'Preview identity Timeout ms must be an integer from 1 through 30000.', draft.line);
+    }
+    timeoutMs = Number(value);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000) {
+      invalid(launchPath, 'Preview identity Timeout ms must be an integer from 1 through 30000.', draft.line);
+    }
+  }
+  return {
+    command,
+    environment,
+    identityTypes,
+    protocol,
+    runtimes: draft.runtimes
+      ? runtimeRequirements(
+        draft.runtimes,
+        launchPath,
+        'Preview identity Runtimes',
+        draft.line,
+        { deduplicate: true },
+      )
+      : [],
+    timeoutMs,
+  };
+}
+
+function normalizeTarget(draft, launchPath) {
+  if (draft.steps.length === 0) {
+    invalid(launchPath, `Launch target ${draft.id} needs at least one step.`, draft.line);
+  }
+  const serverSteps = draft.steps.filter(({ role }) => role === 'server');
+  if (serverSteps.length !== 1 || draft.steps.at(-1).role !== 'server') {
+    invalid(launchPath, `Launch target ${draft.id} needs exactly one final Serve step.`, draft.line);
+  }
+  return {
+    id: draft.id,
+    label: draft.label,
+    default: draft.default,
+    workdir: draft.workdir,
+    preferredPort: draft.preferredPort,
+    urlPath: draft.urlPath,
+    runtimeRequirements: draft.runtimeRequirements,
+    steps: draft.steps,
+    ...(draft.previewIdentity
+      ? { previewIdentity: normalizePreviewIdentity(draft.previewIdentity, launchPath, draft.id) }
+      : {}),
+  };
+}
+
+export function parseStackLaunchLines(lines, {
+  path: launchPath = 'stack launch',
+} = {}) {
+  if (lines === undefined) return null;
+  const entries = lines.map((line) => line.trim()).filter(Boolean);
+  if (entries.length === 1 && entries[0] === '- Nothing.') return { version: 1, targets: [] };
+
+  const targets = [];
+  let target = null;
+  let inPreviewIdentity = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const line = index + 1;
+    const heading = source.match(TARGET_HEADING);
+    if (heading) {
+      if (target) targets.push(normalizeTarget(target, launchPath));
+      target = targetDraft(heading, launchPath, line);
+      inPreviewIdentity = false;
+      continue;
+    }
+    if (source === '#### Preview identity') {
+      if (!target || target.previewIdentity) {
+        invalid(launchPath, 'Preview identity must appear once below a Launch target.', line);
+      }
+      target.previewIdentity = previewDraft(line);
+      inPreviewIdentity = true;
+      continue;
+    }
+    if (!target) {
+      invalid(launchPath, '## Launch must begin with a Target heading.', line);
+    }
+    if (inPreviewIdentity) parsePreviewLine(target.previewIdentity, source, launchPath, line);
+    else parseTargetLine(target, source, launchPath, line);
+  }
+  if (target) targets.push(normalizeTarget(target, launchPath));
+  if (targets.length === 0) {
+    invalid(launchPath, '## Launch needs at least one Target or exactly `- Nothing.`.');
+  }
+  const ids = targets.map(({ id: targetId }) => targetId);
+  if (new Set(ids).size !== ids.length) invalid(launchPath, 'Launch contains a duplicate target id.');
+  if (targets.filter(({ default: isDefault }) => isDefault).length > 1) {
+    invalid(launchPath, 'Launch may declare at most one default target.');
+  }
+  return { version: 1, targets };
+}
+
+export function composeStackLaunchTargets(components, projectLaunch) {
+  if (projectLaunch) {
+    return projectLaunch.targets.map((target) => ({ ...target, source: 'project' }));
+  }
+  const targets = components.flatMap((component) => (
+    (component.launchTargets || []).map((target) => ({
+      ...target,
+      source: `component:${component.id}`,
+    }))
+  ));
+  const sourcesById = new Map();
+  for (const target of targets) {
+    const previous = sourcesById.get(target.id);
+    if (previous) {
+      invalid(
+        'selected Stack components',
+        `Selected Stack components provide duplicate launch target ${target.id}.`,
+        undefined,
+        { sources: [previous, target.source], target: target.id },
+      );
+    }
+    sourcesById.set(target.id, target.source);
+  }
+  if (targets.filter((target) => target.default).length > 1) {
+    invalid('selected Stack components', 'Selected Stack components provide more than one default launch target.');
+  }
+  return targets;
+}