@codewalla_india/openspec 1.0.1

package/dist/core/completions/types.d.ts

@@ -0,0 +1,101 @@
+import { SupportedShell } from '../../utils/shell-detection.js';
+/**
+ * Definition of a command-line flag/option
+ */
+export interface FlagDefinition {
+    /**
+     * Flag name without dashes (e.g., "json", "strict", "no-interactive")
+     */
+    name: string;
+    /**
+     * Short flag name without dash (e.g., "y" for "-y")
+     */
+    short?: string;
+    /**
+     * Human-readable description of what the flag does
+     */
+    description: string;
+    /**
+     * Whether the flag takes an argument value
+     */
+    takesValue?: boolean;
+    /**
+     * Possible values for the flag (for completion suggestions)
+     */
+    values?: string[];
+}
+export type PositionalType = 'change-id' | 'spec-id' | 'change-or-spec-id' | 'path' | 'shell' | 'schema-name';
+/**
+ * Definition of a positional argument.
+ */
+export interface PositionalDefinition {
+    /**
+     * Positional name used in generated shell metadata.
+     */
+    name: string;
+    /**
+     * Type of positional argument for dynamic completion.
+     */
+    type?: PositionalType;
+    /**
+     * Whether this positional is optional in the CLI syntax.
+     */
+    optional?: boolean;
+}
+/**
+ * Definition of a CLI command
+ */
+export interface CommandDefinition {
+    /**
+     * Command name (e.g., "init", "validate", "show")
+     */
+    name: string;
+    /**
+     * Human-readable description of the command
+     */
+    description: string;
+    /**
+     * Flags/options supported by this command
+     */
+    flags: FlagDefinition[];
+    /**
+     * Subcommands (e.g., "change show", "spec validate")
+     */
+    subcommands?: CommandDefinition[];
+    /**
+     * Whether this command accepts a positional argument (e.g., item name, path)
+     */
+    acceptsPositional?: boolean;
+    /**
+     * Type of positional argument for dynamic completion
+     * - 'change-id': Complete with active change IDs
+     * - 'spec-id': Complete with spec IDs
+     * - 'change-or-spec-id': Complete with both changes and specs
+     * - 'path': Complete with file paths
+     * - 'shell': Complete with supported shell names
+     * - 'schema-name': Complete with available schema names
+     * - undefined: No specific completion
+     */
+    positionalType?: PositionalType;
+    /**
+     * Ordered positional arguments when a command accepts more than one.
+     */
+    positionals?: PositionalDefinition[];
+}
+/**
+ * Interface for shell-specific completion script generators
+ */
+export interface CompletionGenerator {
+    /**
+     * The shell type this generator targets
+     */
+    readonly shell: SupportedShell;
+    /**
+     * Generate the completion script content
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns The shell-specific completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/completions/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/comprehension/config.d.ts

@@ -0,0 +1,20 @@
+import type { ProjectConfig } from '../project-config.js';
+export interface ComprehensionConfig {
+    enabled: boolean;
+    thresholdPercent: number;
+    minQuestions: number;
+    maxQuestions: number;
+}
+export declare const DEFAULT_COMPREHENSION_CONFIG: ComprehensionConfig;
+export interface ComprehensionConfigInput {
+    enabled?: boolean;
+    threshold_percent?: number;
+    min_questions?: number;
+    max_questions?: number;
+}
+/**
+ * Resolve comprehension settings from project config.
+ * Defaults apply when config is missing or fields are absent.
+ */
+export declare function resolveComprehensionConfig(projectConfig: ProjectConfig | null | undefined): ComprehensionConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/comprehension/config.js

@@ -0,0 +1,23 @@
+export const DEFAULT_COMPREHENSION_CONFIG = {
+    enabled: true,
+    thresholdPercent: 80,
+    minQuestions: 5,
+    maxQuestions: 10,
+};
+/**
+ * Resolve comprehension settings from project config.
+ * Defaults apply when config is missing or fields are absent.
+ */
+export function resolveComprehensionConfig(projectConfig) {
+    const raw = projectConfig?.comprehension;
+    if (!raw) {
+        return { ...DEFAULT_COMPREHENSION_CONFIG };
+    }
+    return {
+        enabled: raw.enabled ?? DEFAULT_COMPREHENSION_CONFIG.enabled,
+        thresholdPercent: raw.thresholdPercent ?? DEFAULT_COMPREHENSION_CONFIG.thresholdPercent,
+        minQuestions: raw.minQuestions ?? DEFAULT_COMPREHENSION_CONFIG.minQuestions,
+        maxQuestions: raw.maxQuestions ?? DEFAULT_COMPREHENSION_CONFIG.maxQuestions,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/comprehension/fingerprint.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SHA-256 fingerprint of delta spec and optional tasks file contents.
+ */
+export declare function fingerprintSpecFiles(specPaths: string[], tasksPath?: string | null): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/core/comprehension/fingerprint.js

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+/**
+ * SHA-256 fingerprint of delta spec and optional tasks file contents.
+ */
+export function fingerprintSpecFiles(specPaths, tasksPath) {
+    const sorted = [...specPaths].sort();
+    const hash = createHash('sha256');
+    for (const specPath of sorted) {
+        hash.update('spec:');
+        hash.update(specPath);
+        hash.update('\0');
+        hash.update(readFileSync(specPath, 'utf-8'));
+        hash.update('\0');
+    }
+    if (tasksPath && existsSync(tasksPath)) {
+        hash.update('tasks:');
+        hash.update(tasksPath);
+        hash.update('\0');
+        hash.update(readFileSync(tasksPath, 'utf-8'));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/core/comprehension/index.d.ts

@@ -0,0 +1,49 @@
+import type { ProjectConfig } from '../project-config.js';
+import { type ComprehensionPassRecord } from './pass-record.js';
+export { DEFAULT_COMPREHENSION_CONFIG, resolveComprehensionConfig, type ComprehensionConfig, } from './config.js';
+export { fingerprintSpecFiles } from './fingerprint.js';
+export { COMPREHENSION_PASS_FILENAME, COMPREHENSION_SESSION_FILENAME, buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, type ComprehensionPassRecord, } from './pass-record.js';
+export { computeQuestionCount, computeSpecStats, countSpecStats, type SpecStats } from './stats.js';
+export interface ComprehensionGateInfo {
+    required: boolean;
+    passed: boolean;
+    thresholdPercent: number;
+    bestScorePercent?: number;
+    questionCount: number;
+    requirementCount: number;
+    scenarioCount: number;
+    pendingTaskCount: number;
+    attempts?: number;
+}
+export interface ComprehensionGateOptions {
+    tasksPath?: string | null;
+    pendingTaskCount?: number;
+}
+export interface ComprehensionGateResult {
+    active: boolean;
+    passed: boolean;
+    info?: ComprehensionGateInfo;
+}
+/**
+ * Evaluate whether apply is blocked by the comprehension gate.
+ */
+export declare function checkComprehensionGate(changeDir: string, specPaths: string[], projectConfig: ProjectConfig | null | undefined, gateOptions?: ComprehensionGateOptions): ComprehensionGateResult;
+export declare class ComprehensionPassError extends Error {
+    readonly score: number;
+    readonly threshold: number;
+    constructor(message: string, score: number, threshold: number);
+}
+/**
+ * Record a comprehension pass after quiz success.
+ */
+export declare function recordComprehensionPass(input: {
+    changeDir: string;
+    specPaths: string[];
+    tasksPath?: string | null;
+    projectConfig: ProjectConfig | null | undefined;
+    scorePercent: number;
+    attempt: number;
+    questionCount: number;
+    pendingTaskCount?: number;
+}): ComprehensionPassRecord;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/comprehension/index.js

@@ -0,0 +1,78 @@
+import { resolveComprehensionConfig } from './config.js';
+import { fingerprintSpecFiles } from './fingerprint.js';
+import { buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, } from './pass-record.js';
+import { computeSpecStats } from './stats.js';
+export { DEFAULT_COMPREHENSION_CONFIG, resolveComprehensionConfig, } from './config.js';
+export { fingerprintSpecFiles } from './fingerprint.js';
+export { COMPREHENSION_PASS_FILENAME, COMPREHENSION_SESSION_FILENAME, buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, } from './pass-record.js';
+export { computeQuestionCount, computeSpecStats, countSpecStats } from './stats.js';
+/**
+ * Evaluate whether apply is blocked by the comprehension gate.
+ */
+export function checkComprehensionGate(changeDir, specPaths, projectConfig, gateOptions = {}) {
+    const config = resolveComprehensionConfig(projectConfig);
+    const pendingTaskCount = gateOptions.pendingTaskCount ?? 0;
+    const tasksPath = gateOptions.tasksPath ?? null;
+    if (!config.enabled) {
+        return { active: false, passed: true };
+    }
+    if (specPaths.length === 0) {
+        return { active: false, passed: true };
+    }
+    const stats = computeSpecStats(specPaths, config, pendingTaskCount);
+    if (stats.requirementCount === 0) {
+        return { active: false, passed: true };
+    }
+    const fingerprint = fingerprintSpecFiles(specPaths, tasksPath);
+    const record = readPassRecord(changeDir);
+    const passed = isPassValid(record, fingerprint);
+    const info = {
+        required: true,
+        passed,
+        thresholdPercent: config.thresholdPercent,
+        questionCount: stats.questionCount,
+        requirementCount: stats.requirementCount,
+        scenarioCount: stats.scenarioCount,
+        pendingTaskCount: stats.pendingTaskCount,
+        ...(record && !passed
+            ? { bestScorePercent: record.score_percent, attempts: record.attempt }
+            : record && passed
+                ? { attempts: record.attempt }
+                : {}),
+    };
+    return { active: true, passed, info };
+}
+export class ComprehensionPassError extends Error {
+    score;
+    threshold;
+    constructor(message, score, threshold) {
+        super(message);
+        this.score = score;
+        this.threshold = threshold;
+        this.name = 'ComprehensionPassError';
+    }
+}
+/**
+ * Record a comprehension pass after quiz success.
+ */
+export function recordComprehensionPass(input) {
+    const config = resolveComprehensionConfig(input.projectConfig);
+    if (input.scorePercent < config.thresholdPercent) {
+        throw new ComprehensionPassError(`Score ${input.scorePercent}% is below the ${config.thresholdPercent}% threshold required to apply.`, input.scorePercent, config.thresholdPercent);
+    }
+    const stats = input.questionCount > 0
+        ? { questionCount: input.questionCount }
+        : computeSpecStats(input.specPaths, config, input.pendingTaskCount ?? 0);
+    const fingerprint = fingerprintSpecFiles(input.specPaths, input.tasksPath);
+    const record = buildPassRecord({
+        scorePercent: input.scorePercent,
+        thresholdPercent: config.thresholdPercent,
+        attempt: input.attempt,
+        questionCount: stats.questionCount,
+        specFingerprint: fingerprint,
+    });
+    writePassRecord(input.changeDir, record);
+    deleteSessionRecord(input.changeDir);
+    return record;
+}
+//# sourceMappingURL=index.js.map

package/dist/core/comprehension/pass-record.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const COMPREHENSION_PASS_FILENAME = ".comprehension-pass.yaml";
+export declare const COMPREHENSION_SESSION_FILENAME = ".comprehension-session.yaml";
+declare const PassRecordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    passed: z.ZodLiteral<true>;
+    score_percent: z.ZodNumber;
+    threshold_percent: z.ZodNumber;
+    attempt: z.ZodNumber;
+    question_count: z.ZodNumber;
+    spec_fingerprint: z.ZodString;
+    passed_at: z.ZodString;
+}, z.core.$strip>;
+export type ComprehensionPassRecord = z.infer<typeof PassRecordSchema>;
+export declare function passRecordPath(changeDir: string): string;
+export declare function sessionRecordPath(changeDir: string): string;
+export declare function readPassRecord(changeDir: string): ComprehensionPassRecord | null;
+export declare function writePassRecord(changeDir: string, record: ComprehensionPassRecord): void;
+export declare function deleteSessionRecord(changeDir: string): void;
+export declare function isPassValid(record: ComprehensionPassRecord | null, currentFingerprint: string): boolean;
+export declare function buildPassRecord(input: {
+    scorePercent: number;
+    thresholdPercent: number;
+    attempt: number;
+    questionCount: number;
+    specFingerprint: string;
+}): ComprehensionPassRecord;
+export {};
+//# sourceMappingURL=pass-record.d.ts.map

package/dist/core/comprehension/pass-record.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { z } from 'zod';
+export const COMPREHENSION_PASS_FILENAME = '.comprehension-pass.yaml';
+export const COMPREHENSION_SESSION_FILENAME = '.comprehension-session.yaml';
+const PassRecordSchema = z.object({
+    version: z.literal(1),
+    passed: z.literal(true),
+    score_percent: z.number().int().min(0).max(100),
+    threshold_percent: z.number().int().min(0).max(100),
+    attempt: z.number().int().positive(),
+    question_count: z.number().int().positive(),
+    spec_fingerprint: z.string().min(1),
+    passed_at: z.string().min(1),
+});
+export function passRecordPath(changeDir) {
+    return path.join(changeDir, COMPREHENSION_PASS_FILENAME);
+}
+export function sessionRecordPath(changeDir) {
+    return path.join(changeDir, COMPREHENSION_SESSION_FILENAME);
+}
+export function readPassRecord(changeDir) {
+    const filePath = passRecordPath(changeDir);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const parsed = parseYaml(readFileSync(filePath, 'utf-8'));
+        const result = PassRecordSchema.safeParse(parsed);
+        return result.success ? result.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writePassRecord(changeDir, record) {
+    writeFileSync(passRecordPath(changeDir), stringifyYaml(record), 'utf-8');
+}
+export function deleteSessionRecord(changeDir) {
+    const filePath = sessionRecordPath(changeDir);
+    if (existsSync(filePath)) {
+        unlinkSync(filePath);
+    }
+}
+export function isPassValid(record, currentFingerprint) {
+    if (!record?.passed) {
+        return false;
+    }
+    return record.spec_fingerprint === currentFingerprint;
+}
+export function buildPassRecord(input) {
+    return {
+        version: 1,
+        passed: true,
+        score_percent: input.scorePercent,
+        threshold_percent: input.thresholdPercent,
+        attempt: input.attempt,
+        question_count: input.questionCount,
+        spec_fingerprint: input.specFingerprint,
+        passed_at: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=pass-record.js.map

package/dist/core/comprehension/stats.d.ts

@@ -0,0 +1,18 @@
+import type { ComprehensionConfig } from './config.js';
+export interface SpecStats {
+    requirementCount: number;
+    scenarioCount: number;
+    pendingTaskCount: number;
+    questionCount: number;
+}
+/**
+ * Count requirements and scenarios across delta spec files.
+ */
+export declare function countSpecStats(specPaths: string[]): Pick<SpecStats, 'requirementCount' | 'scenarioCount'>;
+/**
+ * Target quiz length from spec and task size:
+ * clamp(min, max, round(req * 0.6 + scenarios * 0.15 + pendingTasks * 0.15)).
+ */
+export declare function computeQuestionCount(requirementCount: number, scenarioCount: number, pendingTaskCount: number, config: Pick<ComprehensionConfig, 'minQuestions' | 'maxQuestions'>): number;
+export declare function computeSpecStats(specPaths: string[], config: Pick<ComprehensionConfig, 'minQuestions' | 'maxQuestions'>, pendingTaskCount?: number): SpecStats;
+//# sourceMappingURL=stats.d.ts.map

package/dist/core/comprehension/stats.js

@@ -0,0 +1,41 @@
+import { readFileSync } from 'node:fs';
+import { parseDeltaSpec } from '../parsers/requirement-blocks.js';
+const SCENARIO_HEADER_REGEX = /^####\s*Scenario:/gim;
+function countScenariosInBlock(raw) {
+    const matches = raw.match(SCENARIO_HEADER_REGEX);
+    return matches?.length ?? 0;
+}
+/**
+ * Count requirements and scenarios across delta spec files.
+ */
+export function countSpecStats(specPaths) {
+    let requirementCount = 0;
+    let scenarioCount = 0;
+    for (const specPath of specPaths) {
+        const content = readFileSync(specPath, 'utf-8');
+        const plan = parseDeltaSpec(content);
+        const blocks = [...plan.added, ...plan.modified];
+        requirementCount += blocks.length;
+        for (const block of blocks) {
+            scenarioCount += countScenariosInBlock(block.raw);
+        }
+    }
+    return { requirementCount, scenarioCount };
+}
+function clamp(min, max, value) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Target quiz length from spec and task size:
+ * clamp(min, max, round(req * 0.6 + scenarios * 0.15 + pendingTasks * 0.15)).
+ */
+export function computeQuestionCount(requirementCount, scenarioCount, pendingTaskCount, config) {
+    const raw = Math.round(requirementCount * 0.6 + scenarioCount * 0.15 + pendingTaskCount * 0.15);
+    return clamp(config.minQuestions, config.maxQuestions, raw);
+}
+export function computeSpecStats(specPaths, config, pendingTaskCount = 0) {
+    const { requirementCount, scenarioCount } = countSpecStats(specPaths);
+    const questionCount = computeQuestionCount(requirementCount, scenarioCount, pendingTaskCount, config);
+    return { requirementCount, scenarioCount, pendingTaskCount, questionCount };
+}
+//# sourceMappingURL=stats.js.map

package/dist/core/config-prompts.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectConfig } from './project-config.js';
+/**
+ * Serialize config to YAML string with helpful comments.
+ *
+ * @param config - Partial config object (schema required, context/rules optional)
+ * @returns YAML string ready to write to file
+ */
+export declare function serializeConfig(config: Partial<ProjectConfig>): string;
+//# sourceMappingURL=config-prompts.d.ts.map

package/dist/core/config-prompts.js

@@ -0,0 +1,34 @@
+/**
+ * Serialize config to YAML string with helpful comments.
+ *
+ * @param config - Partial config object (schema required, context/rules optional)
+ * @returns YAML string ready to write to file
+ */
+export function serializeConfig(config) {
+    const lines = [];
+    // Schema (required)
+    lines.push(`schema: ${config.schema}`);
+    lines.push('');
+    // Context section with comments
+    lines.push('# Project context (optional)');
+    lines.push('# This is shown to AI when creating artifacts.');
+    lines.push('# Add your tech stack, conventions, style guides, domain knowledge, etc.');
+    lines.push('# Example:');
+    lines.push('#   context: |');
+    lines.push('#     Tech stack: TypeScript, React, Node.js');
+    lines.push('#     We use conventional commits');
+    lines.push('#     Domain: e-commerce platform');
+    lines.push('');
+    // Rules section with comments
+    lines.push('# Per-artifact rules (optional)');
+    lines.push('# Add custom rules for specific artifacts.');
+    lines.push('# Example:');
+    lines.push('#   rules:');
+    lines.push('#     proposal:');
+    lines.push('#       - Keep proposals under 500 words');
+    lines.push('#       - Always include a "Non-goals" section');
+    lines.push('#     tasks:');
+    lines.push('#       - Break tasks into chunks of max 2 hours');
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=config-prompts.js.map

package/dist/core/config-schema.d.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+/**
+ * Zod schema for global OpenSpec configuration.
+ * Uses passthrough() to preserve unknown fields for forward compatibility.
+ */
+export declare const GlobalConfigSchema: z.ZodObject<{
+    featureFlags: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>>;
+    profile: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        core: "core";
+        custom: "custom";
+    }>>>;
+    delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        commands: "commands";
+        skills: "skills";
+        both: "both";
+    }>>>;
+    workflows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type GlobalConfigType = z.infer<typeof GlobalConfigSchema>;
+/**
+ * Default configuration values.
+ */
+export declare const DEFAULT_CONFIG: GlobalConfigType;
+/**
+ * Validate a config key path for CLI set operations.
+ * Unknown top-level keys are rejected unless explicitly allowed by the caller.
+ */
+export declare function validateConfigKeyPath(path: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Get a nested value from an object using dot notation.
+ *
+ * @param obj - The object to access
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns The value at the path, or undefined if not found
+ */
+export declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * Set a nested value in an object using dot notation.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @param value - The value to set
+ */
+export declare function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Delete a nested value from an object using dot notation.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns true if the key existed and was deleted, false otherwise
+ */
+export declare function deleteNestedValue(obj: Record<string, unknown>, path: string): boolean;
+/**
+ * Coerce a string value to its appropriate type.
+ * - "true" / "false" -> boolean
+ * - Numeric strings -> number
+ * - JSON arrays/objects -> parsed containers
+ * - Everything else -> string
+ *
+ * @param value - The string value to coerce
+ * @param forceString - If true, always return the value as a string
+ * @returns The coerced value
+ */
+export declare function coerceValue(value: string, forceString?: boolean): string | number | boolean | unknown[] | Record<string, unknown>;
+/**
+ * Format a value for YAML-like display.
+ *
+ * @param value - The value to format
+ * @param indent - Current indentation level
+ * @returns Formatted string
+ */
+export declare function formatValueYaml(value: unknown, indent?: number): string;
+/**
+ * Validate a configuration object against the schema.
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with success status and optional error message
+ */
+export declare function validateConfig(config: unknown): {
+    success: boolean;
+    error?: string;
+};
+//# sourceMappingURL=config-schema.d.ts.map