cc4pm 1.8.0

package/scripts/lib/session-adapters/canonical-session.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const path = require('path');
+
+const SESSION_SCHEMA_VERSION = 'ecc.session.v1';
+
+function buildAggregates(workers) {
+  const states = workers.reduce((accumulator, worker) => {
+    const state = worker.state || 'unknown';
+    accumulator[state] = (accumulator[state] || 0) + 1;
+    return accumulator;
+  }, {});
+
+  return {
+    workerCount: workers.length,
+    states
+  };
+}
+
+function deriveDmuxSessionState(snapshot) {
+  if (snapshot.sessionActive) {
+    return 'active';
+  }
+
+  if (snapshot.workerCount > 0) {
+    return 'idle';
+  }
+
+  return 'missing';
+}
+
+function normalizeDmuxSnapshot(snapshot, sourceTarget) {
+  const workers = (snapshot.workers || []).map(worker => ({
+    id: worker.workerSlug,
+    label: worker.workerSlug,
+    state: worker.status.state || 'unknown',
+    branch: worker.status.branch || null,
+    worktree: worker.status.worktree || null,
+    runtime: {
+      kind: 'tmux-pane',
+      command: worker.pane ? worker.pane.currentCommand || null : null,
+      pid: worker.pane ? worker.pane.pid || null : null,
+      active: worker.pane ? Boolean(worker.pane.active) : false,
+      dead: worker.pane ? Boolean(worker.pane.dead) : false,
+    },
+    intent: {
+      objective: worker.task.objective || '',
+      seedPaths: Array.isArray(worker.task.seedPaths) ? worker.task.seedPaths : []
+    },
+    outputs: {
+      summary: Array.isArray(worker.handoff.summary) ? worker.handoff.summary : [],
+      validation: Array.isArray(worker.handoff.validation) ? worker.handoff.validation : [],
+      remainingRisks: Array.isArray(worker.handoff.remainingRisks) ? worker.handoff.remainingRisks : []
+    },
+    artifacts: {
+      statusFile: worker.files.status,
+      taskFile: worker.files.task,
+      handoffFile: worker.files.handoff
+    }
+  }));
+
+  return {
+    schemaVersion: SESSION_SCHEMA_VERSION,
+    adapterId: 'dmux-tmux',
+    session: {
+      id: snapshot.sessionName,
+      kind: 'orchestrated',
+      state: deriveDmuxSessionState(snapshot),
+      repoRoot: snapshot.repoRoot || null,
+      sourceTarget
+    },
+    workers,
+    aggregates: buildAggregates(workers)
+  };
+}
+
+function deriveClaudeWorkerId(session) {
+  if (session.shortId && session.shortId !== 'no-id') {
+    return session.shortId;
+  }
+
+  return path.basename(session.filename || session.sessionPath || 'session', '.tmp');
+}
+
+function normalizeClaudeHistorySession(session, sourceTarget) {
+  const metadata = session.metadata || {};
+  const workerId = deriveClaudeWorkerId(session);
+  const worker = {
+    id: workerId,
+    label: metadata.title || session.filename || workerId,
+    state: 'recorded',
+    branch: metadata.branch || null,
+    worktree: metadata.worktree || null,
+    runtime: {
+      kind: 'claude-session',
+      command: 'claude',
+      pid: null,
+      active: false,
+      dead: true,
+    },
+    intent: {
+      objective: metadata.inProgress && metadata.inProgress.length > 0
+        ? metadata.inProgress[0]
+        : (metadata.title || ''),
+      seedPaths: []
+    },
+    outputs: {
+      summary: Array.isArray(metadata.completed) ? metadata.completed : [],
+      validation: [],
+      remainingRisks: metadata.notes ? [metadata.notes] : []
+    },
+    artifacts: {
+      sessionFile: session.sessionPath,
+      context: metadata.context || null
+    }
+  };
+
+  return {
+    schemaVersion: SESSION_SCHEMA_VERSION,
+    adapterId: 'claude-history',
+    session: {
+      id: workerId,
+      kind: 'history',
+      state: 'recorded',
+      repoRoot: metadata.worktree || null,
+      sourceTarget
+    },
+    workers: [worker],
+    aggregates: buildAggregates([worker])
+  };
+}
+
+module.exports = {
+  SESSION_SCHEMA_VERSION,
+  buildAggregates,
+  normalizeClaudeHistorySession,
+  normalizeDmuxSnapshot
+};

package/scripts/lib/session-adapters/claude-history.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const sessionManager = require('../session-manager');
+const sessionAliases = require('../session-aliases');
+const { normalizeClaudeHistorySession } = require('./canonical-session');
+
+function parseClaudeTarget(target) {
+  if (typeof target !== 'string') {
+    return null;
+  }
+
+  for (const prefix of ['claude-history:', 'claude:', 'history:']) {
+    if (target.startsWith(prefix)) {
+      return target.slice(prefix.length).trim();
+    }
+  }
+
+  return null;
+}
+
+function isSessionFileTarget(target, cwd) {
+  if (typeof target !== 'string' || target.length === 0) {
+    return false;
+  }
+
+  const absoluteTarget = path.resolve(cwd, target);
+  return fs.existsSync(absoluteTarget)
+    && fs.statSync(absoluteTarget).isFile()
+    && absoluteTarget.endsWith('.tmp');
+}
+
+function hydrateSessionFromPath(sessionPath) {
+  const filename = path.basename(sessionPath);
+  const parsed = sessionManager.parseSessionFilename(filename);
+  if (!parsed) {
+    throw new Error(`Unsupported session file: ${sessionPath}`);
+  }
+
+  const content = sessionManager.getSessionContent(sessionPath);
+  const stats = fs.statSync(sessionPath);
+
+  return {
+    ...parsed,
+    sessionPath,
+    content,
+    metadata: sessionManager.parseSessionMetadata(content),
+    stats: sessionManager.getSessionStats(content || ''),
+    size: stats.size,
+    modifiedTime: stats.mtime,
+    createdTime: stats.birthtime || stats.ctime
+  };
+}
+
+function resolveSessionRecord(target, cwd) {
+  const explicitTarget = parseClaudeTarget(target);
+
+  if (explicitTarget) {
+    if (explicitTarget === 'latest') {
+      const [latest] = sessionManager.getAllSessions({ limit: 1 }).sessions;
+      if (!latest) {
+        throw new Error('No Claude session history found');
+      }
+
+      return {
+        session: sessionManager.getSessionById(latest.filename, true),
+        sourceTarget: {
+          type: 'claude-history',
+          value: 'latest'
+        }
+      };
+    }
+
+    const alias = sessionAliases.resolveAlias(explicitTarget);
+    if (alias) {
+      return {
+        session: hydrateSessionFromPath(alias.sessionPath),
+        sourceTarget: {
+          type: 'claude-alias',
+          value: explicitTarget
+        }
+      };
+    }
+
+    const session = sessionManager.getSessionById(explicitTarget, true);
+    if (!session) {
+      throw new Error(`Claude session not found: ${explicitTarget}`);
+    }
+
+    return {
+      session,
+      sourceTarget: {
+        type: 'claude-history',
+        value: explicitTarget
+      }
+    };
+  }
+
+  if (isSessionFileTarget(target, cwd)) {
+    return {
+      session: hydrateSessionFromPath(path.resolve(cwd, target)),
+      sourceTarget: {
+        type: 'session-file',
+        value: path.resolve(cwd, target)
+      }
+    };
+  }
+
+  throw new Error(`Unsupported Claude session target: ${target}`);
+}
+
+function createClaudeHistoryAdapter() {
+  return {
+    id: 'claude-history',
+    description: 'Claude local session history and session-file snapshots',
+    targetTypes: ['claude-history', 'claude-alias', 'session-file'],
+    canOpen(target, context = {}) {
+      if (context.adapterId && context.adapterId !== 'claude-history') {
+        return false;
+      }
+
+      if (context.adapterId === 'claude-history') {
+        return true;
+      }
+
+      const cwd = context.cwd || process.cwd();
+      return parseClaudeTarget(target) !== null || isSessionFileTarget(target, cwd);
+    },
+    open(target, context = {}) {
+      const cwd = context.cwd || process.cwd();
+
+      return {
+        adapterId: 'claude-history',
+        getSnapshot() {
+          const { session, sourceTarget } = resolveSessionRecord(target, cwd);
+          return normalizeClaudeHistorySession(session, sourceTarget);
+        }
+      };
+    }
+  };
+}
+
+module.exports = {
+  createClaudeHistoryAdapter,
+  isSessionFileTarget,
+  parseClaudeTarget
+};

package/scripts/lib/session-adapters/dmux-tmux.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { collectSessionSnapshot } = require('../orchestration-session');
+const { normalizeDmuxSnapshot } = require('./canonical-session');
+
+function isPlanFileTarget(target, cwd) {
+  if (typeof target !== 'string' || target.length === 0) {
+    return false;
+  }
+
+  const absoluteTarget = path.resolve(cwd, target);
+  return fs.existsSync(absoluteTarget)
+    && fs.statSync(absoluteTarget).isFile()
+    && path.extname(absoluteTarget) === '.json';
+}
+
+function isSessionNameTarget(target, cwd) {
+  if (typeof target !== 'string' || target.length === 0) {
+    return false;
+  }
+
+  const coordinationDir = path.resolve(cwd, '.claude', 'orchestration', target);
+  return fs.existsSync(coordinationDir) && fs.statSync(coordinationDir).isDirectory();
+}
+
+function buildSourceTarget(target, cwd) {
+  if (isPlanFileTarget(target, cwd)) {
+    return {
+      type: 'plan',
+      value: path.resolve(cwd, target)
+    };
+  }
+
+  return {
+    type: 'session',
+    value: target
+  };
+}
+
+function createDmuxTmuxAdapter(options = {}) {
+  const collectSessionSnapshotImpl = options.collectSessionSnapshotImpl || collectSessionSnapshot;
+
+  return {
+    id: 'dmux-tmux',
+    description: 'Tmux/worktree orchestration snapshots from plan files or session names',
+    targetTypes: ['plan', 'session'],
+    canOpen(target, context = {}) {
+      if (context.adapterId && context.adapterId !== 'dmux-tmux') {
+        return false;
+      }
+
+      if (context.adapterId === 'dmux-tmux') {
+        return true;
+      }
+
+      const cwd = context.cwd || process.cwd();
+      return isPlanFileTarget(target, cwd) || isSessionNameTarget(target, cwd);
+    },
+    open(target, context = {}) {
+      const cwd = context.cwd || process.cwd();
+
+      return {
+        adapterId: 'dmux-tmux',
+        getSnapshot() {
+          const snapshot = collectSessionSnapshotImpl(target, cwd);
+          return normalizeDmuxSnapshot(snapshot, buildSourceTarget(target, cwd));
+        }
+      };
+    }
+  };
+}
+
+module.exports = {
+  createDmuxTmuxAdapter,
+  isPlanFileTarget,
+  isSessionNameTarget
+};

package/scripts/lib/session-adapters/registry.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { createClaudeHistoryAdapter } = require('./claude-history');
+const { createDmuxTmuxAdapter } = require('./dmux-tmux');
+
+const TARGET_TYPE_TO_ADAPTER_ID = Object.freeze({
+  plan: 'dmux-tmux',
+  session: 'dmux-tmux',
+  'claude-history': 'claude-history',
+  'claude-alias': 'claude-history',
+  'session-file': 'claude-history'
+});
+
+function createDefaultAdapters() {
+  return [
+    createClaudeHistoryAdapter(),
+    createDmuxTmuxAdapter()
+  ];
+}
+
+function coerceTargetValue(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error('Structured session targets require a non-empty string value');
+  }
+
+  return value.trim();
+}
+
+function normalizeStructuredTarget(target, context = {}) {
+  if (!target || typeof target !== 'object' || Array.isArray(target)) {
+    return {
+      target,
+      context: { ...context }
+    };
+  }
+
+  const value = coerceTargetValue(target.value);
+  const type = typeof target.type === 'string' ? target.type.trim() : '';
+  if (type.length === 0) {
+    throw new Error('Structured session targets require a non-empty type');
+  }
+
+  const adapterId = target.adapterId || TARGET_TYPE_TO_ADAPTER_ID[type] || context.adapterId || null;
+  const nextContext = {
+    ...context,
+    adapterId
+  };
+
+  if (type === 'claude-history' || type === 'claude-alias') {
+    return {
+      target: `claude:${value}`,
+      context: nextContext
+    };
+  }
+
+  return {
+    target: value,
+    context: nextContext
+  };
+}
+
+function createAdapterRegistry(options = {}) {
+  const adapters = options.adapters || createDefaultAdapters();
+
+  return {
+    adapters,
+    getAdapter(id) {
+      const adapter = adapters.find(candidate => candidate.id === id);
+      if (!adapter) {
+        throw new Error(`Unknown session adapter: ${id}`);
+      }
+
+      return adapter;
+    },
+    listAdapters() {
+      return adapters.map(adapter => ({
+        id: adapter.id,
+        description: adapter.description || '',
+        targetTypes: Array.isArray(adapter.targetTypes) ? [...adapter.targetTypes] : []
+      }));
+    },
+    select(target, context = {}) {
+      const normalized = normalizeStructuredTarget(target, context);
+      const adapter = normalized.context.adapterId
+        ? this.getAdapter(normalized.context.adapterId)
+        : adapters.find(candidate => candidate.canOpen(normalized.target, normalized.context));
+      if (!adapter) {
+        throw new Error(`No session adapter matched target: ${target}`);
+      }
+
+      return adapter;
+    },
+    open(target, context = {}) {
+      const normalized = normalizeStructuredTarget(target, context);
+      const adapter = this.select(normalized.target, normalized.context);
+      return adapter.open(normalized.target, normalized.context);
+    }
+  };
+}
+
+function inspectSessionTarget(target, options = {}) {
+  const registry = createAdapterRegistry(options);
+  return registry.open(target, options).getSnapshot();
+}
+
+module.exports = {
+  createAdapterRegistry,
+  createDefaultAdapters,
+  inspectSessionTarget,
+  normalizeStructuredTarget
+};

package/scripts/lib/session-aliases.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Session Aliases Library for Claude Code.
+ * Manages named aliases for session files, stored in ~/.claude/session-aliases.json.
+ */
+
+/** Internal alias storage entry */
+export interface AliasEntry {
+  sessionPath: string;
+  createdAt: string;
+  updatedAt?: string;
+  title: string | null;
+}
+
+/** Alias data structure stored on disk */
+export interface AliasStore {
+  version: string;
+  aliases: Record<string, AliasEntry>;
+  metadata: {
+    totalCount: number;
+    lastUpdated: string;
+  };
+}
+
+/** Resolved alias information returned by resolveAlias */
+export interface ResolvedAlias {
+  alias: string;
+  sessionPath: string;
+  createdAt: string;
+  title: string | null;
+}
+
+/** Alias entry returned by listAliases */
+export interface AliasListItem {
+  name: string;
+  sessionPath: string;
+  createdAt: string;
+  updatedAt?: string;
+  title: string | null;
+}
+
+/** Result from mutation operations (set, delete, rename, update, cleanup) */
+export interface AliasResult {
+  success: boolean;
+  error?: string;
+  [key: string]: unknown;
+}
+
+export interface SetAliasResult extends AliasResult {
+  isNew?: boolean;
+  alias?: string;
+  sessionPath?: string;
+  title?: string | null;
+}
+
+export interface DeleteAliasResult extends AliasResult {
+  alias?: string;
+  deletedSessionPath?: string;
+}
+
+export interface RenameAliasResult extends AliasResult {
+  oldAlias?: string;
+  newAlias?: string;
+  sessionPath?: string;
+}
+
+export interface CleanupResult {
+  totalChecked: number;
+  removed: number;
+  removedAliases: Array<{ name: string; sessionPath: string }>;
+  error?: string;
+}
+
+export interface ListAliasesOptions {
+  /** Filter aliases by name or title (partial match, case-insensitive) */
+  search?: string | null;
+  /** Maximum number of aliases to return */
+  limit?: number | null;
+}
+
+/** Get the path to the aliases JSON file */
+export function getAliasesPath(): string;
+
+/** Load all aliases from disk. Returns default structure if file doesn't exist. */
+export function loadAliases(): AliasStore;
+
+/**
+ * Save aliases to disk with atomic write (temp file + rename).
+ * Creates backup before writing; restores on failure.
+ */
+export function saveAliases(aliases: AliasStore): boolean;
+
+/**
+ * Resolve an alias name to its session data.
+ * @returns Alias data, or null if not found or invalid name
+ */
+export function resolveAlias(alias: string): ResolvedAlias | null;
+
+/**
+ * Create or update an alias for a session.
+ * Alias names must be alphanumeric with dashes/underscores.
+ * Reserved names (list, help, remove, delete, create, set) are rejected.
+ */
+export function setAlias(alias: string, sessionPath: string, title?: string | null): SetAliasResult;
+
+/**
+ * List all aliases, optionally filtered and limited.
+ * Results are sorted by updated time (newest first).
+ */
+export function listAliases(options?: ListAliasesOptions): AliasListItem[];
+
+/** Delete an alias by name */
+export function deleteAlias(alias: string): DeleteAliasResult;
+
+/**
+ * Rename an alias. Fails if old alias doesn't exist or new alias already exists.
+ * New alias name must be alphanumeric with dashes/underscores.
+ */
+export function renameAlias(oldAlias: string, newAlias: string): RenameAliasResult;
+
+/**
+ * Resolve an alias or pass through a session path.
+ * First tries to resolve as alias; if not found, returns the input as-is.
+ */
+export function resolveSessionAlias(aliasOrId: string): string;
+
+/** Update the title of an existing alias. Pass null to clear. */
+export function updateAliasTitle(alias: string, title: string | null): AliasResult;
+
+/** Get all aliases that point to a specific session path */
+export function getAliasesForSession(sessionPath: string): Array<{ name: string; createdAt: string; title: string | null }>;
+
+/**
+ * Remove aliases whose sessions no longer exist.
+ * @param sessionExists - Function that returns true if a session path is valid
+ */
+export function cleanupAliases(sessionExists: (sessionPath: string) => boolean): CleanupResult;