Task Kit Core

@caio.silveira/taskkit-core is the programmatic, local-first, AI-first project state engine underlying Task Kit.

It manages the project directory workspace, file loading, data serialization, schema migrations, and concurrency locks. It is designed to be purely programmatic, with zero terminal formatting or CLI dependencies, making it safe and clean to use inside Node.js applications or custom integrations.

Installation

Install the package via npm:

npm install @caio.silveira/taskkit-core

Programmatic Usage Example

Here is a quick example of how to load the engine and interact with the task state programmatically:

import { TaskKitEngine } from '@caio.silveira/taskkit-core';

async function main() {
  // Find project root and load the state engine
  // This automatically runs any required schema migrations and acquires a project lock
  const engine = await TaskKitEngine.load(process.cwd());

  try {
    // 1. Get current project config and tree structure
    const config = engine.getConfig();
    const tree = engine.getTree();
    console.log(`Loaded project with ${Object.keys(tree.nodes).length} nodes.`);

    // 2. Create a new task node
    const newNode = await engine.createNode('Implement Database Cache', {
      description: 'Use Redis for caching database query results.',
      tags: ['backend', 'performance']
    });
    console.log(`Created node with ID: ${newNode.id} and Slug: ${newNode.slug}`);

    // 3. Mark a task completed
    await engine.completeNode(newNode.id);
    console.log('Task marked completed successfully.');
    
  } finally {
    // Crucial: Release the file lock when finished
    await engine.release();
  }
}

main().catch(console.error);

API Summary

The TaskKitEngine class exposes the following core operations:

• Lifecycle:
  • TaskKitEngine.load(path): Loads the database, executes migrations if needed, and locks the state files.
  • engine.release(): Releases the active file locks.
• Queries:
  • engine.getConfig(): Returns project configurations (config.json).
  • engine.getTree(): Returns the tree registry hierarchy (tree.json).
  • engine.getNode(idOrPath): Returns detailed node data including description, timestamps, and tags.
  • engine.findNode(idOrPath): Resolves full/relative path slugs or IDs to the target node.
• Mutations:
  • engine.createNode(title, options): Creates a new leaf node in the hierarchy.
  • engine.updateNode(idOrPath, updates): Updates a node's details.
  • engine.moveNode(idOrPath, newParentIdOrPath): Moves a node to another parent in the tree hierarchy.
  • engine.completeNode(idOrPath): Marks a node and all of its children as completed.
  • engine.reopenNode(idOrPath): Reopens a completed node.
  • engine.archiveNode(idOrPath): Archives a node.
  • engine.deleteNode(idOrPath): Recursively deletes a node and its children from the database.
• Agent Checkpoint & Handover:
  • engine.checkpointNode(idOrPath, checkpointData): Records progress details (checkpoints) for AI assistants to resume.
  • engine.resumeNode(idOrPath): Retrieves the active agent progress checkpoint.