@urielsh/prodify 0.1.0

package/src/commands/setup-agent.ts

@@ -0,0 +1,28 @@
+import { setupAgentIntegration } from '../core/agent-setup.js';
+import { ProdifyError } from '../core/errors.js';
+import type { CommandContext } from '../types.js';
+
+function parseAgent(args: string[]): string {
+  const agent = args[0] ?? null;
+  if (!agent || args.length !== 1) {
+    throw new ProdifyError('setup-agent requires exactly one argument: <codex|claude|copilot|opencode>.', {
+      code: 'INVALID_AGENT'
+    });
+  }
+
+  return agent;
+}
+
+export async function runSetupAgentCommand(args: string[], context: CommandContext): Promise<number> {
+  const agent = parseAgent(args);
+  const result = await setupAgentIntegration(agent);
+
+  context.stdout.write('Prodify Agent Setup\n');
+  context.stdout.write(`Agent: ${agent}\n`);
+  context.stdout.write(`Status: ${result.alreadyConfigured ? 'already configured globally; refreshed' : 'configured globally'}\n`);
+  context.stdout.write(`Configured agents: ${result.configuredAgents.join(', ')}\n`);
+  context.stdout.write(`Registry: ${result.statePath}\n`);
+  context.stdout.write('Repo impact: none\n');
+  context.stdout.write('Next step: run `prodify init` in a repository, then open that agent and use `$prodify-init`.\n');
+  return 0;
+}

package/src/commands/status.ts

@@ -0,0 +1,34 @@
+import { resolveRepoRoot } from '../core/repo-root.js';
+import { inspectRepositoryStatus, renderStatusReport } from '../core/status.js';
+import { ProdifyError } from '../core/errors.js';
+import { getRuntimeProfile } from '../core/targets.js';
+import type { CommandContext } from '../types.js';
+
+function parseRequestedAgent(args: string[]): string | null {
+  const agentFlagIndex = args.indexOf('--agent');
+  if (agentFlagIndex === -1) {
+    return null;
+  }
+
+  const value = args[agentFlagIndex + 1] ?? null;
+  if (!value || !getRuntimeProfile(value)) {
+    throw new ProdifyError('status requires --agent <codex|claude|copilot|opencode> when an agent is specified.', {
+      code: 'INVALID_AGENT'
+    });
+  }
+
+  return value;
+}
+
+export async function runStatusCommand(args: string[], context: CommandContext): Promise<number> {
+  const repoRoot = await resolveRepoRoot({
+    cwd: context.cwd,
+    allowBootstrap: true
+  });
+  const report = await inspectRepositoryStatus(repoRoot, {
+    agent: parseRequestedAgent(args)
+  });
+
+  context.stdout.write(`${renderStatusReport(report)}\n`);
+  return report.ok ? 0 : 1;
+}

package/src/commands/update.ts

@@ -0,0 +1,23 @@
+import { resolveRepoRoot } from '../core/repo-root.js';
+import { updateProdifySetup } from '../core/upgrade.js';
+import type { CommandContext } from '../types.js';
+
+export async function runUpdateCommand(args: string[], context: CommandContext): Promise<number> {
+  void args;
+  const repoRoot = await resolveRepoRoot({
+    cwd: context.cwd
+  });
+  const summary = await updateProdifySetup(repoRoot);
+
+  context.stdout.write('Prodify Update\n');
+  context.stdout.write(`Version/schema: ${summary.versionStatus}\n`);
+  if (summary.schemaMigrationRequired) {
+    context.stdout.write('Schema migration: applied\n');
+  }
+
+  context.stdout.write(`Canonical assets: ${summary.writtenCanonicalCount} written, ${summary.preservedCanonicalCount} preserved\n`);
+  context.stdout.write(`Compiled contracts: ${summary.compiledContractCount}\n`);
+  context.stdout.write('Legacy compatibility adapters: not part of the default flow\n');
+
+  return 0;
+}

package/src/contracts/README.md

@@ -0,0 +1,10 @@
+# Contracts Subsystem
+
+This directory owns the contract pipeline end to end.
+
+- `parser.ts`: parses Markdown plus YAML frontmatter into a source document.
+- `source-schema.ts`: validates source-contract fields and normalizes them into the runtime shape.
+- `compiled-schema.ts`: validates checked-in compiled JSON before runtime uses it.
+- `compiler.ts`: compiles source contracts and writes runtime JSON contracts.
+- `freshness.ts`: computes whether compiled runtime contracts are fresh relative to source contracts.
+- `index.ts`: public entrypoint for the contract subsystem.

package/src/contracts/compiled-schema.ts

@@ -0,0 +1,42 @@
+import { ProdifyError } from '../core/errors.js';
+import { normalizeSourceContractDocument } from './source-schema.js';
+import type { CompiledStageContract } from '../types.js';
+
+function asString(value: unknown, fieldName: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new ProdifyError(`Compiled contract field "${fieldName}" must be a non-empty string.`, {
+      code: 'COMPILED_CONTRACT_INVALID'
+    });
+  }
+
+  return value.trim();
+}
+
+export function validateCompiledContractShape(contract: unknown): CompiledStageContract {
+  if (typeof contract !== 'object' || contract === null || Array.isArray(contract)) {
+    throw new ProdifyError('Compiled contract must be a JSON object.', {
+      code: 'COMPILED_CONTRACT_INVALID'
+    });
+  }
+
+  const record = contract as Record<string, unknown>;
+  return normalizeSourceContractDocument({
+    document: {
+      frontmatter: {
+        schema_version: record.schema_version,
+        contract_version: record.contract_version,
+        stage: record.stage,
+        task_id: record.task_id,
+        required_artifacts: record.required_artifacts,
+        allowed_write_roots: record.allowed_write_roots,
+        forbidden_writes: record.forbidden_writes,
+        policy_rules: record.policy_rules,
+        success_criteria: record.success_criteria,
+        skill_routing: record.skill_routing
+      },
+      body: 'compiled-contract'
+    },
+    sourcePath: asString(record.source_path, 'source_path'),
+    sourceHash: asString(record.source_hash, 'source_hash')
+  });
+}

package/src/contracts/compiler.ts

@@ -0,0 +1,111 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+
+import { listFilesRecursive, pathExists, writeFileEnsuringDir } from '../core/fs.js';
+import { normalizeRepoRelativePath, resolveCanonicalPath } from '../core/paths.js';
+import { ProdifyError } from '../core/errors.js';
+import { parseContractSource } from './parser.js';
+import { validateCompiledContractShape } from './compiled-schema.js';
+import { CONTRACT_STAGE_NAMES, normalizeSourceContractDocument } from './source-schema.js';
+import type { CompiledStageContract, FlowStage } from '../types.js';
+
+function createSourceHash(source: string): string {
+  return crypto.createHash('sha256').update(source).digest('hex');
+}
+
+export function serializeCompiledContract(contract: CompiledStageContract): string {
+  return `${JSON.stringify(contract, null, 2)}\n`;
+}
+
+export function compileContractSource(options: {
+  markdown: string;
+  sourcePath: string;
+}): CompiledStageContract {
+  const { markdown, sourcePath } = options;
+  const document = parseContractSource(markdown);
+  return normalizeSourceContractDocument({
+    document,
+    sourcePath,
+    sourceHash: createSourceHash(markdown.replace(/\r\n/g, '\n'))
+  });
+}
+
+export async function compileContractsFromSourceDir(repoRoot: string): Promise<CompiledStageContract[]> {
+  const sourceDir = resolveCanonicalPath(repoRoot, '.prodify/contracts-src');
+  if (!(await pathExists(sourceDir))) {
+    throw new ProdifyError('Contract source directory is missing: .prodify/contracts-src', {
+      code: 'CONTRACT_SOURCE_MISSING'
+    });
+  }
+
+  const files = (await listFilesRecursive(sourceDir))
+    .filter((file) => file.relativePath.endsWith('.contract.md'))
+    .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+
+  const contracts = [];
+  for (const file of files) {
+    const sourcePath = `.prodify/contracts-src/${normalizeRepoRelativePath(file.relativePath)}`;
+    contracts.push(compileContractSource({
+      markdown: await fs.readFile(file.fullPath, 'utf8'),
+      sourcePath
+    }));
+  }
+
+  const seenStages = new Set<FlowStage>();
+  for (const contract of contracts) {
+    if (seenStages.has(contract.stage)) {
+      throw new ProdifyError(`Duplicate contract stage detected: ${contract.stage}.`, {
+        code: 'CONTRACT_SCHEMA_INVALID'
+      });
+    }
+
+    seenStages.add(contract.stage);
+  }
+
+  return contracts.sort((left, right) => left.stage.localeCompare(right.stage));
+}
+
+export async function synchronizeRuntimeContracts(repoRoot: string): Promise<CompiledStageContract[]> {
+  const contracts = await compileContractsFromSourceDir(repoRoot);
+  const compiledDir = resolveCanonicalPath(repoRoot, '.prodify/contracts');
+
+  await writeFileEnsuringDir(
+    resolveCanonicalPath(repoRoot, '.prodify/contracts/README.md'),
+    '# Compiled Contracts\n\nThis directory contains deterministic runtime-only JSON contracts generated from `.prodify/contracts-src/`.\n'
+  );
+
+  for (const contract of contracts) {
+    await writeFileEnsuringDir(
+      resolveCanonicalPath(repoRoot, `.prodify/contracts/${contract.stage}.contract.json`),
+      serializeCompiledContract(contract)
+    );
+  }
+
+  const existingFiles = (await pathExists(compiledDir))
+    ? await listFilesRecursive(compiledDir)
+    : [];
+  for (const file of existingFiles) {
+    if (!file.relativePath.endsWith('.contract.json')) {
+      continue;
+    }
+
+    const stage = file.relativePath.replace(/\.contract\.json$/, '') as FlowStage;
+    if (!CONTRACT_STAGE_NAMES.includes(stage)) {
+      await fs.rm(file.fullPath, { force: true });
+    }
+  }
+
+  return contracts;
+}
+
+export async function loadCompiledContract(repoRoot: string, stage: FlowStage): Promise<CompiledStageContract> {
+  const contractPath = resolveCanonicalPath(repoRoot, `.prodify/contracts/${stage}.contract.json`);
+  if (!(await pathExists(contractPath))) {
+    throw new ProdifyError(`Compiled contract is missing for stage "${stage}".`, {
+      code: 'COMPILED_CONTRACT_MISSING'
+    });
+  }
+
+  const parsed = JSON.parse(await fs.readFile(contractPath, 'utf8'));
+  return validateCompiledContractShape(parsed);
+}

package/src/contracts/freshness.ts

@@ -0,0 +1,58 @@
+import { compileContractsFromSourceDir, loadCompiledContract, serializeCompiledContract } from './compiler.js';
+import { CONTRACT_STAGE_NAMES } from './source-schema.js';
+import type { CompiledContractInventory, CompiledStageContract, FlowStage } from '../types.js';
+
+export async function inspectCompiledContracts(repoRoot: string): Promise<CompiledContractInventory> {
+  const inventory: CompiledContractInventory = {
+    ok: true,
+    sourceCount: 0,
+    compiledCount: 0,
+    staleStages: [],
+    missingCompiledStages: [],
+    missingSourceStages: [],
+    invalidStages: []
+  };
+
+  let expectedContracts: CompiledStageContract[] = [];
+  try {
+    expectedContracts = await compileContractsFromSourceDir(repoRoot);
+    inventory.sourceCount = expectedContracts.length;
+  } catch (error) {
+    inventory.ok = false;
+    inventory.invalidStages.push(error instanceof Error ? error.message : String(error));
+  }
+
+  const expectedByStage = new Map<FlowStage, CompiledStageContract>();
+  for (const contract of expectedContracts) {
+    expectedByStage.set(contract.stage, contract);
+  }
+
+  for (const stage of CONTRACT_STAGE_NAMES) {
+    const expected = expectedByStage.get(stage);
+    if (!expected) {
+      inventory.ok = false;
+      inventory.missingSourceStages.push(stage);
+      continue;
+    }
+
+    try {
+      const compiled = await loadCompiledContract(repoRoot, stage);
+      inventory.compiledCount += 1;
+      if (serializeCompiledContract(compiled) !== serializeCompiledContract(expected)) {
+        inventory.ok = false;
+        inventory.staleStages.push(stage);
+      }
+    } catch (error) {
+      inventory.ok = false;
+      inventory.missingCompiledStages.push(stage);
+      inventory.invalidStages.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  inventory.staleStages.sort((left, right) => left.localeCompare(right));
+  inventory.missingCompiledStages.sort((left, right) => left.localeCompare(right));
+  inventory.missingSourceStages.sort((left, right) => left.localeCompare(right));
+  inventory.invalidStages.sort((left, right) => left.localeCompare(right));
+
+  return inventory;
+}

package/src/contracts/index.ts

@@ -0,0 +1,11 @@
+export { parseContractSource } from './parser.js';
+export { normalizeSourceContractDocument, CONTRACT_STAGE_NAMES } from './source-schema.js';
+export { validateCompiledContractShape } from './compiled-schema.js';
+export {
+  compileContractSource,
+  compileContractsFromSourceDir,
+  synchronizeRuntimeContracts,
+  loadCompiledContract,
+  serializeCompiledContract
+} from './compiler.js';
+export { inspectCompiledContracts } from './freshness.js';

package/src/contracts/parser.ts

@@ -0,0 +1,253 @@
+import { ProdifyError } from '../core/errors.js';
+import type { ContractSourceDocument } from '../types.js';
+
+interface ParsedLine {
+  indent: number;
+  content: string;
+  lineNumber: number;
+}
+
+function parseScalar(rawValue: string): unknown {
+  const value = rawValue.trim();
+
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\''))) {
+    return value.slice(1, -1);
+  }
+
+  if (value === 'true') {
+    return true;
+  }
+
+  if (value === 'false') {
+    return false;
+  }
+
+  if (value === 'null') {
+    return null;
+  }
+
+  if (/^-?\d+(\.\d+)?$/.test(value)) {
+    return Number(value);
+  }
+
+  return value;
+}
+
+function splitKeyValue(content: string, lineNumber: number): { key: string; value: string } {
+  const separatorIndex = content.indexOf(':');
+  if (separatorIndex === -1) {
+    throw new ProdifyError(`Invalid frontmatter at line ${lineNumber}: expected "key: value".`, {
+      code: 'CONTRACT_FRONTMATTER_INVALID'
+    });
+  }
+
+  const key = content.slice(0, separatorIndex).trim();
+  if (!key) {
+    throw new ProdifyError(`Invalid frontmatter at line ${lineNumber}: missing key before ":".`, {
+      code: 'CONTRACT_FRONTMATTER_INVALID'
+    });
+  }
+
+  return {
+    key,
+    value: content.slice(separatorIndex + 1).trim()
+  };
+}
+
+function preprocessFrontmatter(frontmatter: string): ParsedLine[] {
+  return frontmatter
+    .split('\n')
+    .map((line, index) => ({ raw: line.replace(/\r$/, ''), lineNumber: index + 1 }))
+    .filter(({ raw }) => raw.trim() !== '' && !raw.trimStart().startsWith('#'))
+    .map(({ raw, lineNumber }) => {
+      const indent = raw.match(/^ */)?.[0].length ?? 0;
+      if (indent % 2 !== 0) {
+        throw new ProdifyError(`Invalid frontmatter indentation at line ${lineNumber}: use multiples of two spaces.`, {
+          code: 'CONTRACT_FRONTMATTER_INVALID'
+        });
+      }
+
+      return {
+        indent,
+        content: raw.trim(),
+        lineNumber
+      };
+    });
+}
+
+function parseBlock(lines: ParsedLine[], state: { index: number }, indent: number): unknown {
+  const line = lines[state.index];
+  if (!line || line.indent !== indent) {
+    throw new ProdifyError(`Invalid frontmatter near line ${line?.lineNumber ?? 'EOF'}: unexpected indentation.`, {
+      code: 'CONTRACT_FRONTMATTER_INVALID'
+    });
+  }
+
+  if (line.content.startsWith('- ')) {
+    return parseSequence(lines, state, indent);
+  }
+
+  return parseMapping(lines, state, indent);
+}
+
+function parseMapping(lines: ParsedLine[], state: { index: number }, indent: number): Record<string, unknown> {
+  const value: Record<string, unknown> = {};
+
+  while (state.index < lines.length) {
+    const line = lines[state.index];
+    if (line.indent < indent) {
+      break;
+    }
+
+    if (line.indent > indent) {
+      throw new ProdifyError(`Invalid frontmatter at line ${line.lineNumber}: unexpected indentation.`, {
+        code: 'CONTRACT_FRONTMATTER_INVALID'
+      });
+    }
+
+    if (line.content.startsWith('- ')) {
+      throw new ProdifyError(`Invalid frontmatter at line ${line.lineNumber}: sequence item is not valid here.`, {
+        code: 'CONTRACT_FRONTMATTER_INVALID'
+      });
+    }
+
+    const { key, value: rawValue } = splitKeyValue(line.content, line.lineNumber);
+    state.index += 1;
+
+    if (rawValue !== '') {
+      value[key] = parseScalar(rawValue);
+      continue;
+    }
+
+    const nextLine = lines[state.index];
+    if (!nextLine || nextLine.indent <= indent) {
+      throw new ProdifyError(`Invalid frontmatter at line ${line.lineNumber}: expected an indented block for "${key}".`, {
+        code: 'CONTRACT_FRONTMATTER_INVALID'
+      });
+    }
+
+    value[key] = parseBlock(lines, state, indent + 2);
+  }
+
+  return value;
+}
+
+function parseSequence(lines: ParsedLine[], state: { index: number }, indent: number): unknown[] {
+  const value: unknown[] = [];
+
+  while (state.index < lines.length) {
+    const line = lines[state.index];
+    if (line.indent < indent) {
+      break;
+    }
+
+    if (line.indent > indent) {
+      throw new ProdifyError(`Invalid frontmatter at line ${line.lineNumber}: unexpected indentation.`, {
+        code: 'CONTRACT_FRONTMATTER_INVALID'
+      });
+    }
+
+    if (!line.content.startsWith('- ')) {
+      break;
+    }
+
+    const inlineValue = line.content.slice(2).trim();
+    state.index += 1;
+
+    if (inlineValue === '') {
+      const nextLine = lines[state.index];
+      if (!nextLine || nextLine.indent <= indent) {
+        throw new ProdifyError(`Invalid frontmatter at line ${line.lineNumber}: expected an indented sequence value.`, {
+          code: 'CONTRACT_FRONTMATTER_INVALID'
+        });
+      }
+
+      value.push(parseBlock(lines, state, indent + 2));
+      continue;
+    }
+
+    if (inlineValue.includes(':')) {
+      const { key, value: rawValue } = splitKeyValue(inlineValue, line.lineNumber);
+      const item: Record<string, unknown> = {};
+
+      if (rawValue !== '') {
+        item[key] = parseScalar(rawValue);
+      } else {
+        const nextLine = lines[state.index];
+        if (!nextLine || nextLine.indent <= indent) {
+          throw new ProdifyError(`Invalid frontmatter at line ${line.lineNumber}: expected an indented block for "${key}".`, {
+            code: 'CONTRACT_FRONTMATTER_INVALID'
+          });
+        }
+
+        item[key] = parseBlock(lines, state, indent + 2);
+      }
+
+      if (state.index < lines.length && lines[state.index].indent > indent) {
+        Object.assign(item, parseMapping(lines, state, indent + 2));
+      }
+
+      value.push(item);
+      continue;
+    }
+
+    value.push(parseScalar(inlineValue));
+  }
+
+  return value;
+}
+
+function parseFrontmatter(frontmatter: string): Record<string, unknown> {
+  const lines = preprocessFrontmatter(frontmatter);
+  if (lines.length === 0) {
+    throw new ProdifyError('Contract source frontmatter is empty.', {
+      code: 'CONTRACT_FRONTMATTER_INVALID'
+    });
+  }
+
+  const state = { index: 0 };
+  const parsed = parseBlock(lines, state, 0);
+  if (state.index !== lines.length) {
+    const nextLine = lines[state.index];
+    throw new ProdifyError(`Invalid frontmatter at line ${nextLine.lineNumber}: trailing content could not be parsed.`, {
+      code: 'CONTRACT_FRONTMATTER_INVALID'
+    });
+  }
+
+  if (Array.isArray(parsed)) {
+    throw new ProdifyError('Contract source frontmatter must be a mapping.', {
+      code: 'CONTRACT_FRONTMATTER_INVALID'
+    });
+  }
+
+  return parsed as Record<string, unknown>;
+}
+
+export function parseContractSource(markdown: string): ContractSourceDocument {
+  const normalized = markdown.replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---\n')) {
+    throw new ProdifyError('Contract source must start with YAML frontmatter delimited by "---".', {
+      code: 'CONTRACT_FRONTMATTER_MISSING'
+    });
+  }
+
+  const closingIndex = normalized.indexOf('\n---\n', 4);
+  if (closingIndex === -1) {
+    throw new ProdifyError('Contract source frontmatter is not closed with "---".', {
+      code: 'CONTRACT_FRONTMATTER_MISSING'
+    });
+  }
+
+  const rawFrontmatter = normalized.slice(4, closingIndex);
+  const body = normalized.slice(closingIndex + 5).trim();
+  if (!body) {
+    throw new ProdifyError('Contract source body is empty.', {
+      code: 'CONTRACT_BODY_EMPTY'
+    });
+  }
+
+  return {
+    frontmatter: parseFrontmatter(rawFrontmatter),
+    body
+  };
+}