@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/sessions/legacy.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Legacy session detection, warning, and migration.
+ *
+ * No transparent fallback reads — all session reads go directly to
+ * .kspec-sessions/. When legacy sessions exist in .kspec/sessions/,
+ * a warning is emitted advising the user to run `kspec session migrate`.
+ *
+ * AC: @session-legacy-migration ac-read-fallback ac-no-write ac-list-merge ac-deprecation-warning
+ */
+/**
+ * Get the legacy sessions directory path (.kspec/sessions/).
+ *
+ * @param specDir - The .kspec/ directory (shadow branch worktree)
+ * @returns Path to legacy sessions directory, or null if specDir is not available
+ */
+export declare function getLegacySessionsDir(specDir: string | undefined): string | null;
+/**
+ * Check if a legacy sessions directory exists and has session subdirectories.
+ */
+export declare function hasLegacySessions(specDir: string | undefined): Promise<boolean>;
+/**
+ * Count legacy sessions that haven't been migrated yet.
+ *
+ * @returns Number of session directories in .kspec/sessions/
+ */
+export declare function countLegacySessions(specDir: string | undefined): Promise<number>;
+/**
+ * Emit a deprecation warning to stderr for legacy sessions detected.
+ * AC: @session-legacy-migration ac-deprecation-warning
+ *
+ * Emits once per process to avoid spam. Writes to stderr, not stdout,
+ * so it doesn't interfere with structured output.
+ *
+ * @param count - Number of legacy sessions found (included in warning message)
+ */
+export declare function emitLegacyDeprecationWarning(count?: number): void;
+/**
+ * Reset the deprecation warning state (for testing).
+ */
+export declare function resetDeprecationWarning(): void;
+/**
+ * Check for legacy sessions and emit a warning if found.
+ * AC: @session-legacy-migration ac-read-fallback ac-deprecation-warning
+ *
+ * Convenience function that combines hasLegacySessions + countLegacySessions
+ * + emitLegacyDeprecationWarning. Call this at the start of session read
+ * operations to detect-and-warn without performing any fallback reads.
+ *
+ * @returns true if legacy sessions were detected (warning was emitted)
+ */
+export declare function warnIfLegacySessions(specDir: string | undefined): Promise<boolean>;
+/**
+ * Result of a session migration operation.
+ * AC: @session-legacy-migration ac-migration-copy ac-migration-idempotent
+ */
+export interface MigrationResult {
+    /** Number of sessions copied */
+    migrated: number;
+    /** Number of sessions skipped (already exist in target) */
+    skipped: number;
+    /** Session IDs that were migrated */
+    migratedIds: string[];
+    /** Session IDs that were skipped */
+    skippedIds: string[];
+}
+/**
+ * Copy session directories from legacy to primary location.
+ *
+ * AC: @session-legacy-migration ac-migration-copy
+ * Copies session directories from .kspec/sessions/ to .kspec-sessions/.
+ * Does not delete originals.
+ *
+ * AC: @session-legacy-migration ac-migration-idempotent
+ * Skips sessions that already exist in target.
+ */
+export declare function migrateLegacySessions(sessionsDir: string, specDir: string): Promise<MigrationResult>;
+//# sourceMappingURL=legacy.d.ts.map

package/dist/sessions/legacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy.d.ts","sourceRoot":"","sources":["../../src/sessions/legacy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAGf;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAAC,MAAM,CAAC,CAYjB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CASjE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAAC,OAAO,CAAC,CAOlB;AAID;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,oCAAoC;IACpC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,CAAC,CAoC1B"}

package/dist/sessions/legacy.js

@@ -0,0 +1,146 @@
+/**
+ * Legacy session detection, warning, and migration.
+ *
+ * No transparent fallback reads — all session reads go directly to
+ * .kspec-sessions/. When legacy sessions exist in .kspec/sessions/,
+ * a warning is emitted advising the user to run `kspec session migrate`.
+ *
+ * AC: @session-legacy-migration ac-read-fallback ac-no-write ac-list-merge ac-deprecation-warning
+ */
+import * as path from "node:path";
+import * as fsPromises from "node:fs/promises";
+import { listSessions, } from "./store.js";
+// ─── Legacy Path Resolution ─────────────────────────────────────────────────
+/**
+ * Get the legacy sessions directory path (.kspec/sessions/).
+ *
+ * @param specDir - The .kspec/ directory (shadow branch worktree)
+ * @returns Path to legacy sessions directory, or null if specDir is not available
+ */
+export function getLegacySessionsDir(specDir) {
+    if (!specDir)
+        return null;
+    return path.join(specDir, "sessions");
+}
+/**
+ * Check if a legacy sessions directory exists and has session subdirectories.
+ */
+export async function hasLegacySessions(specDir) {
+    const legacyDir = getLegacySessionsDir(specDir);
+    if (!legacyDir)
+        return false;
+    try {
+        const entries = await fsPromises.readdir(legacyDir, {
+            withFileTypes: true,
+        });
+        return entries.some((e) => e.isDirectory());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Count legacy sessions that haven't been migrated yet.
+ *
+ * @returns Number of session directories in .kspec/sessions/
+ */
+export async function countLegacySessions(specDir) {
+    const legacyDir = getLegacySessionsDir(specDir);
+    if (!legacyDir)
+        return 0;
+    try {
+        const entries = await fsPromises.readdir(legacyDir, {
+            withFileTypes: true,
+        });
+        return entries.filter((e) => e.isDirectory()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+// ─── Deprecation Warning ────────────────────────────────────────────────────
+let deprecationWarningEmitted = false;
+/**
+ * Emit a deprecation warning to stderr for legacy sessions detected.
+ * AC: @session-legacy-migration ac-deprecation-warning
+ *
+ * Emits once per process to avoid spam. Writes to stderr, not stdout,
+ * so it doesn't interfere with structured output.
+ *
+ * @param count - Number of legacy sessions found (included in warning message)
+ */
+export function emitLegacyDeprecationWarning(count) {
+    if (!deprecationWarningEmitted) {
+        const countMsg = count !== undefined ? `${count} legacy session(s) found` : "Legacy sessions found";
+        console.error(`Warning: ${countMsg} in .kspec/sessions/. ` +
+            "Run `kspec session migrate` to move them to .kspec-sessions/.");
+        deprecationWarningEmitted = true;
+    }
+}
+/**
+ * Reset the deprecation warning state (for testing).
+ */
+export function resetDeprecationWarning() {
+    deprecationWarningEmitted = false;
+}
+/**
+ * Check for legacy sessions and emit a warning if found.
+ * AC: @session-legacy-migration ac-read-fallback ac-deprecation-warning
+ *
+ * Convenience function that combines hasLegacySessions + countLegacySessions
+ * + emitLegacyDeprecationWarning. Call this at the start of session read
+ * operations to detect-and-warn without performing any fallback reads.
+ *
+ * @returns true if legacy sessions were detected (warning was emitted)
+ */
+export async function warnIfLegacySessions(specDir) {
+    const count = await countLegacySessions(specDir);
+    if (count > 0) {
+        emitLegacyDeprecationWarning(count);
+        return true;
+    }
+    return false;
+}
+/**
+ * Copy session directories from legacy to primary location.
+ *
+ * AC: @session-legacy-migration ac-migration-copy
+ * Copies session directories from .kspec/sessions/ to .kspec-sessions/.
+ * Does not delete originals.
+ *
+ * AC: @session-legacy-migration ac-migration-idempotent
+ * Skips sessions that already exist in target.
+ */
+export async function migrateLegacySessions(sessionsDir, specDir) {
+    const legacyDir = getLegacySessionsDir(specDir);
+    if (!legacyDir) {
+        return { migrated: 0, skipped: 0, migratedIds: [], skippedIds: [] };
+    }
+    const legacyIds = await listSessions(legacyDir);
+    if (legacyIds.length === 0) {
+        return { migrated: 0, skipped: 0, migratedIds: [], skippedIds: [] };
+    }
+    const primaryIds = new Set(await listSessions(sessionsDir));
+    const result = {
+        migrated: 0,
+        skipped: 0,
+        migratedIds: [],
+        skippedIds: [],
+    };
+    for (const id of legacyIds) {
+        if (primaryIds.has(id)) {
+            // AC: ac-migration-idempotent — skip existing
+            result.skipped++;
+            result.skippedIds.push(id);
+            continue;
+        }
+        // Copy entire session directory recursively
+        const srcDir = path.join(legacyDir, id);
+        const destDir = path.join(sessionsDir, id);
+        await fsPromises.cp(srcDir, destDir, { recursive: true });
+        result.migrated++;
+        result.migratedIds.push(id);
+    }
+    return result;
+}
+//# sourceMappingURL=legacy.js.map

package/dist/sessions/legacy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy.js","sourceRoot":"","sources":["../../src/sessions/legacy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA2B;IAE3B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAA2B;IAE3B,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAE7B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE;YAClD,aAAa,EAAE,IAAI;SACpB,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAA2B;IAE3B,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,CAAC,SAAS;QAAE,OAAO,CAAC,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE;YAClD,aAAa,EAAE,IAAI;SACpB,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,+EAA+E;AAE/E,IAAI,yBAAyB,GAAG,KAAK,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,IAAI,CAAC,yBAAyB,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,0BAA0B,CAAC,CAAC,CAAC,uBAAuB,CAAC;QACpG,OAAO,CAAC,KAAK,CACX,YAAY,QAAQ,wBAAwB;YAC5C,+DAA+D,CAChE,CAAC;QACF,yBAAyB,GAAG,IAAI,CAAC;IACnC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,yBAAyB,GAAG,KAAK,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAA2B;IAE3B,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACjD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,4BAA4B,CAAC,KAAK,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAmBD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,WAAmB,EACnB,OAAe;IAEf,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IACtE,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IACtE,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAoB;QAC9B,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,EAAE;QACf,UAAU,EAAE,EAAE;KACf,CAAC;IAEF,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACvB,8CAA8C;YAC9C,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,4CAA4C;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAC3C,MAAM,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}