@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/parser/config.d.ts

@@ -0,0 +1,457 @@
+/**
+ * Project-level configuration for kspec.
+ *
+ * Loads kspec.config.yaml from the project root (main branch) before shadow
+ * branch detection. All fields are optional with backward-compatible defaults.
+ *
+ * Priority: env vars > config file > defaults
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * Complete schema for kspec.config.yaml.
+ *
+ * AC: @project-config ac-4 — unknown fields are ignored via passthrough
+ */
+export declare const KspecConfigSchema: z.ZodObject<{
+    /** Shadow branch configuration */
+    shadow: z.ZodOptional<z.ZodObject<{
+        /** Branch name for shadow branch (default: kspec-meta) */
+        branch: z.ZodOptional<z.ZodString>;
+        /** Worktree directory name (default: .kspec) */
+        directory: z.ZodOptional<z.ZodString>;
+        /**
+         * Remote target for shadow branch. Can be:
+         * - Named remote (e.g., "origin", "specs-origin")
+         * - Local filesystem path (starts with /, ./, or ~)
+         * - Git URL (contains :// or starts with git@)
+         */
+        remote: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        branch?: string | undefined;
+        directory?: string | undefined;
+        remote?: string | undefined;
+    }, {
+        branch?: string | undefined;
+        directory?: string | undefined;
+        remote?: string | undefined;
+    }>>;
+    /** Identity configuration */
+    identity: z.ZodOptional<z.ZodObject<{
+        /** Default author for notes/tasks (overridden by KSPEC_AUTHOR env var) */
+        author: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        author?: string | undefined;
+    }, {
+        author?: string | undefined;
+    }>>;
+    /** Validation configuration */
+    validation: z.ZodOptional<z.ZodObject<{
+        /**
+         * When true, dangling references are treated as errors instead of warnings.
+         * AC: @config-validation ac-2 ac-3 — strict_refs configurable
+         */
+        strict_refs: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * When true, specs missing acceptance criteria are reported as errors not warnings.
+         * AC: @config-validation ac-1 — require_acceptance configurable
+         */
+        require_acceptance: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        strict_refs?: boolean | undefined;
+        require_acceptance?: boolean | undefined;
+    }, {
+        strict_refs?: boolean | undefined;
+        require_acceptance?: boolean | undefined;
+    }>>;
+    /** Daemon configuration */
+    daemon: z.ZodOptional<z.ZodObject<{
+        /** Default port for daemon (default: 3456) */
+        port: z.ZodOptional<z.ZodNumber>;
+        /** Host to bind to (default: localhost) */
+        host: z.ZodOptional<z.ZodString>;
+        /**
+         * Whether to auto-start daemon when running kspec commands.
+         * AC: @config-daemon ac-3 — auto_start configurable
+         */
+        auto_start: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        auto_start?: boolean | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
+    }, {
+        auto_start?: boolean | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
+    }>>;
+    /** Ralph automation configuration */
+    ralph: z.ZodOptional<z.ZodObject<{
+        /** Skill invocation name overrides */
+        skills: z.ZodOptional<z.ZodObject<{
+            /** Skill invocation for task-work (default: /kspec:task-work) */
+            task_work: z.ZodOptional<z.ZodString>;
+            /** Skill invocation for reflect (default: /kspec:reflect) */
+            reflect: z.ZodOptional<z.ZodString>;
+            /** Skill invocation for PR review (default: /kspec:review) */
+            pr_review: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        }, {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        skills?: {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        } | undefined;
+    }, {
+        skills?: {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        } | undefined;
+    }>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** Shadow branch configuration */
+    shadow: z.ZodOptional<z.ZodObject<{
+        /** Branch name for shadow branch (default: kspec-meta) */
+        branch: z.ZodOptional<z.ZodString>;
+        /** Worktree directory name (default: .kspec) */
+        directory: z.ZodOptional<z.ZodString>;
+        /**
+         * Remote target for shadow branch. Can be:
+         * - Named remote (e.g., "origin", "specs-origin")
+         * - Local filesystem path (starts with /, ./, or ~)
+         * - Git URL (contains :// or starts with git@)
+         */
+        remote: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        branch?: string | undefined;
+        directory?: string | undefined;
+        remote?: string | undefined;
+    }, {
+        branch?: string | undefined;
+        directory?: string | undefined;
+        remote?: string | undefined;
+    }>>;
+    /** Identity configuration */
+    identity: z.ZodOptional<z.ZodObject<{
+        /** Default author for notes/tasks (overridden by KSPEC_AUTHOR env var) */
+        author: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        author?: string | undefined;
+    }, {
+        author?: string | undefined;
+    }>>;
+    /** Validation configuration */
+    validation: z.ZodOptional<z.ZodObject<{
+        /**
+         * When true, dangling references are treated as errors instead of warnings.
+         * AC: @config-validation ac-2 ac-3 — strict_refs configurable
+         */
+        strict_refs: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * When true, specs missing acceptance criteria are reported as errors not warnings.
+         * AC: @config-validation ac-1 — require_acceptance configurable
+         */
+        require_acceptance: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        strict_refs?: boolean | undefined;
+        require_acceptance?: boolean | undefined;
+    }, {
+        strict_refs?: boolean | undefined;
+        require_acceptance?: boolean | undefined;
+    }>>;
+    /** Daemon configuration */
+    daemon: z.ZodOptional<z.ZodObject<{
+        /** Default port for daemon (default: 3456) */
+        port: z.ZodOptional<z.ZodNumber>;
+        /** Host to bind to (default: localhost) */
+        host: z.ZodOptional<z.ZodString>;
+        /**
+         * Whether to auto-start daemon when running kspec commands.
+         * AC: @config-daemon ac-3 — auto_start configurable
+         */
+        auto_start: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        auto_start?: boolean | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
+    }, {
+        auto_start?: boolean | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
+    }>>;
+    /** Ralph automation configuration */
+    ralph: z.ZodOptional<z.ZodObject<{
+        /** Skill invocation name overrides */
+        skills: z.ZodOptional<z.ZodObject<{
+            /** Skill invocation for task-work (default: /kspec:task-work) */
+            task_work: z.ZodOptional<z.ZodString>;
+            /** Skill invocation for reflect (default: /kspec:reflect) */
+            reflect: z.ZodOptional<z.ZodString>;
+            /** Skill invocation for PR review (default: /kspec:review) */
+            pr_review: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        }, {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        skills?: {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        } | undefined;
+    }, {
+        skills?: {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        } | undefined;
+    }>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** Shadow branch configuration */
+    shadow: z.ZodOptional<z.ZodObject<{
+        /** Branch name for shadow branch (default: kspec-meta) */
+        branch: z.ZodOptional<z.ZodString>;
+        /** Worktree directory name (default: .kspec) */
+        directory: z.ZodOptional<z.ZodString>;
+        /**
+         * Remote target for shadow branch. Can be:
+         * - Named remote (e.g., "origin", "specs-origin")
+         * - Local filesystem path (starts with /, ./, or ~)
+         * - Git URL (contains :// or starts with git@)
+         */
+        remote: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        branch?: string | undefined;
+        directory?: string | undefined;
+        remote?: string | undefined;
+    }, {
+        branch?: string | undefined;
+        directory?: string | undefined;
+        remote?: string | undefined;
+    }>>;
+    /** Identity configuration */
+    identity: z.ZodOptional<z.ZodObject<{
+        /** Default author for notes/tasks (overridden by KSPEC_AUTHOR env var) */
+        author: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        author?: string | undefined;
+    }, {
+        author?: string | undefined;
+    }>>;
+    /** Validation configuration */
+    validation: z.ZodOptional<z.ZodObject<{
+        /**
+         * When true, dangling references are treated as errors instead of warnings.
+         * AC: @config-validation ac-2 ac-3 — strict_refs configurable
+         */
+        strict_refs: z.ZodOptional<z.ZodBoolean>;
+        /**
+         * When true, specs missing acceptance criteria are reported as errors not warnings.
+         * AC: @config-validation ac-1 — require_acceptance configurable
+         */
+        require_acceptance: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        strict_refs?: boolean | undefined;
+        require_acceptance?: boolean | undefined;
+    }, {
+        strict_refs?: boolean | undefined;
+        require_acceptance?: boolean | undefined;
+    }>>;
+    /** Daemon configuration */
+    daemon: z.ZodOptional<z.ZodObject<{
+        /** Default port for daemon (default: 3456) */
+        port: z.ZodOptional<z.ZodNumber>;
+        /** Host to bind to (default: localhost) */
+        host: z.ZodOptional<z.ZodString>;
+        /**
+         * Whether to auto-start daemon when running kspec commands.
+         * AC: @config-daemon ac-3 — auto_start configurable
+         */
+        auto_start: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        auto_start?: boolean | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
+    }, {
+        auto_start?: boolean | undefined;
+        port?: number | undefined;
+        host?: string | undefined;
+    }>>;
+    /** Ralph automation configuration */
+    ralph: z.ZodOptional<z.ZodObject<{
+        /** Skill invocation name overrides */
+        skills: z.ZodOptional<z.ZodObject<{
+            /** Skill invocation for task-work (default: /kspec:task-work) */
+            task_work: z.ZodOptional<z.ZodString>;
+            /** Skill invocation for reflect (default: /kspec:reflect) */
+            reflect: z.ZodOptional<z.ZodString>;
+            /** Skill invocation for PR review (default: /kspec:review) */
+            pr_review: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        }, {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        skills?: {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        } | undefined;
+    }, {
+        skills?: {
+            task_work?: string | undefined;
+            reflect?: string | undefined;
+            pr_review?: string | undefined;
+        } | undefined;
+    }>>;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * Raw config type as parsed from YAML file.
+ */
+export type KspecConfig = z.infer<typeof KspecConfigSchema>;
+/**
+ * Remote type for shadow branch configuration.
+ * - "named": Git remote name (e.g., "origin", "specs-origin")
+ * - "path": Local filesystem path
+ * - "url": Git URL (https://, git@, etc.)
+ */
+export type ShadowRemoteType = "named" | "path" | "url";
+/**
+ * Resolved shadow remote configuration.
+ */
+export interface ResolvedShadowRemote {
+    /** The remote value from config */
+    value: string;
+    /** Detected type of the remote */
+    type: ShadowRemoteType;
+}
+/**
+ * Detect the type of a shadow remote string.
+ *
+ * AC: @config-shadow ac-3 ac-4 ac-5 — remote type detection
+ *
+ * @param remote Remote string from config
+ * @returns Detected type: "path" for filesystem, "url" for git URLs, "named" for git remote names
+ */
+export declare function detectRemoteType(remote: string): ShadowRemoteType;
+/**
+ * Resolved config with all values finalized (env vars applied, defaults filled).
+ */
+export interface ResolvedKspecConfig {
+    shadow: {
+        /** Branch name (default: kspec-meta) */
+        branch: string;
+        /** Worktree directory name (default: .kspec) */
+        directory: string;
+        /** Remote configuration, null if not specified */
+        remote: ResolvedShadowRemote | null;
+    };
+    identity: {
+        author: string | null;
+    };
+    validation: {
+        /**
+         * When true, dangling references are treated as errors instead of warnings.
+         * AC: @config-validation ac-2 ac-3
+         */
+        strict_refs: boolean;
+        /**
+         * When true, specs missing acceptance criteria are reported as errors not warnings.
+         * AC: @config-validation ac-1
+         */
+        require_acceptance: boolean;
+    };
+    daemon: {
+        port: number;
+        host: string;
+        /**
+         * Whether to auto-start daemon when running kspec commands.
+         * AC: @config-daemon ac-3
+         */
+        auto_start: boolean;
+    };
+    ralph: {
+        skills: {
+            /** Skill invocation for task-work (default: /kspec:task-work) */
+            task_work: string;
+            /** Skill invocation for reflect (default: /kspec:reflect) */
+            reflect: string;
+            /** Skill invocation for PR review (default: /kspec:review) */
+            pr_review: string;
+        };
+    };
+}
+/**
+ * Result of loading project config.
+ */
+export interface LoadConfigResult {
+    /** Resolved configuration with all values finalized */
+    config: ResolvedKspecConfig;
+    /** Path to config file if found, null otherwise */
+    configPath: string | null;
+    /** Warning message if config had issues but was recoverable */
+    warning: string | null;
+    /** The git root directory where config was loaded from */
+    gitRoot: string | null;
+}
+/**
+ * Find git root directory, handling KSPEC_SPEC_DIR batch mode.
+ *
+ * AC: @project-config ac-7 — in batch mode, we need the REAL project root
+ *
+ * When KSPEC_SPEC_DIR is set (batch atomic mode), the cwd might be the temp
+ * directory. We need to find the real project root by checking:
+ * 1. If KSPEC_BATCH_PROJECT_ROOT is set, use that (set by batch executor)
+ * 2. Otherwise, use git root from cwd
+ *
+ * AC: @project-config ac-6 — loads from git root, not cwd subdirectory
+ */
+export declare function findProjectRoot(startDir: string): string | null;
+/**
+ * Load project configuration from kspec.config.yaml.
+ *
+ * AC: @project-config ac-1 — no config = all defaults
+ * AC: @project-config ac-2 — config parsed and available before shadow detection
+ * AC: @project-config ac-3 — invalid YAML = defaults + warning
+ * AC: @project-config ac-4 — unknown fields ignored
+ * AC: @project-config ac-5 — env vars take precedence
+ * AC: @project-config ac-6 — loads from git root
+ * AC: @project-config ac-7 — batch mode uses real project root
+ *
+ * @param startDir Starting directory for git root detection
+ */
+export declare function loadProjectConfig(startDir?: string): Promise<LoadConfigResult>;
+/**
+ * Resolve configuration by merging file config with env vars and defaults.
+ *
+ * Priority: env vars > config file > defaults
+ *
+ * AC: @project-config ac-5 — env vars take precedence
+ */
+export declare function resolveConfig(fileConfig: KspecConfig | null): ResolvedKspecConfig;
+/**
+ * Get the default configuration (no file, no env vars).
+ * Useful for testing or when config loading fails completely.
+ * Returns a deep copy to prevent mutation of shared defaults.
+ */
+export declare function getDefaultConfig(): ResolvedKspecConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/parser/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/parser/config.ts"],"names":[],"mappings":"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"}