@lwelliott/cortex-cli 1.0.3

package/dist/validators/spawn-legality.js

@@ -0,0 +1,77 @@
+"use strict";
+// Spawn legality checker
+// Validates spawn prerequisites: sprint phase, task state, role match
+// Implements AD-0009: Validation as Read-Only Snapshot
+// + FS-SS-006-0002 (validate spawn legality)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSpawnLegality = checkSpawnLegality;
+const errors_1 = require("../utils/errors");
+/**
+ * Check whether a spawn operation is legal.
+ *
+ * Requirements:
+ * - Sprint must be IN EXECUTION (ERR-SPAWN-SPRINT)
+ * - Task must be To Do or In Progress (ERR-SPAWN-STATE)
+ * - Role must match the required stage role (ERR-SPAWN-ROLE)
+ *
+ * @param db - Database connection (read-only)
+ * @param sprintId - Sprint ID
+ * @param taskId - Task ID to spawn from
+ * @param stage - The spawn stage (e.g. "analyst", "architect", "coder", "tester")
+ * @param role - The role that will own the spawned task
+ * @returns Spawn legality result
+ */
+function checkSpawnLegality(db, sprintId, taskId, stage, role) {
+    // Check sprint exists and is IN EXECUTION
+    const sprint = db.prepare('SELECT id, status FROM sprints WHERE id = ?').get(sprintId);
+    if (!sprint) {
+        throw new errors_1.SprintNotFoundError(sprintId);
+    }
+    if (sprint.status !== 'IN EXECUTION') {
+        return {
+            sprint_id: sprintId,
+            task_id: taskId,
+            isLegal: false,
+            verdict: 'ERR-SPAWN-SPRINT',
+            reason: `Sprint "${sprintId}" is "${sprint.status}", but spawn requires "IN EXECUTION"`,
+        };
+    }
+    // Check task exists and is To Do or In Progress (per FS-SS-006-0002)
+    const task = db.prepare('SELECT id, status FROM tasks WHERE id = ?').get(taskId);
+    if (!task) {
+        return {
+            sprint_id: sprintId,
+            task_id: taskId,
+            isLegal: false,
+            verdict: 'ERR-SPAWN-STATE',
+            reason: `Task "${taskId}" not found`,
+        };
+    }
+    if (task.status !== 'To Do' && task.status !== 'In Progress') {
+        return {
+            sprint_id: sprintId,
+            task_id: taskId,
+            isLegal: false,
+            verdict: 'ERR-SPAWN-STATE',
+            reason: `Task "${taskId}" is "${task.status}", but spawn requires "To Do" or "In Progress"`,
+        };
+    }
+    // Check role match
+    // The stage to role mapping: analyst→analyst, architect→architect, coder→coder, tester→tester
+    if (stage !== role) {
+        return {
+            sprint_id: sprintId,
+            task_id: taskId,
+            isLegal: false,
+            verdict: 'ERR-SPAWN-ROLE',
+            reason: `Spawn stage "${stage}" requires role "${stage}", but "${role}" was provided`,
+        };
+    }
+    return {
+        sprint_id: sprintId,
+        task_id: taskId,
+        isLegal: true,
+        verdict: 'OK',
+    };
+}
+//# sourceMappingURL=spawn-legality.js.map

package/dist/validators/spawn-legality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-legality.js","sourceRoot":"","sources":["../../src/validators/spawn-legality.ts"],"names":[],"mappings":";AAAA,yBAAyB;AACzB,sEAAsE;AACtE,uDAAuD;AACvD,6CAA6C;;AAqB7C,gDAqEC;AAtFD,4CAAsD;AAEtD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,kBAAkB,CAChC,EAAqB,EACrB,QAAgB,EAChB,MAAc,EACd,KAAa,EACb,IAAY;IAEZ,0CAA0C;IAC1C,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CACvB,6CAA6C,CAC9C,CAAC,GAAG,CAAC,QAAQ,CAA+C,CAAC;IAE9D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,4BAAmB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACrC,OAAO;YACL,SAAS,EAAE,QAAQ;YACnB,OAAO,EAAE,MAAM;YACf,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,kBAAkB;YAC3B,MAAM,EAAE,WAAW,QAAQ,SAAS,MAAM,CAAC,MAAM,sCAAsC;SACxF,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CACrB,2CAA2C,CAC5C,CAAC,GAAG,CAAC,MAAM,CAA+C,CAAC;IAE5D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,SAAS,EAAE,QAAQ;YACnB,OAAO,EAAE,MAAM;YACf,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,iBAAiB;YAC1B,MAAM,EAAE,SAAS,MAAM,aAAa;SACrC,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QAC7D,OAAO;YACL,SAAS,EAAE,QAAQ;YACnB,OAAO,EAAE,MAAM;YACf,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,iBAAiB;YAC1B,MAAM,EAAE,SAAS,MAAM,SAAS,IAAI,CAAC,MAAM,gDAAgD;SAC5F,CAAC;IACJ,CAAC;IAED,mBAAmB;IACnB,8FAA8F;IAC9F,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO;YACL,SAAS,EAAE,QAAQ;YACnB,OAAO,EAAE,MAAM;YACf,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,gBAAgB;YACzB,MAAM,EAAE,gBAAgB,KAAK,oBAAoB,KAAK,WAAW,IAAI,gBAAgB;SACtF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,SAAS,EAAE,QAAQ;QACnB,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/validators/state-field-checker.d.ts

@@ -0,0 +1,8 @@
+import type Database from 'better-sqlite3';
+import type { ValidationIssue } from '../models/validation';
+/**
+ * Check that tasks in each state have the expected context fields populated.
+ * Missing fields generate warning-level issues (not hard errors).
+ */
+export declare function checkRequiredFields(db: Database.Database, sprintId?: string): ValidationIssue[];
+//# sourceMappingURL=state-field-checker.d.ts.map

package/dist/validators/state-field-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-field-checker.d.ts","sourceRoot":"","sources":["../../src/validators/state-field-checker.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAgB5D;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,eAAe,EAAE,CAmCnB"}

package/dist/validators/state-field-checker.js

@@ -0,0 +1,47 @@
+"use strict";
+// State field checker
+// Validates that tasks in each state have the expected context fields populated
+// Implements FS-SS-006-0003 (validate required fields per state)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkRequiredFields = checkRequiredFields;
+/**
+ * Define which fields are expected (recommended) for each task state.
+ * These are not hard errors — missing fields generate warnings.
+ */
+const EXPECTED_FIELDS = {
+    'Backlog': [],
+    'To Do': [],
+    'In Progress': [{ field: 'session_key', label: 'session_key' }],
+    'In Review': [{ field: 'owner', label: 'owner' }],
+    'Done': [{ field: 'completed_at', label: 'completed_at' }],
+    'Dropped': [],
+};
+/**
+ * Check that tasks in each state have the expected context fields populated.
+ * Missing fields generate warning-level issues (not hard errors).
+ */
+function checkRequiredFields(db, sprintId) {
+    const issues = [];
+    const rows = db.prepare(`SELECT id, status, session_key, owner, completed_at
+     FROM tasks
+     WHERE status IN ('In Progress', 'In Review', 'Done')
+       AND removed_at IS NULL
+     ${sprintId ? 'AND sprint_id = ?' : ''}`).all(...(sprintId ? [sprintId] : []));
+    for (const row of rows) {
+        const expected = EXPECTED_FIELDS[row.status] ?? [];
+        for (const { field, label } of expected) {
+            const value = row[field];
+            if (value === null || value === undefined || value === '') {
+                issues.push({
+                    category: 'field',
+                    severity: 'warning',
+                    message: `Task "${row.id}" in "${row.status}" is missing expected field "${label}"`,
+                    entity: row.id,
+                    detail: `State "${row.status}" expects ${label} to be populated`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=state-field-checker.js.map

package/dist/validators/state-field-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-field-checker.js","sourceRoot":"","sources":["../../src/validators/state-field-checker.ts"],"names":[],"mappings":";AAAA,sBAAsB;AACtB,gFAAgF;AAChF,iEAAiE;;AAuBjE,kDAsCC;AAvDD;;;GAGG;AACH,MAAM,eAAe,GAAgE;IACnF,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;IAC/D,WAAW,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACjD,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;IAC1D,SAAS,EAAE,EAAE;CACd,CAAC;AAEF;;;GAGG;AACH,SAAgB,mBAAmB,CACjC,EAAqB,EACrB,QAAiB;IAEjB,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CACrB;;;;OAIG,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,EAAE,CACzC,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAMlC,CAAC;IAEJ,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAEnD,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,QAAQ,EAAE,CAAC;YACxC,MAAM,KAAK,GAAI,GAA+B,CAAC,KAAK,CAAC,CAAC;YACtD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBAC1D,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,OAAO;oBACjB,QAAQ,EAAE,SAAS;oBACnB,OAAO,EAAE,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,CAAC,MAAM,gCAAgC,KAAK,GAAG;oBACnF,MAAM,EAAE,GAAG,CAAC,EAAE;oBACd,MAAM,EAAE,UAAU,GAAG,CAAC,MAAM,aAAa,KAAK,kBAAkB;iBACjE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/validators/state-field-recorder.d.ts

@@ -0,0 +1,39 @@
+import type Database from 'better-sqlite3';
+import type { TaskStatus } from '../models/common';
+/**
+ * Context fields that can be provided on a task move.
+ * — blocker removed per FS-SS-030-0004
+ * — reviewer renamed to owner, review_notes removed per FR-URD-034-0006
+ */
+export interface MoveContext {
+    session_key?: string;
+    owner?: string;
+}
+/**
+ * Compute the timestamp updates and field values to record for a transition.
+ *
+ * State-specific rules:
+ * - In Progress: record session_key if provided, auto-set started_at
+ * - In Review: record owner if provided (tasks.owner column)
+ * - Done: auto-set completed_at
+ *
+ * Note: blocker context field removed per FS-SS-030-0004
+ * Note: reviewer renamed to owner, review_notes removed per FR-URD-034-0006
+ *
+ * Returns the partial row updates to apply to the task.
+ */
+export declare function computeStateFields(current: TaskStatus, target: TaskStatus, context?: MoveContext): {
+    columns: string[];
+    values: unknown[];
+};
+/**
+ * Apply state-specific field updates to a task in the database.
+ *
+ * @param db - Database connection (within a transaction)
+ * @param taskId - The task to update
+ * @param target - Target state being moved to
+ * @param current - Current state
+ * @param context - Optional context fields
+ */
+export declare function recordStateFields(db: Database.Database, taskId: string, target: TaskStatus, current: TaskStatus, context?: MoveContext): void;
+//# sourceMappingURL=state-field-recorder.d.ts.map

package/dist/validators/state-field-recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-field-recorder.d.ts","sourceRoot":"","sources":["../../src/validators/state-field-recorder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,WAAW,GACpB;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CA4B1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE,WAAW,GACpB,IAAI,CAIN"}

package/dist/validators/state-field-recorder.js

@@ -0,0 +1,62 @@
+"use strict";
+// State field recorder
+// Records state-specific context fields on task state transitions
+// Implements AD-0014: Nullable Columns for State-Specific Fields
+// + FS-SS-005-0012 (record state-specific fields on move)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeStateFields = computeStateFields;
+exports.recordStateFields = recordStateFields;
+/**
+ * Compute the timestamp updates and field values to record for a transition.
+ *
+ * State-specific rules:
+ * - In Progress: record session_key if provided, auto-set started_at
+ * - In Review: record owner if provided (tasks.owner column)
+ * - Done: auto-set completed_at
+ *
+ * Note: blocker context field removed per FS-SS-030-0004
+ * Note: reviewer renamed to owner, review_notes removed per FR-URD-034-0006
+ *
+ * Returns the partial row updates to apply to the task.
+ */
+function computeStateFields(current, target, context) {
+    const now = new Date().toISOString();
+    const columns = ['status = ?', 'updated_at = ?'];
+    const values = [target, now];
+    // Auto-timestamps
+    if (current !== 'In Progress' && target === 'In Progress') {
+        columns.push('started_at = ?');
+        values.push(now);
+    }
+    if (target === 'Done') {
+        columns.push('completed_at = ?');
+        values.push(now);
+    }
+    // State-specific fields from context
+    if (target === 'In Progress' && context?.session_key) {
+        columns.push('session_key = ?');
+        values.push(context.session_key);
+    }
+    if (target === 'In Review') {
+        if (context?.owner) {
+            columns.push('owner = ?');
+            values.push(context.owner);
+        }
+    }
+    return { columns, values };
+}
+/**
+ * Apply state-specific field updates to a task in the database.
+ *
+ * @param db - Database connection (within a transaction)
+ * @param taskId - The task to update
+ * @param target - Target state being moved to
+ * @param current - Current state
+ * @param context - Optional context fields
+ */
+function recordStateFields(db, taskId, target, current, context) {
+    const { columns, values } = computeStateFields(current, target, context);
+    const sql = `UPDATE tasks SET ${columns.join(', ')} WHERE id = ?`;
+    db.prepare(sql).run(...values, taskId);
+}
+//# sourceMappingURL=state-field-recorder.js.map

package/dist/validators/state-field-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-field-recorder.js","sourceRoot":"","sources":["../../src/validators/state-field-recorder.ts"],"names":[],"mappings":";AAAA,uBAAuB;AACvB,kEAAkE;AAClE,iEAAiE;AACjE,0DAA0D;;AA4B1D,gDAgCC;AAWD,8CAUC;AAlED;;;;;;;;;;;;GAYG;AACH,SAAgB,kBAAkB,CAChC,OAAmB,EACnB,MAAkB,EAClB,OAAqB;IAErB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,OAAO,GAAa,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAExC,kBAAkB;IAClB,IAAI,OAAO,KAAK,aAAa,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IAED,qCAAqC;IACrC,IAAI,MAAM,KAAK,aAAa,IAAI,OAAO,EAAE,WAAW,EAAE,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;QAC3B,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAC/B,EAAqB,EACrB,MAAc,EACd,MAAkB,EAClB,OAAmB,EACnB,OAAqB;IAErB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,oBAAoB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC;IAClE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@lwelliott/cortex-cli",
+  "version": "1.0.3",
+  "description": "A TypeScript CLI for managing software project artifacts backed by SQLite",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lwelliot/cortex-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lwelliot/cortex-cli/issues"
+  },
+  "homepage": "https://github.com/lwelliot/cortex-cli#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/cli/index.js",
+  "bin": {
+    "cortex-cli": "dist/cli/index.js"
+  },
+  "scripts": {
+    "generate:schema": "node scripts/generate-schema-types.js",
+    "build": "npm run generate:schema && tsc",
+    "build:release": "npm run build && node scripts/bundle-release.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit"
+  },
+  "files": [
+    "dist/**/*",
+    "!dist/cortex-cli.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": ["cli", "project-management", "sprint", "kanban", "sqlite", "typescript"],
+  "author": "lwelliot",
+  "dependencies": {
+    "better-sqlite3": "^11.7.0",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.1.0",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^2.1.8",
+    "esbuild": "^0.28.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.8"
+  }
+}