@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/parser/plans.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Plan manifest loading and operations.
+ *
+ * Plans are durable artifacts that capture implementation context before
+ * translating to specs and tasks. They persist in project.plans.yaml.
+ *
+ * AC: @plan-crud ac-1 - Plans stored in project.plans.yaml
+ */
+import { type Plan, type PlanInput } from "../schema/index.js";
+import type { KspecContext } from "./yaml.js";
+/**
+ * Loaded plan with runtime metadata
+ */
+export interface LoadedPlan extends Plan {
+    _sourceFile?: string;
+}
+/**
+ * Get the plans file path.
+ * AC: @plan-crud ac-1 - stored in project.plans.yaml
+ */
+export declare function getPlansFilePath(ctx: KspecContext): string;
+/**
+ * Load all plans from the project.
+ * AC: @plan-crud ac-7, ac-31 - listing plans
+ */
+export declare function loadPlans(ctx: KspecContext): Promise<LoadedPlan[]>;
+/**
+ * Find a plan by reference (ULID, short ULID, or slug)
+ * AC: @plan-crud ac-8 - get plan by reference
+ */
+export declare function findPlanByRef(ctx: KspecContext, ref: string): Promise<LoadedPlan | undefined>;
+/**
+ * Create a new plan from input
+ * AC: @plan-crud ac-1, ac-2 - creating plans
+ */
+export declare function createPlan(input: PlanInput, author?: string): Plan;
+/**
+ * Save a single plan (create or update)
+ * AC: @plan-crud ac-1, ac-3 - save plan changes
+ * Uses file lock to prevent TOCTOU race on concurrent writes.
+ */
+export declare function savePlan(ctx: KspecContext, plan: LoadedPlan): Promise<void>;
+/**
+ * Delete a plan by ULID
+ */
+export declare function deletePlan(ctx: KspecContext, planUlid: string): Promise<boolean>;
+/**
+ * Filter plans by status
+ * AC: @plan-crud ac-7 - list with status filter
+ */
+export declare function filterPlansByStatus(plans: LoadedPlan[], status?: string): LoadedPlan[];
+/**
+ * Get plan statistics
+ */
+export declare function getPlanStats(plans: LoadedPlan[]): {
+    total: number;
+    byStatus: Record<string, number>;
+};
+//# sourceMappingURL=plans.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../../src/parser/plans.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EACL,KAAK,IAAI,EACT,KAAK,SAAS,EAIf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAO9C;;GAEG;AACH,MAAM,WAAW,UAAW,SAAQ,IAAI;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAE1D;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAqBxE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAajC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAiBlE;AAyED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CA0BlB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,EAAE,CAGd;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAWA"}

package/dist/parser/plans.js

@@ -0,0 +1,239 @@
+/**
+ * Plan manifest loading and operations.
+ *
+ * Plans are durable artifacts that capture implementation context before
+ * translating to specs and tasks. They persist in project.plans.yaml.
+ *
+ * AC: @plan-crud ac-1 - Plans stored in project.plans.yaml
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { ulid } from "ulid";
+import { PlansFileSchema, } from "../schema/index.js";
+import { readYamlFile, writeYamlFilePreserveFormat, } from "./yaml.js";
+/**
+ * Get the plans file path.
+ * AC: @plan-crud ac-1 - stored in project.plans.yaml
+ */
+export function getPlansFilePath(ctx) {
+    return path.join(ctx.specDir, "project.plans.yaml");
+}
+/**
+ * Load all plans from the project.
+ * AC: @plan-crud ac-7, ac-31 - listing plans
+ */
+export async function loadPlans(ctx) {
+    const plansPath = getPlansFilePath(ctx);
+    try {
+        const raw = await readYamlFile(plansPath);
+        // Validate and parse plans file
+        const parsed = PlansFileSchema.safeParse(raw);
+        if (!parsed.success) {
+            return [];
+        }
+        // Add source file metadata to each plan
+        return parsed.data.plans.map((plan) => ({
+            ...plan,
+            _sourceFile: plansPath,
+        }));
+    }
+    catch {
+        // File doesn't exist or parse error
+        return [];
+    }
+}
+/**
+ * Find a plan by reference (ULID, short ULID, or slug)
+ * AC: @plan-crud ac-8 - get plan by reference
+ */
+export async function findPlanByRef(ctx, ref) {
+    const plans = await loadPlans(ctx);
+    const cleanRef = ref.startsWith("@") ? ref.slice(1) : ref;
+    return plans.find((p) => 
+    // Match full ULID
+    p._ulid === cleanRef ||
+        // Match short ULID (prefix)
+        p._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()) ||
+        // Match any slug
+        p.slugs.includes(cleanRef));
+}
+/**
+ * Create a new plan from input
+ * AC: @plan-crud ac-1, ac-2 - creating plans
+ */
+export function createPlan(input, author) {
+    const now = new Date().toISOString();
+    return {
+        _ulid: input._ulid ?? ulid(),
+        slugs: input.slugs ?? [],
+        title: input.title,
+        content: input.content ?? "",
+        status: input.status ?? "draft",
+        derived_tasks: input.derived_tasks ?? [],
+        derived_specs: input.derived_specs ?? [],
+        source_path: input.source_path ?? null,
+        created_at: input.created_at ?? now,
+        approved_at: input.approved_at ?? null,
+        completed_at: input.completed_at ?? null,
+        notes: input.notes ?? [],
+    };
+}
+/**
+ * Acquire a simple mkdir-based file lock. Returns a release function.
+ * Uses mkdir atomicity on POSIX filesystems to prevent concurrent writes.
+ * Writes PID to a file inside the lock dir for staleness detection.
+ */
+async function acquireLock(lockPath, timeoutMs = 5000) {
+    const pidFile = path.join(lockPath, "pid");
+    const start = Date.now();
+    while (true) {
+        try {
+            await fs.mkdir(lockPath);
+            // Write our PID for staleness detection
+            await fs.writeFile(pidFile, String(process.pid));
+            return async () => {
+                try {
+                    await fs.rm(lockPath, { recursive: true });
+                }
+                catch {
+                    // Lock already released
+                }
+            };
+        }
+        catch {
+            if (Date.now() - start > timeoutMs) {
+                // Check if lock holder is still alive before force-removing
+                let isStale = false;
+                try {
+                    const holderPid = parseInt(await fs.readFile(pidFile, "utf-8"), 10);
+                    if (!isNaN(holderPid)) {
+                        try {
+                            process.kill(holderPid, 0); // signal 0 = check existence
+                        }
+                        catch {
+                            isStale = true; // Process doesn't exist — lock is stale
+                        }
+                    }
+                    else {
+                        isStale = true; // Corrupt PID file
+                    }
+                }
+                catch {
+                    isStale = true; // No PID file — assume stale
+                }
+                if (isStale) {
+                    try {
+                        await fs.rm(lockPath, { recursive: true });
+                    }
+                    catch {
+                        // ignore
+                    }
+                    // Retry once after stale lock removal
+                    try {
+                        await fs.mkdir(lockPath);
+                        await fs.writeFile(pidFile, String(process.pid));
+                        return async () => {
+                            try {
+                                await fs.rm(lockPath, { recursive: true });
+                            }
+                            catch {
+                                // Lock already released
+                            }
+                        };
+                    }
+                    catch {
+                        throw new Error(`Failed to acquire lock: ${lockPath}`);
+                    }
+                }
+                throw new Error(`Lock held by active process, timeout after ${timeoutMs}ms: ${lockPath}`);
+            }
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    }
+}
+/**
+ * Save a single plan (create or update)
+ * AC: @plan-crud ac-1, ac-3 - save plan changes
+ * Uses file lock to prevent TOCTOU race on concurrent writes.
+ */
+export async function savePlan(ctx, plan) {
+    const plansPath = getPlansFilePath(ctx);
+    const lockPath = `${plansPath}.lock`;
+    // Ensure directory exists
+    const dir = path.dirname(plansPath);
+    await fs.mkdir(dir, { recursive: true });
+    // Acquire lock for atomic read-modify-write
+    const releaseLock = await acquireLock(lockPath);
+    try {
+        // Load existing plans (inside lock to prevent TOCTOU)
+        const plans = await loadPlans(ctx);
+        // Strip runtime metadata before saving
+        const { _sourceFile, ...cleanPlan } = plan;
+        // Update or add
+        const existingIndex = plans.findIndex((p) => p._ulid === plan._ulid);
+        if (existingIndex >= 0) {
+            plans[existingIndex] = cleanPlan;
+        }
+        else {
+            plans.push(cleanPlan);
+        }
+        // Save back to file
+        const plansFile = {
+            kynetic_plans: "1.0",
+            plans: plans.map(({ _sourceFile, ...p }) => p),
+        };
+        await writeYamlFilePreserveFormat(plansPath, plansFile);
+    }
+    finally {
+        await releaseLock();
+    }
+}
+/**
+ * Delete a plan by ULID
+ */
+export async function deletePlan(ctx, planUlid) {
+    const plansPath = getPlansFilePath(ctx);
+    try {
+        const plans = await loadPlans(ctx);
+        // Find plan to delete
+        const index = plans.findIndex((p) => p._ulid === planUlid);
+        if (index < 0) {
+            return false;
+        }
+        // Remove plan
+        plans.splice(index, 1);
+        // Save back
+        const plansFile = {
+            kynetic_plans: "1.0",
+            plans: plans.map(({ _sourceFile, ...p }) => p),
+        };
+        await writeYamlFilePreserveFormat(plansPath, plansFile);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Filter plans by status
+ * AC: @plan-crud ac-7 - list with status filter
+ */
+export function filterPlansByStatus(plans, status) {
+    if (!status)
+        return plans;
+    return plans.filter((p) => p.status === status);
+}
+/**
+ * Get plan statistics
+ */
+export function getPlanStats(plans) {
+    const byStatus = {};
+    for (const plan of plans) {
+        byStatus[plan.status] = (byStatus[plan.status] ?? 0) + 1;
+    }
+    return {
+        total: plans.length,
+        byStatus,
+    };
+}
+//# sourceMappingURL=plans.js.map

package/dist/parser/plans.js.map

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

package/dist/parser/refs.d.ts

@@ -4,8 +4,9 @@
  * Handles resolution of @slug and @ulid references to actual items,
  * with proper error handling for not-found and ambiguous cases.
  */
-import type { LoadedSpecItem, LoadedTask, AnyLoadedItem } from './yaml.js';
-import type { LoadedMetaItem } from './meta.js';
+import type { LoadedMetaItem } from "./meta.js";
+import type { LoadedPlan } from "./plans.js";
+import type { AnyLoadedItem, LoadedSpecItem, LoadedTask } from "./yaml.js";
 /**
  * Successful resolution result
  * AC: @agent-definitions ac-agent-3
@@ -15,14 +16,14 @@ export interface ResolveSuccess {
     ulid: string;
     item: AnyLoadedItem | LoadedMetaItem;
     /** How the reference was matched */
-    matchType: 'slug' | 'ulid-full' | 'ulid-prefix';
+    matchType: "slug" | "ulid-full" | "ulid-prefix";
 }
 /**
  * Failed resolution - reference not found
  */
 export interface ResolveNotFound {
     ok: false;
-    error: 'not_found';
+    error: "not_found";
     ref: string;
 }
 /**
@@ -30,7 +31,7 @@ export interface ResolveNotFound {
  */
 export interface ResolveAmbiguous {
     ok: false;
-    error: 'ambiguous';
+    error: "ambiguous";
     ref: string;
     /** The matching ULIDs */
     candidates: string[];
@@ -40,7 +41,7 @@ export interface ResolveAmbiguous {
  */
 export interface ResolveDuplicateSlug {
     ok: false;
-    error: 'duplicate_slug';
+    error: "duplicate_slug";
     ref: string;
     /** The ULIDs that share this slug */
     candidates: string[];
@@ -59,7 +60,7 @@ export interface RefValidationError {
     /** The field containing this reference */
     field: string;
     /** Error type */
-    error: 'not_found' | 'ambiguous' | 'duplicate_slug';
+    error: "not_found" | "ambiguous" | "duplicate_slug";
     /** Additional context */
     message: string;
 }
@@ -76,7 +77,7 @@ export interface RefValidationWarning {
     /** The field containing this reference */
     field: string;
     /** Warning type */
-    warning: 'deprecated_target';
+    warning: "deprecated_target";
     /** Additional context */
     message: string;
 }
@@ -95,9 +96,15 @@ export declare class ReferenceIndex {
     /**
      * Build index from loaded items and meta items
      * AC: @agent-definitions ac-agent-3
+     * AC: @plan-validation ac-10
      */
-    constructor(tasks: LoadedTask[], items: LoadedSpecItem[], metaItems?: LoadedMetaItem[]);
+    constructor(tasks: LoadedTask[], items: LoadedSpecItem[], metaItems?: LoadedMetaItem[], plans?: LoadedPlan[]);
     private indexItem;
+    /**
+     * Index a plan
+     * AC: @plan-validation ac-10
+     */
+    private indexPlan;
     /**
      * Index a meta item (agent, workflow, convention, observation)
      * Meta items use 'id' field as their slug
@@ -113,6 +120,12 @@ export declare class ReferenceIndex {
      * 3. ULID prefix match (must be unique)
      */
     resolve(ref: string): ResolveResult;
+    /**
+     * Check if a slug is available (not used by any indexed item).
+     * Returns true only when the slug is completely unused.
+     * A slug is unavailable if it resolves to an item, is ambiguous, or is duplicated.
+     */
+    isSlugAvailable(slug: string): boolean;
     /**
      * Get an item by exact ULID (no resolution, direct lookup)
      */

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

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