@schnick371/devsteps-shared 0.0.1 → 0.5.0

package/src/core/context.ts

@@ -0,0 +1,269 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { ContextLevel, QuickContext } from '../schemas/project.js';
+import { CACHE_CONFIG, getCache } from '../utils/cache.js';
+
+interface PackageInfo {
+  name: string;
+  purpose: string;
+  dependencies: string[];
+}
+
+interface ItemCounts {
+  total: number;
+  by_type: Record<string, number>;
+  by_status: Record<string, number>;
+}
+
+interface RecentUpdate {
+  id: string;
+  type: string;
+  title: string;
+  updated: string;
+}
+
+interface ContextResponse {
+  context_level: ContextLevel;
+  tokens_used: number;
+  static_context?: unknown;
+  dynamic_context: {
+    packages: PackageInfo[];
+    active_items: ItemCounts;
+    recent_updates: RecentUpdate[];
+  };
+  suggestions?: string[];
+}
+
+/**
+ * Analyze packages from workspace (with caching)
+ */
+export async function analyzePackages(projectDir: string): Promise<PackageInfo[]> {
+  const cache = getCache();
+  const cacheKey = `package_analysis:${projectDir}`;
+  const packagesDir = path.join(projectDir, 'packages');
+
+  // Try cache first
+  const cached = cache.get<PackageInfo[]>(cacheKey, CACHE_CONFIG.PACKAGE_ANALYSIS_TTL, packagesDir);
+  if (cached) {
+    return cached;
+  }
+
+  const packages: PackageInfo[] = [];
+
+  try {
+    const entries = await fs.readdir(packagesDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const pkgPath = path.join(packagesDir, entry.name, 'package.json');
+        try {
+          const content = await fs.readFile(pkgPath, 'utf-8');
+          const pkg = JSON.parse(content);
+
+          packages.push({
+            name: pkg.name || entry.name,
+            purpose: pkg.description || 'No description',
+            dependencies: Object.keys(pkg.dependencies || {}),
+          });
+        } catch {
+          // Skip if no package.json
+        }
+      }
+    }
+  } catch {
+    // No packages directory
+  }
+
+  // Cache the result
+  cache.set(cacheKey, packages, packagesDir);
+
+  return packages;
+}
+
+/**
+ * Get item counts from index (with caching)
+ */
+export async function getItemCounts(devcrumbsDir: string): Promise<ItemCounts> {
+  const cache = getCache();
+  const cacheKey = `item_counts:${devcrumbsDir}`;
+  const indexPath = path.join(devcrumbsDir, 'index.json');
+
+  // Try cache first
+  const cached = cache.get<ItemCounts>(cacheKey, CACHE_CONFIG.ITEM_COUNTS_TTL, indexPath);
+  if (cached) {
+    return cached;
+  }
+
+  try {
+    const content = await fs.readFile(indexPath, 'utf-8');
+    const index = JSON.parse(content);
+
+    const counts: ItemCounts = {
+      total: index.items.length,
+      by_type: {},
+      by_status: {},
+    };
+
+    for (const item of index.items) {
+      counts.by_type[item.type] = (counts.by_type[item.type] || 0) + 1;
+      counts.by_status[item.status] = (counts.by_status[item.status] || 0) + 1;
+    }
+
+    // Cache the result
+    cache.set(cacheKey, counts, indexPath);
+
+    return counts;
+  } catch {
+    return { total: 0, by_type: {}, by_status: {} };
+  }
+}
+
+/**
+ * Get recent updates (last N days) (with caching)
+ */
+export async function getRecentUpdates(devcrumbsDir: string, days: number): Promise<RecentUpdate[]> {
+  const cache = getCache();
+  const cacheKey = `recent_updates:${devcrumbsDir}:${days}`;
+  const indexPath = path.join(devcrumbsDir, 'index.json');
+
+  // Try cache first
+  const cached = cache.get<RecentUpdate[]>(cacheKey, CACHE_CONFIG.RECENT_UPDATES_TTL, indexPath);
+  if (cached) {
+    return cached;
+  }
+
+  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+
+  try {
+    const content = await fs.readFile(indexPath, 'utf-8');
+    const index = JSON.parse(content);
+
+    const updates = index.items
+      .filter((item: { updated: string }) => new Date(item.updated).getTime() > cutoff)
+      .sort(
+        (a: { updated: string }, b: { updated: string }) =>
+          new Date(b.updated).getTime() - new Date(a.updated).getTime()
+      )
+      .slice(0, 10)
+      .map((item: { id: string; type: string; title: string; updated: string }) => ({
+        id: item.id,
+        type: item.type,
+        title: item.title,
+        updated: item.updated,
+      }));
+
+    // Cache the result
+    cache.set(cacheKey, updates, indexPath);
+
+    return updates;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read PROJECT.md if exists (with caching)
+ */
+export async function readProjectMd(devcrumbsDir: string): Promise<QuickContext | null> {
+  const cache = getCache();
+  const cacheKey = `project_md:${devcrumbsDir}`;
+  const projectPath = path.join(devcrumbsDir, 'PROJECT.md');
+
+  // Try cache first
+  const cached = cache.get<QuickContext | null>(cacheKey, CACHE_CONFIG.PROJECT_MD_TTL, projectPath);
+  if (cached !== null) {
+    return cached;
+  }
+
+  try {
+    const content = await fs.readFile(projectPath, 'utf-8');
+
+    // Parse markdown to extract context (simplified)
+    // In production, use a proper markdown parser
+    const techStack: Record<string, string> = {};
+    const packages: PackageInfo[] = [];
+
+    // Extract tech stack (look for bullet points after "### Tech Stack")
+    const techStackMatch = content.match(/### Tech Stack\n([\s\S]*?)(?=\n###|$)/);
+    if (techStackMatch) {
+      const lines = techStackMatch[1].split('\n');
+      for (const line of lines) {
+        const match = line.match(/- \*\*(.+?)\*\*: (.+)/);
+        if (match) {
+          techStack[match[1]] = match[2];
+        }
+      }
+    }
+
+    // Extract project type
+    const projectTypeMatch = content.match(/### Project Type\n(.+)/);
+    const projectType = projectTypeMatch?.[1] || 'Unknown';
+
+    const result = {
+      tech_stack: techStack,
+      packages,
+      project_type: projectType,
+    };
+
+    // Cache the result
+    cache.set(cacheKey, result, projectPath);
+
+    return result;
+  } catch {
+    // Cache the null result (file doesn't exist)
+    cache.set(cacheKey, null);
+    return null;
+  }
+}
+
+/**
+ * Estimate token count (rough approximation: 1 token ≈ 4 chars)
+ */
+export function estimateTokens(obj: unknown): number {
+  const str = JSON.stringify(obj);
+  return Math.ceil(str.length / 4);
+}
+
+/**
+ * Get quick context
+ */
+export async function getQuickContext(
+  projectDir: string,
+  devcrumbsDir: string
+): Promise<ContextResponse> {
+  const packages = await analyzePackages(projectDir);
+  const activeItems = await getItemCounts(devcrumbsDir);
+  const recentUpdates = await getRecentUpdates(devcrumbsDir, 7);
+  const staticContext = await readProjectMd(devcrumbsDir);
+
+  const response: ContextResponse = {
+    context_level: 'quick',
+    tokens_used: 0,
+    dynamic_context: {
+      packages,
+      active_items: activeItems,
+      recent_updates: recentUpdates,
+    },
+  };
+
+  if (staticContext) {
+    response.static_context = staticContext;
+  }
+
+  response.tokens_used = estimateTokens(response);
+
+  // Add suggestions
+  const suggestions: string[] = [];
+  if (!staticContext) {
+    suggestions.push('Consider creating .devcrumbs/PROJECT.md for static context');
+  }
+  if (activeItems.by_status.blocked > 0) {
+    suggestions.push(`${activeItems.by_status.blocked} blocked items need attention`);
+  }
+
+  if (suggestions.length > 0) {
+    response.suggestions = suggestions;
+  }
+
+  return response;
+}

package/src/core/get.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.js","sourceRoot":"","sources":["get.ts"],"names":[],"mappings":";;AAaA,0BAyBC;AAtCD,qCAAmD;AACnD,yCAAiC;AAEjC,gDAAmE;AAOnE;;GAEG;AACI,KAAK,UAAU,OAAO,CAAC,SAAiB,EAAE,MAAc;IAC7D,IAAI,CAAC,IAAA,oBAAU,EAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,sBAAW,EAAC,MAAM,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,UAAU,GAAG,4BAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,IAAA,gBAAI,EAAC,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC;IACnE,MAAM,eAAe,GAAG,IAAA,gBAAI,EAAC,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,KAAK,CAAC,CAAC;IAEpE,IAAI,CAAC,IAAA,oBAAU,EAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,QAAQ,GAAiB,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/E,MAAM,WAAW,GAAG,IAAA,oBAAU,EAAC,eAAe,CAAC,CAAC,CAAC,CAAC,IAAA,sBAAY,EAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE9F,OAAO;QACL,QAAQ;QACR,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/src/core/get.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ItemMetadata } from '../schemas/index.js';
+import { TYPE_TO_DIRECTORY, parseItemId } from '../utils/index.js';
+
+export interface GetItemResult {
+  metadata: ItemMetadata;
+  description: string;
+}
+
+/**
+ * Core business logic for getting an item
+ */
+export async function getItem(devcrumbsDir: string, itemId: string): Promise<GetItemResult> {
+  if (!existsSync(devcrumbsDir)) {
+    throw new Error('Project not initialized. Run devcrumbs-init first.');
+  }
+
+  const parsed = parseItemId(itemId);
+  if (!parsed) {
+    throw new Error(`Invalid item ID: ${itemId}`);
+  }
+
+  const typeFolder = TYPE_TO_DIRECTORY[parsed.type];
+  const metadataPath = join(devcrumbsDir, typeFolder, `${itemId}.json`);
+  const descriptionPath = join(devcrumbsDir, typeFolder, `${itemId}.md`);
+
+  if (!existsSync(metadataPath)) {
+    throw new Error(`Item not found: ${itemId}`);
+  }
+
+  const metadata: ItemMetadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));
+  const description = existsSync(descriptionPath) ? readFileSync(descriptionPath, 'utf-8') : '';
+
+  return {
+    metadata,
+    description,
+  };
+}

package/src/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,mCAAyE;AAAhE,iGAAA,OAAO,OAAA;AAChB,mCAAuD;AAA9C,iGAAA,OAAO,OAAA;AAChB,qCAAgF;AAAvE,oGAAA,SAAS,OAAA;AAClB,yCAAqF;AAA5E,uGAAA,UAAU,OAAA;AACnB,2CAMsB;AALpB,yGAAA,WAAW,OAAA;AAEX,wGAAA,UAAU,OAAA;AAIZ,2CAOsB;AANpB,6GAAA,eAAe,OAAA;AACf,6GAAA,eAAe,OAAA;AACf,2GAAA,aAAa,OAAA;AACb,8GAAA,gBAAgB,OAAA;AAChB,2GAAA,aAAa,OAAA;AACb,4GAAA,cAAc,OAAA;AAEhB,mDAK0B;AAJxB,iHAAA,eAAe,OAAA;AACf,6GAAA,WAAW,OAAA;AACX,gHAAA,cAAc,OAAA"}

package/src/core/index.ts

@@ -0,0 +1,26 @@
+export { addItem, type AddItemArgs, type AddItemResult } from './add.js';
+export { getItem, type GetItemResult } from './get.js';
+export { listItems, type ListItemsArgs, type ListItemsResult } from './list.js';
+export { updateItem, type UpdateItemArgs, type UpdateItemResult } from './update.js';
+export {
+  archiveItem,
+  type ArchiveItemResult,
+  purgeItems,
+  type PurgeItemsArgs,
+  type PurgeItemsResult,
+} from './archive.js';
+export {
+  getQuickContext,
+  analyzePackages,
+  getItemCounts,
+  getRecentUpdates,
+  readProjectMd,
+  estimateTokens,
+} from './context.js';
+export {
+  bulkUpdateItems,
+  bulkAddTags,
+  bulkRemoveTags,
+  type BulkUpdateResult,
+} from './bulk-update.js';
+export { validateRelationship, type ValidationResult, type WorkItem } from './validation.js';

package/src/core/list.js.map

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

package/src/core/list.ts

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type {
+  DevCrumbsIndex,
+  EisenhowerQuadrant,
+  ItemStatus,
+  ItemType,
+  Priority,
+} from '../schemas/index.js';
+import { TYPE_TO_DIRECTORY } from '../utils/index.js';
+
+export interface ListItemsArgs {
+  type?: ItemType;
+  status?: ItemStatus;
+  priority?: Priority;
+  assignee?: string;
+  tags?: string[];
+  eisenhower?: EisenhowerQuadrant;
+  limit?: number;
+}
+
+export interface ListItemsResult {
+  count: number;
+  items: DevCrumbsIndex['items'];
+}
+
+/**
+ * Core business logic for listing items with filters
+ */
+export async function listItems(
+  devcrumbsDir: string,
+  args: ListItemsArgs = {}
+): Promise<ListItemsResult> {
+  if (!existsSync(devcrumbsDir)) {
+    throw new Error('Project not initialized. Run devcrumbs-init first.');
+  }
+
+  const indexPath = join(devcrumbsDir, 'index.json');
+  const index: DevCrumbsIndex = JSON.parse(readFileSync(indexPath, 'utf-8'));
+
+  let items = [...index.items];
+
+  // Apply filters
+  if (args.type) {
+    items = items.filter((i) => i.type === args.type);
+  }
+
+  if (args.status) {
+    items = items.filter((i) => i.status === args.status);
+  }
+
+  if (args.priority) {
+    items = items.filter((i) => i.priority === args.priority);
+  }
+
+  if (args.assignee) {
+    // Load full metadata for assignee filter
+    items = items.filter((i) => {
+      const metadataPath = join(devcrumbsDir, TYPE_TO_DIRECTORY[i.type], `${i.id}.json`);
+      if (!existsSync(metadataPath)) return false;
+      const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));
+      return metadata.assignee === args.assignee;
+    });
+  }
+
+  if (args.tags && args.tags.length > 0) {
+    // Load full metadata for tags filter
+    const filterTags = args.tags;
+    items = items.filter((i) => {
+      const metadataPath = join(devcrumbsDir, TYPE_TO_DIRECTORY[i.type], `${i.id}.json`);
+      if (!existsSync(metadataPath)) return false;
+      const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));
+      return filterTags.every((tag) => metadata.tags.includes(tag));
+    });
+  }
+
+  if (args.eisenhower) {
+    // Load full metadata for eisenhower filter
+    items = items.filter((i) => {
+      const metadataPath = join(devcrumbsDir, TYPE_TO_DIRECTORY[i.type], `${i.id}.json`);
+      if (!existsSync(metadataPath)) return false;
+      const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));
+      return metadata.eisenhower === args.eisenhower;
+    });
+  }
+
+  // Apply limit
+  if (args.limit && args.limit > 0) {
+    items = items.slice(0, args.limit);
+  }
+
+  return {
+    count: items.length,
+    items,
+  };
+}

package/src/core/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","sourceRoot":"","sources":["update.ts"],"names":[],"mappings":";;AAgCA,gCA+FC;AA/HD,qCAAkE;AAClE,yCAAiC;AAQjC,gDAAwF;AAoBxF;;GAEG;AACI,KAAK,UAAU,UAAU,CAC9B,SAAiB,EACjB,IAAoB;IAEpB,IAAI,CAAC,IAAA,oBAAU,EAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,sBAAW,EAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,UAAU,GAAG,4BAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,IAAA,gBAAI,EAAC,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;IACpE,MAAM,eAAe,GAAG,IAAA,gBAAI,EAAC,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAErE,IAAI,CAAC,IAAA,oBAAU,EAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,2BAA2B;IAC3B,MAAM,QAAQ,GAAiB,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/E,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;IAElC,mDAAmD;IACnD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,CAAC;QACtF,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC;QACzD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,YAAY,GAAa,EAAE,CAAC;YAClC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,MAAM,WAAW,GAAG,IAAA,sBAAW,EAAC,OAAO,CAAC,CAAC;gBACzC,IAAI,WAAW,EAAE,CAAC;oBAChB,MAAM,WAAW,GAAG,4BAAiB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;oBACxD,MAAM,SAAS,GAAG,IAAA,gBAAI,EAAC,SAAS,EAAE,WAAW,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;oBAClE,IAAI,IAAA,oBAAU,EAAC,SAAS,CAAC,EAAE,CAAC;wBAC1B,MAAM,SAAS,GAAiB,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;wBAC7E,IAAI,SAAS,CAAC,MAAM,KAAK,MAAM,IAAI,SAAS,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;4BACpE,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;wBAC7B,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;YACD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CACb,gBAAgB,IAAI,CAAC,EAAE,KAAK,YAAY,CAAC,MAAM,8BAA8B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvG,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM;QAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC/C,IAAI,IAAI,CAAC,QAAQ;QAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IACrD,IAAI,IAAI,CAAC,UAAU;QAAE,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAC3D,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS;QAAE,QAAQ,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;IAClF,IAAI,IAAI,CAAC,KAAK;QAAE,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC5C,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;QAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IACnE,IAAI,IAAI,CAAC,IAAI;QAAE,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACzC,IAAI,IAAI,CAAC,cAAc;QAAE,QAAQ,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;IAEvE,QAAQ,CAAC,OAAO,GAAG,IAAA,8BAAmB,GAAE,CAAC;IAEzC,IAAA,uBAAa,EAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAE/D,iCAAiC;IACjC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,IAAA,uBAAa,EAAC,eAAe,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACnD,CAAC;IAED,eAAe;IACf,MAAM,SAAS,GAAG,IAAA,gBAAI,EAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAChD,MAAM,KAAK,GAAgB,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAExE,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;IACjE,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,MAAM;YAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC7D,IAAI,IAAI,CAAC,QAAQ;YAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QACnE,IAAI,IAAI,CAAC,KAAK;YAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QAC1D,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QAElD,eAAe;QACf,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YAC7C,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;YACtE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC/E,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC;IACtC,IAAA,uBAAa,EAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAEzD,OAAO;QACL,QAAQ;QACR,SAAS;KACV,CAAC;AACJ,CAAC"}

package/src/core/update.ts

@@ -0,0 +1,154 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type {
+  DevCrumbsIndex,
+  EisenhowerQuadrant,
+  ItemMetadata,
+  ItemStatus,
+  Priority,
+} from '../schemas/index.js';
+import { TYPE_TO_DIRECTORY, getCurrentTimestamp, parseItemId } from '../utils/index.js';
+
+export interface UpdateItemArgs {
+  id: string;
+  status?: ItemStatus;
+  priority?: Priority;
+  eisenhower?: EisenhowerQuadrant;
+  superseded_by?: string;
+  title?: string;
+  description?: string;
+  append_description?: string;
+  assignee?: string;
+  tags?: string[];
+  affected_paths?: string[];
+}
+
+export interface UpdateItemResult {
+  metadata: ItemMetadata;
+  oldStatus: ItemStatus;
+}
+
+/**
+ * Core business logic for updating an item
+ */
+export async function updateItem(
+  devcrumbsDir: string,
+  args: UpdateItemArgs
+): Promise<UpdateItemResult> {
+  if (!existsSync(devcrumbsDir)) {
+    throw new Error('Project not initialized. Run devcrumbs-init first.');
+  }
+
+  const parsed = parseItemId(args.id);
+  if (!parsed) {
+    throw new Error(`Invalid item ID: ${args.id}`);
+  }
+
+  const typeFolder = TYPE_TO_DIRECTORY[parsed.type];
+  const metadataPath = join(devcrumbsDir, typeFolder, `${args.id}.json`);
+  const descriptionPath = join(devcrumbsDir, typeFolder, `${args.id}.md`);
+
+  if (!existsSync(metadataPath)) {
+    throw new Error(`Item not found: ${args.id}`);
+  }
+
+  // Read and update metadata
+  const metadata: ItemMetadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));
+  const oldStatus = metadata.status;
+
+  // Validate status transitions (parent-child rules)
+  if (args.status === 'done') {
+    // Helper function to validate children are complete
+    const validateChildren = (relationshipType: 'implemented-by' | 'tested-by'): void => {
+      const children = metadata.linked_items[relationshipType];
+      if (children.length > 0) {
+        const openChildren: string[] = [];
+        for (const childId of children) {
+          const childParsed = parseItemId(childId);
+          if (childParsed) {
+            const childFolder = TYPE_TO_DIRECTORY[childParsed.type];
+            const childPath = join(devcrumbsDir, childFolder, `${childId}.json`);
+            if (existsSync(childPath)) {
+              const childMeta: ItemMetadata = JSON.parse(readFileSync(childPath, 'utf-8'));
+              if (childMeta.status !== 'done' && childMeta.status !== 'cancelled' && childMeta.status !== 'obsolete') {
+                openChildren.push(childId);
+              }
+            }
+          }
+        }
+        if (openChildren.length > 0) {
+          const relationLabel = relationshipType === 'implemented-by' ? 'implementation' : 'test';
+          throw new Error(
+            `Cannot close ${args.id}: ${openChildren.length} ${relationLabel} item(s) still open: ${openChildren.join(', ')}`
+          );
+        }
+      }
+    };
+
+    // Validate implemented-by children (Scrum: Epic→Story, Story→Task; Waterfall: Requirement→Feature, Feature→Task)
+    if (['epic', 'story', 'requirement', 'feature'].includes(metadata.type)) {
+      validateChildren('implemented-by');
+    }
+
+    // Validate tested-by children (all parent types must have tests complete)
+    if (['epic', 'story', 'requirement', 'feature'].includes(metadata.type)) {
+      validateChildren('tested-by');
+    }
+  }
+
+  if (args.status) metadata.status = args.status;
+  if (args.priority) metadata.priority = args.priority;
+  if (args.eisenhower) metadata.eisenhower = args.eisenhower;
+  if (args.superseded_by !== undefined) metadata.superseded_by = args.superseded_by;
+  if (args.title) metadata.title = args.title;
+  if (args.assignee !== undefined) metadata.assignee = args.assignee;
+  if (args.tags) metadata.tags = args.tags;
+  if (args.affected_paths) metadata.affected_paths = args.affected_paths;
+
+  metadata.updated = getCurrentTimestamp();
+
+  writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
+
+  // Update description
+  if (args.description && args.append_description) {
+    throw new Error('Cannot use both description and append_description simultaneously');
+  }
+  
+  if (args.description) {
+    // Replace entire description
+    writeFileSync(descriptionPath, args.description);
+  } else if (args.append_description) {
+    // Append to existing (or create new if doesn't exist)
+    const existing = existsSync(descriptionPath) 
+      ? readFileSync(descriptionPath, 'utf-8') 
+      : '';
+    writeFileSync(descriptionPath, existing + args.append_description);
+  }
+
+  // Update index
+  const indexPath = join(devcrumbsDir, 'index.json');
+  const index: DevCrumbsIndex = JSON.parse(readFileSync(indexPath, 'utf-8'));
+
+  const itemIndex = index.items.findIndex((i) => i.id === args.id);
+  if (itemIndex !== -1) {
+    if (args.status) index.items[itemIndex].status = args.status;
+    if (args.priority) index.items[itemIndex].priority = args.priority;
+    if (args.title) index.items[itemIndex].title = args.title;
+    index.items[itemIndex].updated = metadata.updated;
+
+    // Update stats
+    if (args.status && oldStatus !== args.status) {
+      index.stats = index.stats || { total: 0, by_type: {}, by_status: {} };
+      index.stats.by_status[oldStatus] = (index.stats.by_status[oldStatus] || 1) - 1;
+      index.stats.by_status[args.status] = (index.stats.by_status[args.status] || 0) + 1;
+    }
+  }
+
+  index.last_updated = metadata.updated;
+  writeFileSync(indexPath, JSON.stringify(index, null, 2));
+
+  return {
+    metadata,
+    oldStatus,
+  };
+}