@urielsh/prodify 0.1.0

package/dist/contracts/source-schema.js

@@ -0,0 +1,111 @@
+import { normalizeRepoRelativePath } from '../core/paths.js';
+import { ProdifyError } from '../core/errors.js';
+import { stageToTaskId } from '../core/flow-state.js';
+import { normalizeStageSkillRouting } from '../skills/schema.js';
+export const CONTRACT_STAGE_NAMES = ['understand', 'diagnose', 'architecture', 'plan', 'refactor', 'validate'];
+function asString(value, fieldName) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new ProdifyError(`Contract frontmatter field "${fieldName}" must be a non-empty string.`, {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    return value.trim();
+}
+function asStringArray(value, fieldName) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new ProdifyError(`Contract frontmatter field "${fieldName}" must be a non-empty list.`, {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    const normalized = value.map((entry) => asString(entry, fieldName));
+    return [...new Set(normalized)].sort((left, right) => left.localeCompare(right));
+}
+function asOptionalStringArray(value, fieldName) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return [];
+    }
+    return asStringArray(value, fieldName);
+}
+function asStage(value) {
+    const stage = asString(value, 'stage');
+    if (!CONTRACT_STAGE_NAMES.includes(stage)) {
+        throw new ProdifyError(`Contract frontmatter field "stage" is invalid: ${stage}.`, {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    return stage;
+}
+function normalizeArtifactRule(rawValue) {
+    if (typeof rawValue !== 'object' || rawValue === null || Array.isArray(rawValue)) {
+        throw new ProdifyError('Each required_artifacts entry must be a mapping.', {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    const record = rawValue;
+    const path = normalizeRepoRelativePath(asString(record.path, 'required_artifacts.path'));
+    const format = asString(record.format, 'required_artifacts.format');
+    if (format !== 'markdown' && format !== 'json') {
+        throw new ProdifyError(`Unsupported artifact format: ${format}.`, {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    const requiredSections = asOptionalStringArray(record.required_sections, 'required_artifacts.required_sections');
+    const requiredJsonKeys = asOptionalStringArray(record.required_json_keys, 'required_artifacts.required_json_keys');
+    if (format === 'markdown' && requiredSections.length === 0) {
+        throw new ProdifyError(`Markdown artifact "${path}" must declare required_sections.`, {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    if (format === 'json' && requiredJsonKeys.length === 0) {
+        throw new ProdifyError(`JSON artifact "${path}" must declare required_json_keys.`, {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    return {
+        path,
+        format,
+        required_sections: requiredSections,
+        required_json_keys: requiredJsonKeys
+    };
+}
+export function normalizeSourceContractDocument(options) {
+    const { document, sourcePath, sourceHash } = options;
+    const stage = asStage(document.frontmatter.stage);
+    const taskId = asString(document.frontmatter.task_id, 'task_id');
+    if (taskId !== stageToTaskId(stage)) {
+        throw new ProdifyError(`Contract task_id "${taskId}" does not match stage "${stage}".`, {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    if (document.body.trim().length === 0) {
+        throw new ProdifyError(`Contract source "${sourcePath}" must contain explanatory body content.`, {
+            code: 'CONTRACT_BODY_EMPTY'
+        });
+    }
+    const rawArtifacts = document.frontmatter.required_artifacts;
+    if (!Array.isArray(rawArtifacts) || rawArtifacts.length === 0) {
+        throw new ProdifyError('Contract frontmatter field "required_artifacts" must contain at least one artifact rule.', {
+            code: 'CONTRACT_SCHEMA_INVALID'
+        });
+    }
+    const requiredArtifacts = rawArtifacts
+        .map((artifact) => normalizeArtifactRule(artifact))
+        .sort((left, right) => left.path.localeCompare(right.path));
+    return {
+        schema_version: String(document.frontmatter.schema_version ?? '1'),
+        contract_version: asString(document.frontmatter.contract_version, 'contract_version'),
+        stage,
+        task_id: taskId,
+        source_path: normalizeRepoRelativePath(sourcePath),
+        source_hash: sourceHash,
+        required_artifacts: requiredArtifacts,
+        allowed_write_roots: asStringArray(document.frontmatter.allowed_write_roots, 'allowed_write_roots')
+            .map((entry) => normalizeRepoRelativePath(entry)),
+        forbidden_writes: Array.isArray(document.frontmatter.forbidden_writes)
+            ? asStringArray(document.frontmatter.forbidden_writes, 'forbidden_writes').map((entry) => normalizeRepoRelativePath(entry))
+            : [],
+        policy_rules: asStringArray(document.frontmatter.policy_rules, 'policy_rules'),
+        success_criteria: asStringArray(document.frontmatter.success_criteria, 'success_criteria'),
+        skill_routing: normalizeStageSkillRouting(document.frontmatter.skill_routing)
+    };
+}

package/dist/core/agent-runtime.js

@@ -0,0 +1,36 @@
+import { ProdifyError } from './errors.js';
+import { readGlobalAgentSetupState, listConfiguredAgents } from './agent-setup.js';
+import { getRuntimeProfile } from './targets.js';
+export function detectRuntimeAgentFromEnv(env = process.env) {
+    const candidate = env.PRODIFY_ACTIVE_AGENT?.trim();
+    if (!candidate) {
+        return null;
+    }
+    return getRuntimeProfile(candidate)?.name ?? null;
+}
+export async function resolveRuntimeAgentBinding({ requestedAgent = null, env = process.env } = {}) {
+    const explicit = requestedAgent ? getRuntimeProfile(requestedAgent)?.name ?? null : null;
+    if (explicit) {
+        return explicit;
+    }
+    const envAgent = detectRuntimeAgentFromEnv(env);
+    if (envAgent) {
+        return envAgent;
+    }
+    const setupState = await readGlobalAgentSetupState({
+        allowMissing: true,
+        env
+    });
+    const configuredAgents = listConfiguredAgents(setupState);
+    if (configuredAgents.length === 1) {
+        return configuredAgents[0];
+    }
+    if (configuredAgents.length === 0) {
+        throw new ProdifyError('Could not resolve the active agent runtime. Run `prodify setup-agent <agent>` or set PRODIFY_ACTIVE_AGENT.', {
+            code: 'AGENT_RUNTIME_UNRESOLVED'
+        });
+    }
+    throw new ProdifyError('Multiple agents are configured globally. Set PRODIFY_ACTIVE_AGENT or pass an explicit agent for runtime binding.', {
+        code: 'AGENT_RUNTIME_AMBIGUOUS'
+    });
+}

package/dist/core/agent-setup.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { ProdifyError } from './errors.js';
+import { pathExists, writeFileEnsuringDir } from './fs.js';
+import { getRuntimeProfile } from './targets.js';
+export const GLOBAL_AGENT_SETUP_SCHEMA_VERSION = '1';
+export const PRODIFY_RUNTIME_COMMANDS = ['$prodify-init', '$prodify-execute', '$prodify-resume'];
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+export function resolveGlobalProdifyHome(env = process.env) {
+    const explicit = env.PRODIFY_HOME?.trim();
+    if (explicit) {
+        return path.resolve(explicit);
+    }
+    const xdgStateHome = env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome) {
+        return path.resolve(xdgStateHome, 'prodify');
+    }
+    return path.join(os.homedir(), '.prodify');
+}
+export function resolveGlobalAgentSetupStatePath(env = process.env) {
+    return path.join(resolveGlobalProdifyHome(env), 'agent-setup.json');
+}
+export function createInitialGlobalAgentSetupState() {
+    return {
+        schema_version: GLOBAL_AGENT_SETUP_SCHEMA_VERSION,
+        configured_agents: {}
+    };
+}
+export function listConfiguredAgents(state) {
+    if (!state) {
+        return [];
+    }
+    return Object.entries(state.configured_agents)
+        .filter(([, value]) => Boolean(value))
+        .map(([agent]) => agent)
+        .sort((left, right) => left.localeCompare(right));
+}
+function normalizeGlobalAgentSetupState(raw) {
+    const record = asRecord(raw);
+    const configuredAgents = asRecord(record.configured_agents);
+    const normalized = createInitialGlobalAgentSetupState();
+    for (const [agent, value] of Object.entries(configuredAgents)) {
+        const profile = getRuntimeProfile(agent);
+        const entry = asRecord(value);
+        if (!profile) {
+            continue;
+        }
+        normalized.configured_agents[profile.name] = {
+            agent: profile.name,
+            display_name: typeof entry.display_name === 'string' ? entry.display_name : profile.displayName,
+            configured_at: typeof entry.configured_at === 'string' ? entry.configured_at : 'unknown',
+            commands: Array.isArray(entry.commands)
+                ? entry.commands.filter((command) => typeof command === 'string')
+                : [...PRODIFY_RUNTIME_COMMANDS]
+        };
+    }
+    return normalized;
+}
+export async function readGlobalAgentSetupState({ allowMissing = false, env = process.env } = {}) {
+    const statePath = resolveGlobalAgentSetupStatePath(env);
+    if (!(await pathExists(statePath))) {
+        if (allowMissing) {
+            return null;
+        }
+        throw new ProdifyError(`Global agent setup state is missing: ${statePath}`, {
+            code: 'GLOBAL_AGENT_SETUP_MISSING'
+        });
+    }
+    try {
+        return normalizeGlobalAgentSetupState(JSON.parse(await fs.readFile(statePath, 'utf8')));
+    }
+    catch {
+        throw new ProdifyError(`Global agent setup state is malformed: ${statePath}`, {
+            code: 'GLOBAL_AGENT_SETUP_MALFORMED'
+        });
+    }
+}
+export async function writeGlobalAgentSetupState(state, { env = process.env } = {}) {
+    const statePath = resolveGlobalAgentSetupStatePath(env);
+    await writeFileEnsuringDir(statePath, `${JSON.stringify(state, null, 2)}\n`);
+    return statePath;
+}
+export async function setupAgentIntegration(agent, { now = new Date().toISOString(), env = process.env } = {}) {
+    const profile = getRuntimeProfile(agent);
+    if (!profile) {
+        throw new ProdifyError('setup-agent requires <codex|claude|copilot|opencode>.', {
+            code: 'INVALID_AGENT'
+        });
+    }
+    const existingState = await readGlobalAgentSetupState({
+        allowMissing: true,
+        env
+    });
+    const nextState = existingState ?? createInitialGlobalAgentSetupState();
+    const alreadyConfigured = Boolean(nextState.configured_agents[profile.name]);
+    nextState.configured_agents[profile.name] = {
+        agent: profile.name,
+        display_name: profile.displayName,
+        configured_at: now,
+        commands: [...PRODIFY_RUNTIME_COMMANDS]
+    };
+    const statePath = await writeGlobalAgentSetupState(nextState, { env });
+    return {
+        statePath,
+        configuredAgents: listConfiguredAgents(nextState),
+        alreadyConfigured
+    };
+}

package/dist/core/doctor.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs/promises';
+import { REQUIRED_CANONICAL_PATHS, resolveCanonicalPath, resolveRepoPath } from './paths.js';
+import { pathExists } from './fs.js';
+import { readRuntimeState } from './state.js';
+import { inspectVersionStatus } from './version-checks.js';
+import { loadDefaultPreset } from '../presets/loader.js';
+import { parseVersionMetadata } from '../presets/version.js';
+import { hasManualBootstrapGuidance } from './prompt-builder.js';
+import { inspectCompiledContracts } from '../contracts/freshness.js';
+function isProdifyDirectoryIgnore(pattern) {
+    const trimmed = pattern.trim();
+    return trimmed === '.prodify'
+        || trimmed === '.prodify/'
+        || trimmed === '/.prodify'
+        || trimmed === '/.prodify/';
+}
+async function inspectGitignore(repoRoot) {
+    const gitignorePath = resolveRepoPath(repoRoot, '.gitignore');
+    if (!(await pathExists(gitignorePath))) {
+        return {
+            label: 'gitignore/prodify',
+            ok: true,
+            details: '.gitignore does not hide .prodify/'
+        };
+    }
+    const content = await fs.readFile(gitignorePath, 'utf8');
+    const badPatterns = content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '' && !line.startsWith('#'))
+        .filter(isProdifyDirectoryIgnore);
+    return {
+        label: 'gitignore/prodify',
+        ok: badPatterns.length === 0,
+        details: badPatterns.length === 0
+            ? '.gitignore does not ignore .prodify/'
+            : `bad patterns found: ${badPatterns.join(', ')}`
+    };
+}
+async function inspectBootstrapGuidance(repoRoot) {
+    const guidancePath = resolveCanonicalPath(repoRoot, '.prodify/AGENTS.md');
+    if (!(await pathExists(guidancePath))) {
+        return {
+            label: 'bootstrap/guidance',
+            ok: false,
+            details: '.prodify/AGENTS.md is missing'
+        };
+    }
+    const guidance = await fs.readFile(guidancePath, 'utf8');
+    return {
+        label: 'bootstrap/guidance',
+        ok: hasManualBootstrapGuidance(guidance),
+        details: hasManualBootstrapGuidance(guidance)
+            ? 'manual agent entry is documented in .prodify/AGENTS.md'
+            : '.prodify/AGENTS.md does not contain the manual bootstrap instruction'
+    };
+}
+export async function runDoctor(repoRoot) {
+    const checks = [];
+    const preset = await loadDefaultPreset();
+    const prodifyPath = resolveRepoPath(repoRoot, '.prodify');
+    const prodifyExists = await pathExists(prodifyPath);
+    if (!prodifyExists) {
+        checks.push({
+            label: 'canonical',
+            ok: false,
+            details: '.prodify/ is missing'
+        });
+        return {
+            ok: false,
+            checks
+        };
+    }
+    const missingCanonicalFiles = [];
+    for (const relativePath of REQUIRED_CANONICAL_PATHS) {
+        if (!(await pathExists(resolveCanonicalPath(repoRoot, relativePath)))) {
+            missingCanonicalFiles.push(relativePath);
+        }
+    }
+    checks.push({
+        label: 'canonical',
+        ok: missingCanonicalFiles.length === 0,
+        details: missingCanonicalFiles.length === 0
+            ? 'required canonical files verified'
+            : `missing canonical files: ${missingCanonicalFiles.join(', ')}`
+    });
+    const contractInventory = await inspectCompiledContracts(repoRoot);
+    checks.push({
+        label: 'contracts/source',
+        ok: contractInventory.missingSourceStages.length === 0 && contractInventory.invalidStages.length === 0,
+        details: contractInventory.missingSourceStages.length === 0
+            ? `source contracts detected: ${contractInventory.sourceCount}`
+            : `missing source contracts: ${contractInventory.missingSourceStages.join(', ')}`
+    });
+    checks.push({
+        label: 'contracts/compiled',
+        ok: contractInventory.ok,
+        details: contractInventory.ok
+            ? `compiled contracts synchronized: ${contractInventory.compiledCount}`
+            : [
+                contractInventory.missingCompiledStages.length > 0 ? `missing compiled: ${contractInventory.missingCompiledStages.join(', ')}` : '',
+                contractInventory.staleStages.length > 0 ? `stale: ${contractInventory.staleStages.join(', ')}` : '',
+                contractInventory.invalidStages.length > 0 ? `invalid: ${contractInventory.invalidStages.join(', ')}` : ''
+            ].filter(Boolean).join('; ')
+    });
+    const versionPath = resolveCanonicalPath(repoRoot, '.prodify/version.json');
+    if (await pathExists(versionPath)) {
+        try {
+            parseVersionMetadata(await fs.readFile(versionPath, 'utf8'));
+            checks.push({
+                label: 'canonical/version',
+                ok: true,
+                details: 'version metadata is readable'
+            });
+        }
+        catch {
+            checks.push({
+                label: 'canonical/version',
+                ok: false,
+                details: '.prodify/version.json is malformed'
+            });
+        }
+    }
+    const versionStatus = await inspectVersionStatus(repoRoot, preset.metadata);
+    checks.push({
+        label: 'canonical/schema',
+        ok: versionStatus.status === 'current',
+        details: versionStatus.status === 'current'
+            ? `preset ${preset.metadata.name}@${preset.metadata.version} matches`
+            : `version status is ${versionStatus.status}`
+    });
+    try {
+        await readRuntimeState(repoRoot, {
+            presetMetadata: preset.metadata
+        });
+        checks.push({
+            label: 'runtime/state',
+            ok: true,
+            details: '.prodify/state.json is readable'
+        });
+    }
+    catch {
+        checks.push({
+            label: 'runtime/state',
+            ok: false,
+            details: '.prodify/state.json is missing or malformed'
+        });
+    }
+    checks.push(await inspectGitignore(repoRoot));
+    checks.push(await inspectBootstrapGuidance(repoRoot));
+    return {
+        ok: checks.every((check) => check.ok || check.skipped === true),
+        checks
+    };
+}

package/dist/core/errors.js

@@ -0,0 +1,19 @@
+export class ProdifyError extends Error {
+    code;
+    exitCode;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'ProdifyError';
+        this.code = options.code ?? 'PRODIFY_ERROR';
+        this.exitCode = options.exitCode ?? 1;
+    }
+}
+export function toErrorMessage(error) {
+    if (error instanceof ProdifyError) {
+        return error.message;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}