genesis-compiler 1.2.28 → 1.3.0

package/src/index/collaboration.js

@@ -0,0 +1,371 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { GENESIS_CONTRACTS } from './contracts.js';
+import { GenesisError } from './errors.js';
+import { gitContext } from './git.js';
+import { COLLABORATION_PATH } from './paths.js';
+import { normalizeSource, writeFileAtomic } from './utils.js';
+
+const MAX_REQUIREMENTS_BYTES = 64 * 1024;
+
+const DIMENSIONS = {
+  tone: {
+    encouraging: {
+      name: 'Encouraging',
+      guidance: 'Be warm, encouraging, and enthusiastic without empty praise.',
+    },
+    playful: {
+      name: 'Playful and cheeky',
+      guidance: 'Be warm, cheeky, and lightly funny when the situation allows it.',
+    },
+    direct: {
+      name: 'Direct',
+      guidance: 'Be direct, calm, and matter-of-fact.',
+    },
+    military: {
+      name: 'Crisp and military',
+      guidance: 'Use crisp, disciplined, command-style language while remaining respectful.',
+    },
+  },
+  responseLength: {
+    very_short: {
+      name: 'Very short',
+      guidance: 'Use very short sentences and the fewest words that still answer clearly.',
+    },
+    concise: {
+      name: 'Concise',
+      guidance: 'Keep responses concise while including the information needed to act.',
+    },
+    balanced: {
+      name: 'Balanced',
+      guidance: 'Use a balanced amount of detail.',
+    },
+    detailed: {
+      name: 'Detailed',
+      guidance: 'Give thorough, structured explanations when they help.',
+    },
+  },
+  experience: {
+    beginner: {
+      name: 'Beginner',
+      guidance: 'Assume the user is new to software development; explain necessary terms in plain language.',
+    },
+    comfortable: {
+      name: 'Comfortable',
+      guidance: 'Assume the user is comfortable with ordinary software concepts; explain only unfamiliar or consequential details.',
+    },
+    expert: {
+      name: 'Expert',
+      guidance: 'Assume the user is an expert; use precise technical language and omit introductory explanations.',
+    },
+  },
+  explanationStyle: {
+    conclusions: {
+      name: 'Conclusions only',
+      guidance: 'Lead with conclusions and omit rationale unless the user asks for it or it is needed for safety.',
+    },
+    concise: {
+      name: 'Concise rationale',
+      guidance: 'Give a brief, useful rationale for decisions and recommendations.',
+    },
+    teaching: {
+      name: 'Teaching detail',
+      guidance: 'Explain the practical reasoning behind decisions in a teaching-oriented way.',
+    },
+  },
+};
+
+const SECTION_FIELDS = Object.freeze({
+  'Tone': 'tone',
+  'Response length': 'responseLength',
+  'Assumed experience': 'experience',
+  'Explanation style': 'explanationStyle',
+});
+
+export const DEFAULT_COLLABORATION = Object.freeze({
+  tone: 'encouraging',
+  responseLength: 'concise',
+  experience: 'comfortable',
+  explanationStyle: 'concise',
+  requirements: '',
+});
+
+export const COLLABORATION_SKELETON_SOURCE = `# Collaboration approach
+
+## Tone
+
+- \`${DEFAULT_COLLABORATION.tone}\`
+
+## Response length
+
+- \`${DEFAULT_COLLABORATION.responseLength}\`
+
+## Assumed experience
+
+- \`${DEFAULT_COLLABORATION.experience}\`
+
+## Explanation style
+
+- \`${DEFAULT_COLLABORATION.explanationStyle}\`
+
+## Project requirements
+
+- Nothing.
+`;
+
+function sections(source) {
+  const normalized = normalizeSource(source);
+  const title = '# Collaboration approach';
+  if (normalized.split('\n').filter((line) => line.trim() === title).length !== 1) {
+    throw new GenesisError(
+      'COLLABORATION_INVALID',
+      `${COLLABORATION_PATH} needs exactly one \`${title}\` title.`,
+      { path: COLLABORATION_PATH },
+    );
+  }
+  const result = new Map();
+  let current = null;
+  for (const line of normalized.split('\n')) {
+    const heading = line.match(/^##\s+(.+?)\s*$/u);
+    if (heading) {
+      if (result.has(heading[1])) {
+        throw new GenesisError(
+          'COLLABORATION_INVALID',
+          `Duplicate collaboration section: ${heading[1]}.`,
+          { path: COLLABORATION_PATH },
+        );
+      }
+      current = [];
+      result.set(heading[1], current);
+    } else if (current) {
+      current.push(line);
+    } else if (line.trim() && line.trim() !== title) {
+      throw new GenesisError(
+        'COLLABORATION_INVALID',
+        `${COLLABORATION_PATH} contains content outside a collaboration section.`,
+        { path: COLLABORATION_PATH },
+      );
+    }
+  }
+  return { normalized, sections: result };
+}
+
+function sectionText(all, name) {
+  return (all.get(name) || []).join('\n').trim();
+}
+
+function dimensionValue(all, sectionName, field) {
+  const lines = (all.get(sectionName) || []).filter((line) => line.trim());
+  const match = lines.length === 1 ? lines[0].trim().match(/^- `([^`]+)`$/u) : null;
+  const value = match?.[1] || '';
+  if (!Object.hasOwn(DIMENSIONS[field], value)) {
+    throw new GenesisError(
+      'COLLABORATION_INVALID',
+      `${sectionName} must be exactly one backticked choice: ${Object.keys(DIMENSIONS[field]).join(', ')}.`,
+      { path: COLLABORATION_PATH },
+    );
+  }
+  return value;
+}
+
+function normalizedRequirements(value) {
+  const requirements = normalizeSource(value).trim();
+  if (!requirements || requirements === '- Nothing.') return '';
+  if (Buffer.byteLength(requirements, 'utf8') > MAX_REQUIREMENTS_BYTES) {
+    throw new GenesisError(
+      'COLLABORATION_INVALID',
+      'Project collaboration requirements exceed 64 KiB.',
+      { path: COLLABORATION_PATH },
+    );
+  }
+  if (/^#{1,6}(?:\s|$)/mu.test(requirements)) {
+    throw new GenesisError(
+      'COLLABORATION_INVALID',
+      'Project collaboration requirements cannot contain Markdown headings.',
+      { path: COLLABORATION_PATH },
+    );
+  }
+  return requirements;
+}
+
+function collaborationCatalog() {
+  return Object.fromEntries(Object.entries(DIMENSIONS).map(([field, choices]) => [
+    field,
+    Object.entries(choices).map(([id, choice]) => ({ id, ...choice })),
+  ]));
+}
+
+function collaborationGuidance(value) {
+  return [
+    '## Tone',
+    '',
+    DIMENSIONS.tone[value.tone].guidance,
+    '',
+    '## Response length',
+    '',
+    DIMENSIONS.responseLength[value.responseLength].guidance,
+    '',
+    '## Assumed experience',
+    '',
+    DIMENSIONS.experience[value.experience].guidance,
+    '',
+    '## Explanation style',
+    '',
+    DIMENSIONS.explanationStyle[value.explanationStyle].guidance,
+    ...(value.requirements ? [
+      '',
+      '## Project requirements',
+      '',
+      'Additional project-specific collaboration requirements:',
+      value.requirements,
+    ] : []),
+  ].join('\n');
+}
+
+export function parseCollaborationSource(source) {
+  const parsed = sections(source);
+  const expected = new Set([...Object.keys(SECTION_FIELDS), 'Project requirements']);
+  const unknown = [...parsed.sections.keys()].filter((name) => !expected.has(name));
+  const missing = [...expected].filter((name) => !parsed.sections.has(name));
+  if (unknown.length > 0 || missing.length > 0) {
+    throw new GenesisError(
+      'COLLABORATION_INVALID',
+      `${COLLABORATION_PATH} needs only Tone, Response length, Assumed experience, Explanation style, and Project requirements sections.`,
+      { path: COLLABORATION_PATH },
+    );
+  }
+  const values = Object.fromEntries(Object.entries(SECTION_FIELDS).map(([sectionName, field]) => [
+    field,
+    dimensionValue(parsed.sections, sectionName, field),
+  ]));
+  const requirementsSource = sectionText(parsed.sections, 'Project requirements');
+  if (!requirementsSource) {
+    throw new GenesisError(
+      'COLLABORATION_INVALID',
+      'Project requirements must contain requirements or `- Nothing.`.',
+      { path: COLLABORATION_PATH },
+    );
+  }
+  return {
+    path: COLLABORATION_PATH,
+    ...values,
+    requirements: normalizedRequirements(requirementsSource),
+    source: parsed.normalized,
+  };
+}
+
+function collaborationResult(parsed, status = 'configured') {
+  return {
+    contract: GENESIS_CONTRACTS.collaboration,
+    status,
+    ...parsed,
+    choices: collaborationCatalog(),
+    guidance: collaborationGuidance(parsed),
+  };
+}
+
+export function defaultCollaboration() {
+  return collaborationResult(
+    parseCollaborationSource(COLLABORATION_SKELETON_SOURCE),
+    'defaulted',
+  );
+}
+
+function renderCollaboration(value) {
+  return [
+    '# Collaboration approach',
+    '',
+    '## Tone',
+    '',
+    `- \`${value.tone}\``,
+    '',
+    '## Response length',
+    '',
+    `- \`${value.responseLength}\``,
+    '',
+    '## Assumed experience',
+    '',
+    `- \`${value.experience}\``,
+    '',
+    '## Explanation style',
+    '',
+    `- \`${value.explanationStyle}\``,
+    '',
+    '## Project requirements',
+    '',
+    value.requirements || '- Nothing.',
+    '',
+  ].join('\n');
+}
+
+export async function readCollaboration(projectRoot) {
+  let parsed;
+  try {
+    parsed = parseCollaborationSource(
+      await readFile(path.join(projectRoot, COLLABORATION_PATH), 'utf8'),
+    );
+  } catch (error) {
+    if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+    throw new GenesisError(
+      'COLLABORATION_REQUIRED',
+      `${COLLABORATION_PATH} is required for the current Genesis project format.`,
+      { path: COLLABORATION_PATH },
+    );
+  }
+  return collaborationResult(parsed);
+}
+
+export async function materializeDefaultCollaboration({ projectRoot } = {}) {
+  const location = path.join(projectRoot, COLLABORATION_PATH);
+  try {
+    await readCollaboration(projectRoot);
+    return { changedFiles: [] };
+  } catch (error) {
+    if (error?.code !== 'COLLABORATION_REQUIRED') throw error;
+  }
+  await writeFileAtomic(location, COLLABORATION_SKELETON_SOURCE);
+  return { changedFiles: [COLLABORATION_PATH] };
+}
+
+export async function inspectProjectCollaboration({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  return readCollaboration(root);
+}
+
+export async function setProjectCollaboration({
+  experience,
+  explanationStyle,
+  projectRoot,
+  requirements,
+  responseLength,
+  tone,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const current = await readCollaboration(root);
+  const next = parseCollaborationSource(renderCollaboration({
+    tone: tone ?? current.tone,
+    responseLength: responseLength ?? current.responseLength,
+    experience: experience ?? current.experience,
+    explanationStyle: explanationStyle ?? current.explanationStyle,
+    requirements: requirements ?? current.requirements,
+  }));
+  const rendered = renderCollaboration(next);
+  const changed = current.source !== rendered;
+  if (changed) await writeFileAtomic(path.join(root, COLLABORATION_PATH), rendered);
+  return {
+    contract: GENESIS_CONTRACTS.collaboration,
+    status: changed ? 'updated' : 'unchanged',
+    summary: changed
+      ? 'Updated the project collaboration approach.'
+      : 'The project collaboration approach is already selected.',
+    tone: next.tone,
+    responseLength: next.responseLength,
+    experience: next.experience,
+    explanationStyle: next.explanationStyle,
+    requirements: next.requirements,
+    choices: collaborationCatalog(),
+    guidance: collaborationGuidance(next),
+    changedFiles: changed ? [COLLABORATION_PATH] : [],
+  };
+}

package/src/index/context.js

@@ -31,18 +31,13 @@ function stackSummary(stack) {
 }
 
 function stackGuidance(stack) {
-  const pieces = stack.components.filter(({ guidance }) => guidance);
-  if (pieces.length === 0) return [];
+  if (!stack.guidance) return [];
   return [
     '',
     '## Selected Stack guidance',
     '',
-    ...pieces.flatMap(({ id, guidance }) => [
-      `### ${id}`,
-      '',
-      guidance,
-      '',
-    ]),
+    stack.guidance,
+    '',
   ];
 }
 

package/src/index/contracts.js

@@ -1,7 +1,10 @@
 export const GENESIS_CONTRACTS = Object.freeze({
+  collaboration: 'genesis.collaboration.v1',
   derivedArtifacts: 'genesis.derived-artifacts.v1',
   engineering: 'genesis.engineering.v1',
   environment: 'genesis.environment.v2',
+  sessionContext: 'genesis.session-context.v1',
   stackSection: 'genesis.stack-section.v1',
+  turnContext: 'genesis.turn-context.v1',
   verification: 'genesis.verification.v1',
 });

package/src/index/host-context-resolver.js

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+
+import { GenesisError } from './errors.js';
+
+export const HOST_CONTEXT_RESOLVER_ENV = 'GENESIS_HOST_CONTEXT_RESOLVER';
+export const HOST_CONTEXT_RESOLVER_DATA_ENV = 'GENESIS_HOST_CONTEXT_RESOLVER_DATA';
+export const HOST_CONTEXT_INPUT_ENV = 'GENESIS_HOST_CONTEXT_INPUT';
+export const SESSION_CONTEXT_INSTALLED_ENV = 'GENESIS_SESSION_CONTEXT_INSTALLED';
+
+const RESOLVER_OUTPUT_MAX_BYTES = 64 * 1024;
+const RESOLVER_TIMEOUT_MS = 5_000;
+
+function resolverError(message) {
+  return new GenesisError('HOST_CONTEXT_RESOLVER_FAILED', message);
+}
+
+function configuredResolver(environment) {
+  const command = String(environment[HOST_CONTEXT_RESOLVER_ENV] || '').trim();
+  return command || null;
+}
+
+function resolverData(environment) {
+  const source = String(environment[HOST_CONTEXT_RESOLVER_DATA_ENV] || '').trim();
+  if (!source) return null;
+  try {
+    return JSON.parse(source);
+  } catch {
+    throw resolverError(`${HOST_CONTEXT_RESOLVER_DATA_ENV} must contain JSON.`);
+  }
+}
+
+function runResolver({ command, input, projectRoot, environment }) {
+  const source = `${JSON.stringify(input)}\n`;
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, [], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      env: environment,
+      maxBuffer: RESOLVER_OUTPUT_MAX_BYTES,
+      timeout: RESOLVER_TIMEOUT_MS,
+      windowsHide: true,
+    }, (error, stdout) => {
+      if (error) {
+        reject(resolverError(`The configured host context resolver failed: ${error.message}`));
+        return;
+      }
+      resolve(stdout);
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(source);
+  });
+}
+
+export async function resolveConfiguredHostContext({
+  environment = process.env,
+  projectRoot,
+  providerSessionId = null,
+  scope = 'session',
+} = {}) {
+  const command = configuredResolver(environment);
+  if (!command) return null;
+  const output = await runResolver({
+    command,
+    environment,
+    projectRoot,
+    input: {
+      scope,
+      providerSessionId: providerSessionId || null,
+      data: resolverData(environment),
+    },
+  });
+  return output;
+}

package/src/index/init.js

@@ -4,11 +4,13 @@ import path from 'node:path';
 import { syncProjectSkills } from './agent-skills.js';
 import { BLUEPRINT_SKELETON_SOURCE } from './blueprint.js';
 import { installCodexHooks } from './codex-hooks.js';
+import { COLLABORATION_SKELETON_SOURCE } from './collaboration.js';
 import { ENGINEERING_SKELETON_SOURCE } from './engineering.js';
 import { gitContext } from './git.js';
 import { installOpenCodePlugin } from './opencode-plugin.js';
 import {
   BLUEPRINT_PATH,
+  COLLABORATION_PATH,
   ENGINEERING_PATH,
   PROGRAM_ROOT,
   PROJECT_VERSION_PATH,
@@ -39,6 +41,7 @@ export async function initializeProject({ projectRoot, stackPackages = [] } = {}
   requireCurrentProjectFormat(projectFormat, { allowUninitialized: true });
   const created = (await Promise.all([
     createIfMissing(root, BLUEPRINT_PATH, BLUEPRINT_SKELETON_SOURCE),
+    createIfMissing(root, COLLABORATION_PATH, COLLABORATION_SKELETON_SOURCE),
     createIfMissing(root, ENGINEERING_PATH, ENGINEERING_SKELETON_SOURCE),
     createIfMissing(root, STACK_PATH, EMPTY_STACK_SOURCE),
   ])).filter(Boolean);
@@ -73,6 +76,7 @@ export async function initializeProject({ projectRoot, stackPackages = [] } = {}
       'OpenCode loads the project guidance plugin automatically.',
       'Genesis workflow skills are available in .agents/skills/.',
       'Describe product intent in genesis/blueprint.md.',
+      'Choose the project collaboration approach with genesis collaboration set.',
       'Choose the project engineering approach with genesis engineering set <profile>.',
       'Stack components are optional; add them with genesis stack add <piece...>.',
     ].join(' '),

package/src/index/migration.js

@@ -1,4 +1,5 @@
 import { readBlueprint } from './blueprint.js';
+import { materializeDefaultCollaboration } from './collaboration.js';
 import { readEngineering } from './engineering.js';
 import { asDiagnostic, GenesisError } from './errors.js';
 import { gitContext } from './git.js';
@@ -43,6 +44,7 @@ async function materializeProjectContracts({ projectRoot, stackPackages }) {
 const MIGRATIONS = new Map([
   [0, validateLegacyProject],
   [1, materializeProjectContracts],
+  [2, materializeDefaultCollaboration],
 ]);
 
 export async function migrateProject({ projectRoot, stackPackages = [] } = {}) {

package/src/index/opencode-plugin.js

@@ -2,9 +2,9 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { gitContext } from './git.js';
+import { OPENCODE_PLUGIN_PATH } from './paths.js';
 import { writeFileAtomic } from './utils.js';
 
-const OPENCODE_PLUGIN_PATH = '.opencode/plugins/genesis-project-guidance.js';
 const OPENCODE_PLUGIN_SOURCE = new URL('../../plugins/opencode/project-guidance.js', import.meta.url);
 
 async function existingSource(location) {

package/src/index/paths.js

@@ -1,9 +1,11 @@
 export const BLUEPRINT_PATH = 'genesis/blueprint.md';
+export const COLLABORATION_PATH = 'genesis/collaboration.md';
 export const ENGINEERING_PATH = 'genesis/engineering.md';
 export const STACK_PATH = 'genesis/stack.md';
 export const PROGRAM_ROOT = 'genesis/program';
 export const PROJECT_VERSION_PATH = 'genesis/version';
 export const VERIFICATION_PATH = '.genesis/verification.json';
+export const OPENCODE_PLUGIN_PATH = '.opencode/plugins/genesis-project-guidance.js';
 
 export function isProjectContentPath(file) {
   const first = file.split('/')[0];

package/src/index/project-files.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 
+import { isProjectContentPath, OPENCODE_PLUGIN_PATH } from './paths.js';
 import { runGit } from './process.js';
 import { pathState } from './utils.js';
 
@@ -22,3 +23,14 @@ export async function gitVisibleFileStates(projectRoot, { includePath = () => tr
   }
   return states;
 }
+
+/** Classifies opening behavior from cheap Git-visible paths and selected Stack state. */
+export async function classifyProjectKind({ projectRoot, stackComponents = [] } = {}) {
+  if (stackComponents.length > 0) return 'existing';
+  const existing = (await visiblePaths(projectRoot)).some((file) => (
+    isProjectContentPath(file)
+    && file !== OPENCODE_PLUGIN_PATH
+    && !file.split('/').includes('node_modules')
+  ));
+  return existing ? 'existing' : 'new';
+}

package/src/index/project-format.js

@@ -5,6 +5,7 @@ import { asDiagnostic, GenesisError } from './errors.js';
 import { gitContext } from './git.js';
 import {
   BLUEPRINT_PATH,
+  COLLABORATION_PATH,
   ENGINEERING_PATH,
   PROGRAM_ROOT,
   PROJECT_VERSION_PATH,
@@ -12,7 +13,7 @@ import {
 } from './paths.js';
 import { normalizeSource, pathState, writeFileAtomic } from './utils.js';
 
-export const CURRENT_PROJECT_FORMAT_VERSION = 2;
+export const CURRENT_PROJECT_FORMAT_VERSION = 3;
 export const CURRENT_PROJECT_FORMAT_SOURCE = `${CURRENT_PROJECT_FORMAT_VERSION}\n`;
 
 const VERSION_PATTERN = /^(0|[1-9][0-9]*)\n?$/u;
@@ -45,6 +46,7 @@ export function parseProjectFormatVersion(source) {
 async function hasGenesisSource(projectRoot) {
   const states = await Promise.all([
     BLUEPRINT_PATH,
+    COLLABORATION_PATH,
     ENGINEERING_PATH,
     STACK_PATH,
     PROGRAM_ROOT,