@kynetic-ai/spec 0.1.0

package/dist/cli/commands/clone-for-testing.js

@@ -0,0 +1,176 @@
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import { ulid } from 'ulid';
+import { output, error as outputError } from '../output.js';
+import { EXIT_CODES } from '../exit-codes.js';
+// AC: @cmd-clone-for-testing ac-1
+/**
+ * Creates isolated repo copy for testing
+ * - Clones source repo to destination
+ * - Removes remote origin for isolation
+ * - Preserves all branches including kspec-meta
+ */
+function cloneRepo(source, dest) {
+    // Clone with --mirror to get all branches
+    const cloneResult = spawnSync('git', [
+        'clone',
+        '--mirror',
+        source,
+        path.join(dest, '.git')
+    ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (cloneResult.status !== 0) {
+        return { success: false, error: cloneResult.stderr };
+    }
+    // Convert bare mirror repo to normal repo
+    const configResult = spawnSync('git', [
+        'config',
+        '--bool',
+        'core.bare',
+        'false'
+    ], { cwd: dest, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (configResult.status !== 0) {
+        return { success: false, error: configResult.stderr };
+    }
+    // Reset working tree to populate files
+    const resetResult = spawnSync('git', ['reset', '--hard'], {
+        cwd: dest,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    if (resetResult.status !== 0) {
+        return { success: false, error: resetResult.stderr };
+    }
+    // Remove remote references for true isolation
+    const remoteResult = spawnSync('git', ['remote', 'remove', 'origin'], {
+        cwd: dest,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    // Don't fail if no remote exists
+    // remoteResult.status will be non-zero if origin doesn't exist, which is fine
+    // Clean up worktree metadata from source repo to prevent conflicts
+    // The mirror clone copies .git/worktrees/ which causes "already in use" errors
+    const worktreesPath = path.join(dest, '.git', 'worktrees');
+    if (fs.existsSync(worktreesPath)) {
+        fs.rmSync(worktreesPath, { recursive: true, force: true });
+    }
+    return { success: true };
+}
+// AC: @cmd-clone-for-testing ac-2
+/**
+ * Sets up .kspec worktree if kspec-meta branch exists
+ */
+function setupWorktree(repoPath) {
+    // Check for kspec-meta branch
+    const branchCheck = spawnSync('git', [
+        'branch', '--list', 'kspec-meta'
+    ], { cwd: repoPath, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (!branchCheck.stdout.trim()) {
+        // No kspec-meta branch, nothing to do
+        return { success: true };
+    }
+    // Create .kspec worktree
+    const worktreePath = path.join(repoPath, '.kspec');
+    const worktreeResult = spawnSync('git', [
+        'worktree', 'add', '.kspec', 'kspec-meta'
+    ], { cwd: repoPath, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (worktreeResult.status !== 0) {
+        return { success: false, error: worktreeResult.stderr };
+    }
+    return { success: true };
+}
+// AC: @cmd-clone-for-testing ac-3
+/**
+ * Checkout specified branch
+ */
+function checkoutBranch(repoPath, branch) {
+    const checkoutResult = spawnSync('git', ['checkout', branch], {
+        cwd: repoPath,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    if (checkoutResult.status !== 0) {
+        return { success: false, error: checkoutResult.stderr, currentBranch: '' };
+    }
+    // Get current branch name
+    const branchResult = spawnSync('git', ['branch', '--show-current'], {
+        cwd: repoPath,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return { success: true, currentBranch: branchResult.stdout.trim() };
+}
+/**
+ * Get current branch name
+ */
+function getCurrentBranch(repoPath) {
+    const branchResult = spawnSync('git', ['branch', '--show-current'], {
+        cwd: repoPath,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return branchResult.stdout.trim() || 'main';
+}
+/**
+ * Register the 'clone-for-testing' command
+ */
+export function registerCloneForTestingCommand(program) {
+    program
+        .command('clone-for-testing [dest] [source]')
+        .description('Create isolated repo copy for testing')
+        .option('--branch <name>', 'Branch to checkout after cloning')
+        .action(async (dest, source, options) => {
+        // Default source to current directory
+        if (!source) {
+            source = process.cwd();
+        }
+        try {
+            // AC: @cmd-clone-for-testing ac-4
+            // Generate temp dest if not provided
+            if (!dest) {
+                dest = path.join(os.tmpdir(), `kspec-test-${ulid().slice(0, 8).toLowerCase()}`);
+            }
+            // Create destination directory
+            if (!fs.existsSync(dest)) {
+                fs.mkdirSync(dest, { recursive: true });
+            }
+            // Clone the repo
+            const cloneResult = cloneRepo(source, dest);
+            if (!cloneResult.success) {
+                outputError(`Failed to clone repository: ${cloneResult.error}`);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            // Setup worktree if kspec-meta exists
+            const worktreeResult = setupWorktree(dest);
+            if (!worktreeResult.success) {
+                outputError(`Failed to setup worktree: ${worktreeResult.error}`);
+                process.exit(EXIT_CODES.ERROR);
+            }
+            // Checkout specified branch if provided
+            let currentBranch = getCurrentBranch(dest);
+            if (options.branch) {
+                const checkoutResult = checkoutBranch(dest, options.branch);
+                if (!checkoutResult.success) {
+                    outputError(`Failed to checkout branch '${options.branch}': ${checkoutResult.error}`);
+                    process.exit(EXIT_CODES.ERROR);
+                }
+                currentBranch = checkoutResult.currentBranch;
+            }
+            // AC: @cmd-clone-for-testing ac-5
+            // Output result (respects global --json flag)
+            output({ path: dest, branch: currentBranch }, () => {
+                console.log(`Created test repo at: ${dest}`);
+                if (options.branch) {
+                    console.log(`Checked out branch: ${currentBranch}`);
+                }
+            });
+        }
+        catch (err) {
+            outputError(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+}
+//# sourceMappingURL=clone-for-testing.js.map

package/dist/cli/commands/clone-for-testing.js.map

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

package/dist/cli/commands/derive.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+/**
+ * Register the 'derive' command
+ */
+export declare function registerDeriveCommand(program: Command): void;
+//# sourceMappingURL=derive.d.ts.map

package/dist/cli/commands/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/derive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2WpC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyM5D"}

package/dist/cli/commands/derive.js

@@ -0,0 +1,450 @@
+import { initContext, loadAllTasks, loadAllItems, saveTask, createTask, createNote, ReferenceIndex, AlignmentIndex, } from '../../parser/index.js';
+import { commitIfShadow } from '../../parser/shadow.js';
+import { output, error, info, isJsonMode } from '../output.js';
+import { errors } from '../../strings/index.js';
+import { EXIT_CODES } from '../exit-codes.js';
+/**
+ * Fields that contain nested spec items (mirrors yaml.ts)
+ */
+const NESTED_ITEM_FIELDS = ['modules', 'features', 'requirements', 'constraints', 'decisions'];
+/**
+ * Get the parent path from a child's _path.
+ * e.g., "features[0].requirements[1]" -> "features[0]"
+ * Returns empty string for top-level items.
+ */
+function getParentPath(childPath) {
+    if (!childPath)
+        return '';
+    const lastDotIndex = childPath.lastIndexOf('.');
+    if (lastDotIndex === -1)
+        return '';
+    return childPath.slice(0, lastDotIndex);
+}
+/**
+ * Check if an item is a direct child of another item based on _path.
+ * Direct children have a path that extends the parent's path by exactly one field[index].
+ */
+function isDirectChildOf(child, parent) {
+    const childPath = child._path || '';
+    const parentPath = parent._path || '';
+    // If paths are equal, not a child
+    if (childPath === parentPath)
+        return false;
+    // Child path must start with parent path
+    if (parentPath && !childPath.startsWith(parentPath + '.'))
+        return false;
+    // For root parent (empty path), child must be a top-level path like "features[0]"
+    if (!parentPath) {
+        // Direct child of root has no '.' in its path
+        return !childPath.includes('.');
+    }
+    // Get the remaining path after parent
+    const remaining = childPath.slice(parentPath.length + 1);
+    // Direct child has no additional '.' (e.g., "requirements[0]" not "requirements[0].something")
+    return !remaining.includes('.');
+}
+/**
+ * Find the parent spec item of a given item.
+ * Returns undefined for root-level items.
+ */
+function findParentItem(item, allItems) {
+    const parentPath = getParentPath(item._path);
+    // Root-level item or no path
+    if (!parentPath && !item._path)
+        return undefined;
+    if (!parentPath)
+        return undefined;
+    // Find item with matching path in the same source file
+    return allItems.find(i => i._path === parentPath && i._sourceFile === item._sourceFile);
+}
+/**
+ * Get direct children of a spec item.
+ * Only returns immediate children, not grandchildren.
+ */
+function getDirectChildren(parent, allItems) {
+    return allItems.filter(item => item._sourceFile === parent._sourceFile && isDirectChildOf(item, parent));
+}
+/**
+ * Collect an item and all its descendants in topological order (parent first).
+ * This ensures parent tasks are created before child tasks.
+ */
+function collectItemsRecursively(root, allItems) {
+    const result = [root];
+    const children = getDirectChildren(root, allItems);
+    for (const child of children) {
+        const descendants = collectItemsRecursively(child, allItems);
+        result.push(...descendants);
+    }
+    return result;
+}
+/**
+ * Resolve a spec item reference.
+ * Returns the spec item or exits with error.
+ */
+function resolveSpecRef(ref, items, tasks, index) {
+    const result = index.resolve(ref);
+    if (!result.ok) {
+        switch (result.error) {
+            case 'not_found':
+                error(errors.reference.specNotFound(ref));
+                break;
+            case 'ambiguous':
+                error(errors.reference.ambiguous(ref));
+                for (const candidate of result.candidates) {
+                    const item = items.find(i => i._ulid === candidate);
+                    const slug = item?.slugs[0] || '';
+                    console.error(`  - ${index.shortUlid(candidate)} ${slug ? `(${slug})` : ''}`);
+                }
+                break;
+            case 'duplicate_slug':
+                error(errors.reference.slugMapsToMultiple(ref));
+                for (const candidate of result.candidates) {
+                    console.error(`  - ${index.shortUlid(candidate)}`);
+                }
+                break;
+        }
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // Check if it's actually a spec item (not a task)
+    const item = items.find(i => i._ulid === result.ulid);
+    if (!item) {
+        // Check if it's a task
+        const task = tasks.find(t => t._ulid === result.ulid);
+        if (task) {
+            error(errors.reference.notSpecItem(ref));
+        }
+        else {
+            error(errors.reference.specNotFound(ref));
+        }
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    return item;
+}
+/**
+ * Generate a slug from a spec item title.
+ * Converts "My Feature Title" -> "task-my-feature-title"
+ */
+function generateSlugFromTitle(title) {
+    return ('task-' +
+        title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '')
+            .slice(0, 50));
+}
+/**
+ * Convert spec priority to task priority (number).
+ * Spec can use 'high', 'medium', 'low' or numeric 1-5.
+ */
+function normalizePriority(priority) {
+    if (priority === undefined)
+        return 3;
+    if (typeof priority === 'number')
+        return priority;
+    switch (priority) {
+        case 'high':
+            return 1;
+        case 'medium':
+            return 3;
+        case 'low':
+            return 5;
+        default:
+            return 3;
+    }
+}
+/**
+ * Generate implementation notes from spec item for newly derived task.
+ * Includes description and acceptance criteria summary.
+ */
+function generateImplementationNotes(specItem) {
+    const parts = [];
+    // Add description if present
+    if (specItem.description) {
+        parts.push(specItem.description.trim());
+    }
+    // Add acceptance criteria summary if present
+    if (specItem.acceptance_criteria && specItem.acceptance_criteria.length > 0) {
+        const acSection = ['', 'Acceptance Criteria:'];
+        for (const ac of specItem.acceptance_criteria) {
+            const summary = `${ac.given ? 'Given ' + ac.given + ', ' : ''}when ${ac.when}, then ${ac.then}`;
+            acSection.push(`- ${ac.id}: ${summary}`);
+        }
+        parts.push(acSection.join('\n'));
+    }
+    // Return combined content, or undefined if nothing to add
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
+/**
+ * Derive a task from a spec item.
+ * Returns result describing what happened.
+ *
+ * @param dependsOn - Task references to add as dependencies (for hierarchy-based deps)
+ * @param priority - Priority override (1-5), if not provided uses spec's priority
+ */
+async function deriveTaskFromSpec(ctx, specItem, existingTasks, items, index, alignmentIndex, options) {
+    // Check if a task already exists for this spec
+    const linkedTasks = alignmentIndex.getTasksForSpec(specItem._ulid);
+    if (linkedTasks.length > 0 && !options.force) {
+        const taskRef = linkedTasks[0].slugs[0]
+            ? `@${linkedTasks[0].slugs[0]}`
+            : `@${index.shortUlid(linkedTasks[0]._ulid)}`;
+        return {
+            specItem,
+            action: 'skipped',
+            task: linkedTasks[0],
+            reason: `task exists: ${taskRef}`,
+        };
+    }
+    // Check if slug would collide with existing task
+    const baseSlug = generateSlugFromTitle(specItem.title);
+    let slug = baseSlug;
+    let slugSuffix = 1;
+    // Find unique slug if needed
+    while (existingTasks.some(t => t.slugs.includes(slug))) {
+        slug = `${baseSlug}-${slugSuffix}`;
+        slugSuffix++;
+    }
+    // Generate implementation notes from spec
+    const noteContent = generateImplementationNotes(specItem);
+    const initialNotes = noteContent
+        ? [createNote(`Implementation notes (auto-generated from spec):\n\n${noteContent}`, '@kspec-derive')]
+        : [];
+    // Build task input with depends_on and initial notes
+    const taskInput = {
+        title: `Implement: ${specItem.title}`,
+        type: 'task',
+        spec_ref: `@${specItem.slugs[0] || specItem._ulid}`,
+        derivation: 'auto',
+        priority: options.priority ?? normalizePriority(specItem.priority),
+        slugs: [slug],
+        tags: [...(specItem.tags || [])],
+        depends_on: options.dependsOn || [],
+        notes: initialNotes,
+    };
+    // Dry run - don't actually create
+    if (options.dryRun) {
+        const previewTask = createTask(taskInput);
+        return {
+            specItem,
+            action: 'would_create',
+            task: previewTask,
+            dependsOn: options.dependsOn,
+        };
+    }
+    // Create and save the task
+    const newTask = createTask(taskInput);
+    await saveTask(ctx, newTask);
+    const specSlug = specItem.slugs[0] || specItem._ulid.slice(0, 8);
+    await commitIfShadow(ctx.shadow, 'derive', specSlug);
+    // Add to existing tasks list for slug collision checks
+    existingTasks.push(newTask);
+    return {
+        specItem,
+        action: 'created',
+        task: newTask,
+        dependsOn: options.dependsOn,
+    };
+}
+/**
+ * Get a task reference string for use in depends_on.
+ * Prefers slug over ULID for readability.
+ */
+function getTaskRef(task, index) {
+    return task.slugs[0] ? `@${task.slugs[0]}` : `@${index.shortUlid(task._ulid)}`;
+}
+/**
+ * Find or get the task for a parent spec item.
+ * Looks in:
+ * 1. Tasks created in this derive session (specToTaskMap)
+ * 2. Existing tasks linked to the parent spec (alignmentIndex)
+ */
+function getParentTaskRef(parentSpec, specToTaskMap, alignmentIndex, index) {
+    // Check if we created a task for this parent in this session
+    const sessionTask = specToTaskMap.get(parentSpec._ulid);
+    if (sessionTask) {
+        return getTaskRef(sessionTask, index);
+    }
+    // Check if an existing task is linked to this parent spec
+    const linkedTasks = alignmentIndex.getTasksForSpec(parentSpec._ulid);
+    if (linkedTasks.length > 0) {
+        return getTaskRef(linkedTasks[0], index);
+    }
+    return undefined;
+}
+/**
+ * Register the 'derive' command
+ */
+export function registerDeriveCommand(program) {
+    program
+        .command('derive [ref]')
+        .description('Create task(s) from spec item(s)')
+        .option('--all', 'Derive tasks for all spec items without linked tasks')
+        .option('--flat', 'Only derive for the specified item, not children (default: recursive)')
+        .option('--force', 'Create task even if one already exists for the spec')
+        .option('--dry-run', 'Show what would be created without making changes')
+        .option('--priority <n>', 'Set priority for created task(s) (1-5)', parseInt)
+        .action(async (ref, options) => {
+        try {
+            // Validate arguments
+            if (!ref && !options.all) {
+                error(errors.usage.deriveNoRef);
+                console.error('Usage:');
+                console.error('  kspec derive @spec-ref');
+                console.error('  kspec derive @spec-ref --flat');
+                console.error('  kspec derive --all');
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            if (ref && options.all) {
+                error(errors.usage.deriveRefAndAll);
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            // Validate priority if provided
+            if (options.priority !== undefined) {
+                if (isNaN(options.priority) || options.priority < 1 || options.priority > 5) {
+                    error('Priority must be a number between 1 and 5');
+                    process.exit(EXIT_CODES.USAGE_ERROR);
+                }
+            }
+            const ctx = await initContext();
+            const tasks = await loadAllTasks(ctx);
+            const items = await loadAllItems(ctx);
+            const index = new ReferenceIndex(tasks, items);
+            // Build alignment index
+            const alignmentIndex = new AlignmentIndex(tasks, items);
+            alignmentIndex.buildLinks(index);
+            // Collect spec items to process
+            let specsToDerive;
+            if (options.all) {
+                // Get all spec items without linked tasks
+                specsToDerive = items.filter(item => {
+                    const linkedTasks = alignmentIndex.getTasksForSpec(item._ulid);
+                    return linkedTasks.length === 0 || options.force;
+                });
+                if (specsToDerive.length === 0) {
+                    if (isJsonMode()) {
+                        console.log(JSON.stringify([]));
+                    }
+                    else {
+                        info('Nothing to derive (all items have tasks)');
+                    }
+                    return;
+                }
+            }
+            else {
+                // Single spec item - recursive by default, flat if --flat
+                const specItem = resolveSpecRef(ref, items, tasks, index);
+                if (options.flat) {
+                    specsToDerive = [specItem];
+                }
+                else {
+                    // Recursive: collect item and all descendants
+                    specsToDerive = collectItemsRecursively(specItem, items);
+                }
+            }
+            // Track spec ULID -> created task for dependency resolution
+            const specToTaskMap = new Map();
+            // Process each spec item in order (parents before children due to topological sort)
+            const results = [];
+            for (const specItem of specsToDerive) {
+                // Determine depends_on based on parent spec's task
+                let dependsOn;
+                if (!options.flat && !options.all) {
+                    // Find the parent spec item
+                    const parentSpec = findParentItem(specItem, items);
+                    if (parentSpec) {
+                        const parentTaskRef = getParentTaskRef(parentSpec, specToTaskMap, alignmentIndex, index);
+                        if (parentTaskRef) {
+                            dependsOn = [parentTaskRef];
+                        }
+                    }
+                }
+                const result = await deriveTaskFromSpec(ctx, specItem, tasks, items, index, alignmentIndex, {
+                    force: options.force || false,
+                    dryRun: options.dryRun || false,
+                    dependsOn,
+                    priority: options.priority,
+                });
+                // Track created/would_create tasks for dependency resolution
+                if (result.task && (result.action === 'created' || result.action === 'would_create')) {
+                    specToTaskMap.set(specItem._ulid, result.task);
+                }
+                // Also track skipped tasks (existing) for dependency resolution
+                if (result.action === 'skipped' && result.task) {
+                    specToTaskMap.set(specItem._ulid, result.task);
+                }
+                results.push(result);
+            }
+            // Output results
+            if (isJsonMode()) {
+                // JSON output format - simplified per AC
+                const jsonOutput = results.map(r => ({
+                    ulid: r.task?._ulid || null,
+                    slug: r.task?.slugs[0] || null,
+                    spec_ref: `@${r.specItem.slugs[0] || r.specItem._ulid}`,
+                    depends_on: r.task?.depends_on || [],
+                    action: r.action,
+                }));
+                console.log(JSON.stringify(jsonOutput, null, 2));
+                return; // Don't call output() which would output full results in global JSON mode
+            }
+            else {
+                // Human-readable output
+                output(results, () => {
+                    const created = results.filter(r => r.action === 'created');
+                    const skipped = results.filter(r => r.action === 'skipped');
+                    const wouldCreate = results.filter(r => r.action === 'would_create');
+                    if (options.dryRun) {
+                        console.log('Would create:');
+                        for (const r of wouldCreate) {
+                            const taskSlug = r.task?.slugs[0] || '';
+                            const deps = r.dependsOn?.length ? ` (depends: ${r.dependsOn.join(', ')})` : '';
+                            console.log(`  + ${r.specItem.title}`);
+                            console.log(`    -> ${taskSlug}${deps}`);
+                        }
+                        if (skipped.length > 0) {
+                            console.log('\nSkipped:');
+                            for (const r of skipped) {
+                                const specRef = r.specItem.slugs[0] ? `@${r.specItem.slugs[0]}` : `@${index.shortUlid(r.specItem._ulid)}`;
+                                console.log(`  - ${specRef} (${r.reason})`);
+                            }
+                        }
+                        console.log(`\nWould create ${wouldCreate.length} task(s)`);
+                        if (skipped.length > 0) {
+                            console.log(`Skipped ${skipped.length} (already have tasks)`);
+                        }
+                        return;
+                    }
+                    if (created.length > 0) {
+                        for (const r of created) {
+                            const taskSlug = r.task?.slugs[0] || '';
+                            const deps = r.dependsOn?.length ? ` (depends: ${r.dependsOn.join(', ')})` : '';
+                            console.log(`OK Created task: ${taskSlug}${deps}`);
+                        }
+                    }
+                    if (skipped.length > 0 && !options.all) {
+                        // Show skipped for explicit derive (not --all)
+                        for (const r of skipped) {
+                            const specRef = r.specItem.slugs[0] ? `@${r.specItem.slugs[0]}` : `@${index.shortUlid(r.specItem._ulid)}`;
+                            console.log(`Skipped ${specRef} (${r.reason})`);
+                        }
+                    }
+                    // Summary
+                    if (created.length > 0 || skipped.length > 0) {
+                        console.log('');
+                        if (created.length > 0) {
+                            console.log(`Created ${created.length} task(s)`);
+                        }
+                        if (skipped.length > 0) {
+                            console.log(`Skipped ${skipped.length} (already have tasks)`);
+                        }
+                    }
+                });
+            }
+        }
+        catch (err) {
+            error(errors.failures.deriveTasks, err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+}
+//# sourceMappingURL=derive.js.map