@web42/stask 0.1.5

package/commands/sync.mjs

@@ -0,0 +1,36 @@
+/**
+ * sync.mjs — Run one bidirectional sync cycle (Slack ↔ DB).
+ *
+ * Usage: stask sync [--json]
+ */
+
+import { runSyncCycle } from '../lib/slack-sync.mjs';
+
+export async function run(argv) {
+  const json = argv.includes('--json');
+
+  const summary = await runSyncCycle();
+
+  if (json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  if (summary.pulled.length > 0) {
+    console.log(`Pulled from Slack: ${summary.pulled.join(', ')}`);
+  }
+  if (summary.pushed.length > 0) {
+    console.log(`Pushed to Slack: ${summary.pushed.join(', ')}`);
+  }
+  if (summary.deleted.length > 0) {
+    console.log(`Deleted (removed from Slack): ${summary.deleted.join(', ')}`);
+  }
+  if (summary.errors.length > 0) {
+    console.error(`Errors:`);
+    for (const err of summary.errors) console.error(`  - ${err}`);
+  }
+  if (summary.pulled.length === 0 && summary.pushed.length === 0 && summary.errors.length === 0) {
+    console.log(`In sync. (${summary.skipped} tasks checked)`);
+  }
+}

package/commands/transition.mjs

@@ -0,0 +1,143 @@
+/**
+ * stask transition — Transition a task's status with DB-enforced validation.
+ *
+ * Usage: stask transition <task-id> <new-status>
+ *
+ * Handles side effects: worktree creation, PR creation, cleanup,
+ * auto-assignment, and subtask cascading.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { CONFIG, LIB_DIR, getWorkspaceLibs } from '../lib/env.mjs';
+import { withTransaction } from '../lib/tx.mjs';
+import { syncTaskToSlack } from '../lib/slack-row.mjs';
+import { getAutoAssign } from '../lib/roles.mjs';
+import { runGuards } from '../lib/guards.mjs';
+
+const TRIGGER_SQL = `
+  CREATE TRIGGER validate_status_transition
+  BEFORE UPDATE OF status ON tasks WHEN OLD.status != NEW.status
+  BEGIN SELECT CASE
+    WHEN OLD.status = 'Done' THEN RAISE(ABORT, 'Cannot transition from Done')
+    WHEN OLD.status = 'To-Do' AND NEW.status NOT IN ('In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid transition from To-Do')
+    WHEN OLD.status = 'In-Progress' AND NEW.status NOT IN ('Testing','Blocked') THEN RAISE(ABORT, 'Invalid transition from In-Progress')
+    WHEN OLD.status = 'Testing' AND NEW.status NOT IN ('Ready for Human Review','In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid transition from Testing')
+    WHEN OLD.status = 'Ready for Human Review' AND NEW.status NOT IN ('Done','In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid transition from Ready for Human Review')
+    WHEN OLD.status = 'Blocked' AND NEW.status NOT IN ('To-Do','In-Progress','Testing','Ready for Human Review') THEN RAISE(ABORT, 'Invalid transition from Blocked')
+  END; END;
+`;
+
+export async function run(argv) {
+  const taskId = argv[0];
+  const newStatus = argv[1];
+  const libs = await getWorkspaceLibs();
+  const { STATUSES } = libs.validate;
+
+  if (!taskId || !newStatus) {
+    console.error('Usage: stask transition <task-id> <new-status>');
+    console.error(`Valid statuses: ${STATUSES.join(', ')}`);
+    process.exit(1);
+  }
+
+  if (!STATUSES.includes(newStatus)) {
+    console.error(`ERROR: Unknown status "${newStatus}". Valid: ${STATUSES.join(', ')}`);
+    process.exit(1);
+  }
+
+  const task = libs.trackerDb.findTask(taskId);
+  if (!task) { console.error(`ERROR: Task ${taskId} not found`); process.exit(1); }
+
+  const oldStatus = task['Status'];
+  const isParent = task['Parent'] === 'None';
+
+  // Run guards (checks + setup side effects like worktree/PR creation)
+  const { ok, failures } = runGuards(task, newStatus, libs);
+  if (!ok) {
+    console.error(`\nTransition ${taskId}: ${oldStatus} → ${newStatus} BLOCKED by ${failures.length} guard(s).`);
+    process.exit(1);
+  }
+
+  const autoAssign = getAutoAssign(newStatus);
+
+  const result = await withTransaction(
+    (db, libs) => {
+      const updates = { status: newStatus };
+      if (autoAssign) updates.assigned_to = autoAssign;
+
+      // Clear PR status when moving to Testing or RHR (feedback addressed)
+      if (newStatus === 'Testing' || newStatus === 'Ready for Human Review') {
+        updates.pr_status = null;
+      }
+
+      libs.trackerDb.updateTask(taskId, updates);
+
+      const assignMsg = autoAssign ? ` Assigned: ${autoAssign}.` : '';
+      libs.trackerDb.addLogEntry(taskId, `${taskId} "${task['Task Name']}": ${oldStatus} → ${newStatus}.${assignMsg}`);
+
+      // Cascade to subtasks
+      const subtasks = libs.trackerDb.getSubtasks(taskId);
+      const cascaded = [];
+      if (subtasks.length > 0) {
+        db.exec('DROP TRIGGER IF EXISTS validate_status_transition');
+        try {
+          for (const sub of subtasks) {
+            if (sub['Status'] === 'Done' || sub['Status'] === newStatus) continue;
+            const subUpdates = { status: newStatus };
+            // In-Progress keeps existing builder assignments
+            if (newStatus !== 'In-Progress' && autoAssign) subUpdates.assigned_to = autoAssign;
+
+            const sets = Object.keys(subUpdates).map(k => `${k} = ?`).join(', ');
+            db.prepare(`UPDATE tasks SET ${sets} WHERE task_id = ?`)
+              .run(...Object.values(subUpdates), sub['Task ID']);
+            cascaded.push(sub['Task ID']);
+            console.log(`  ${sub['Task ID']}: ${sub['Status']} → ${newStatus} | Assigned: ${subUpdates.assigned_to || sub['Assigned To']}`);
+          }
+        } finally {
+          db.exec(TRIGGER_SQL);
+        }
+      }
+
+      const updatedTask = libs.trackerDb.findTask(taskId);
+      const cascadedTasks = cascaded.map(id => libs.trackerDb.findTask(id));
+      return { taskId, taskRow: updatedTask, cascadedTasks, oldStatus, newStatus };
+    },
+    async ({ taskRow, cascadedTasks }, db) => {
+      const allOps = [];
+      const { slackOps } = await syncTaskToSlack(db, taskRow);
+      allOps.push(...slackOps);
+      for (const sub of cascadedTasks) {
+        if (!sub) continue;
+        try {
+          const { slackOps: subOps } = await syncTaskToSlack(db, sub);
+          allOps.push(...subOps);
+        } catch (err) {
+          console.error(`WARNING: Slack sync failed for subtask ${sub['Task ID']}: ${err.message}`);
+        }
+      }
+      return allOps;
+    }
+  );
+
+  // Post-commit cleanup (best effort)
+  if (newStatus === 'Done') {
+    const parsed = task['Spec']?.match(/^(.+?)\s*\(/);
+    if (parsed) {
+      const specPath = path.resolve(CONFIG.specsDir, 'shared', parsed[1].trim());
+      if (fs.existsSync(specPath)) { fs.unlinkSync(specPath); console.error(`Removed local spec: ${parsed[1].trim()}`); }
+    }
+    // Clean up PR status report
+    const prStatusPath = path.resolve(CONFIG.staskHome, 'pr-status', `${taskId}.md`);
+    if (fs.existsSync(prStatusPath)) { fs.unlinkSync(prStatusPath); console.error(`Removed PR status: pr-status/${taskId}.md`); }
+    if (isParent && task['Worktree'] !== 'None') {
+      try {
+        execFileSync(process.execPath, [path.join(LIB_DIR, 'worktree-cleanup.mjs'), taskId], {
+          encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+        });
+      } catch (err) { console.error(`WARNING: Worktree cleanup failed: ${err.stderr || err.message}`); }
+    }
+  }
+
+  console.log(`${taskId}: "${task['Task Name']}" | ${oldStatus} → ${newStatus} | Assigned: ${autoAssign || task['Assigned To']}`);
+}

package/config.example.json

@@ -0,0 +1,55 @@
+{
+  "specsDir": "/path/to/your/specs",
+  "projectRepoPath": "/path/to/your/git/repo",
+  "worktreeBaseDir": "/path/to/worktrees",
+  "staleSessionMinutes": 30,
+  "syncIntervalSeconds": 60,
+  "maxQaRetries": 3,
+
+  "human": {
+    "name": "YourName",
+    "slackUserId": "UXXXXXXXXXX",
+    "githubUsername": "your-github-username"
+  },
+
+  "agents": {
+    "lead-agent":   { "role": "lead",   "slackUserId": "UXXXXXXXXXX" },
+    "worker-1":     { "role": "worker", "slackUserId": "UXXXXXXXXXX" },
+    "worker-2":     { "role": "worker", "slackUserId": "UXXXXXXXXXX" },
+    "qa-agent":     { "role": "qa",     "slackUserId": "UXXXXXXXXXX" }
+  },
+
+  "slack": {
+    "listId": "FROM_ENV",
+    "columns": {
+      "name":          "ColXXXXXXXXX",
+      "task_id":       "ColXXXXXXXXX",
+      "status":        "ColXXXXXXXXX",
+      "assignee":      "ColXX",
+      "spec":          "ColXXXXXXXXX",
+      "type":          "ColXXXXXXXXX",
+      "worktree":      "ColXXXXXXXXX",
+      "pr":            "ColXXXXXXXXX",
+      "qa_report_1":   "ColXXXXXXXXX",
+      "qa_report_2":   "ColXXXXXXXXX",
+      "qa_report_3":   "ColXXXXXXXXX",
+      "completed":     "ColXX",
+      "spec_approved": "ColXXXXXXXXX",
+      "pr_status":     "ColXXXXXXXXX"
+    },
+    "statusOptions": {
+      "To-Do":                    "OptXXXXXXXXX",
+      "In-Progress":              "OptXXXXXXXXX",
+      "Testing":                  "OptXXXXXXXXX",
+      "Ready for Human Review":   "OptXXXXXXXXX",
+      "Blocked":                  "OptXXXXXXXXX",
+      "Done":                     "OptXXXXXXXXX"
+    },
+    "typeOptions": {
+      "Feature":     "OptXXXXXXXXX",
+      "Bug":         "OptXXXXXXXXX",
+      "Improvement": "OptXXXXXXXXX",
+      "Research":    "OptXXXXXXXXX"
+    }
+  }
+}

package/lib/env.mjs

@@ -0,0 +1,118 @@
+/**
+ * env.mjs — Loads config.json from ~/.stask/, auto-loads .env,
+ * resolves global paths, and imports bundled libs.
+ *
+ * Global data dir: ~/.stask/ (override with STASK_HOME env var)
+ * Contains: config.json, .env, tracker.db, FILE_REGISTRY.json, logs/, pr-status/
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ─── STASK_HOME — global data directory ───────────────────────────
+
+export const STASK_HOME = process.env.STASK_HOME || path.join(os.homedir(), '.stask');
+
+// ─── Load config.json from STASK_HOME ─────────────────────────────
+
+let _config = null;
+
+export function loadConfig() {
+  if (_config) return _config;
+
+  const configPath = path.join(STASK_HOME, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    console.error(`ERROR: Config not found at ${configPath}`);
+    console.error(`Run: mkdir -p ~/.stask && cp config.example.json ~/.stask/config.json`);
+    process.exit(1);
+  }
+
+  const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+
+  // staskRoot = package install dir (for finding lib/ scripts)
+  const staskRoot = path.resolve(__dirname, '..');
+
+  _config = {
+    ...raw,
+    // Resolved absolute paths — all runtime data lives in STASK_HOME
+    staskRoot,
+    staskHome: STASK_HOME,
+    dbPath: path.join(STASK_HOME, 'tracker.db'),
+    envFile: path.join(STASK_HOME, '.env'),
+    registryPath: path.join(STASK_HOME, 'FILE_REGISTRY.json'),
+    // Backward compat: expose specsDir as workspace too
+    workspace: raw.specsDir,
+  };
+  return _config;
+}
+
+// ─── Auto-load .env into process.env ───────────────────────────────
+
+let _envLoaded = false;
+
+export function loadEnv() {
+  if (_envLoaded) return;
+  const config = loadConfig();
+  try {
+    const lines = fs.readFileSync(config.envFile, 'utf-8').split('\n');
+    for (const line of lines) {
+      const match = line.match(/^([^#=]+)=(.*)$/);
+      if (match) {
+        const key = match[1].trim();
+        const val = match[2].trim();
+        if (!process.env[key]) process.env[key] = val;
+      }
+    }
+  } catch (err) {
+    console.error(`WARNING: Could not load env file ${config.envFile}: ${err.message}`);
+  }
+  _envLoaded = true;
+
+  // Override listId from env if config says FROM_ENV
+  if (config.slack?.listId === 'FROM_ENV' && process.env.LIST_ID) {
+    config.slack.listId = process.env.LIST_ID;
+  }
+}
+
+// ─── Local lib imports (all bundled in stask/lib/) ─────────────────
+
+import * as _slackApi from './slack-api.mjs';
+import * as _fileUploader from './file-uploader.mjs';
+import * as _trackerDb from './tracker-db.mjs';
+import * as _validate from './validate.mjs';
+
+const _workspaceLibs = {
+  slackApi: _slackApi,
+  fileUploader: _fileUploader,
+  trackerDb: _trackerDb,
+  validate: _validate,
+};
+
+export async function getWorkspaceLibs() {
+  return _workspaceLibs;
+}
+
+// ─── Pipeline config (stale thresholds, etc.) ─────────────────────
+
+let _pipelineConfig = null;
+
+export function getPipelineConfig() {
+  if (_pipelineConfig) return _pipelineConfig;
+  const config = loadConfig();
+  _pipelineConfig = {
+    staleSessionMinutes: config.staleSessionMinutes || 30,
+    maxRetries: config.maxQaRetries || 3,
+  };
+  return _pipelineConfig;
+}
+
+// ─── Convenience exports ───────────────────────────────────────────
+
+export const CONFIG = loadConfig();
+
+// Absolute path to stask/lib/ — used by execFileSync callers
+export const LIB_DIR = __dirname;

package/lib/file-uploader.mjs

@@ -0,0 +1,179 @@
+/**
+ * file-uploader.mjs — Scans workspace files, uploads new/changed ones to Slack,
+ * and maintains FILE_REGISTRY.json for agent file references.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { uploadFile, logger } from './slack-api.mjs';
+
+const config = {
+  maxFileSizeBytes: 102400,
+  dryRun: process.argv.includes('--dry-run'),
+};
+
+const UPLOAD_GLOBS = [
+  'shared/specs/*.md',
+  'shared/artifacts/*.md',
+  'shared/qa-reports/*.md',
+  'shared/qa-reports/screenshots/*.png',
+  'shared/pr-status/*.md',
+];
+
+/**
+ * Simple glob matching (supports * and **).
+ */
+function matchGlob(filePath, pattern) {
+  const regex = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*\*\//g, '(.+/)?')
+    .replace(/\*/g, '[^/]+');
+  return new RegExp(`^${regex}$`).test(filePath);
+}
+
+/**
+ * Recursively walk a directory and return all file paths relative to base.
+ */
+function walkDir(dir, base = dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (['.git', 'node_modules', 'sessions', 'skills', '.web42'].includes(entry.name)) continue;
+      results.push(...walkDir(full, base));
+    } else {
+      results.push(path.relative(base, full));
+    }
+  }
+  return results;
+}
+
+/**
+ * Scan workspace for files matching UPLOAD_GLOBS.
+ * Returns array of relative paths.
+ */
+export function scanWorkspace(basePath) {
+  const allFiles = walkDir(basePath);
+  const matched = [];
+  for (const file of allFiles) {
+    for (const glob of UPLOAD_GLOBS) {
+      if (matchGlob(file, glob)) {
+        matched.push(file);
+        break;
+      }
+    }
+  }
+  return matched.sort();
+}
+
+/**
+ * Load registry from disk. Returns { version, updatedAt, files: {} }.
+ */
+export function loadRegistry(registryPath) {
+  try {
+    return JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+  } catch {
+    return { version: 1, updatedAt: null, files: {} };
+  }
+}
+
+/**
+ * Save registry to disk.
+ */
+export function saveRegistry(registryPath, registry) {
+  registry.updatedAt = new Date().toISOString();
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+}
+
+/**
+ * Hash file content (SHA-256, first 16 hex chars).
+ */
+function hashContent(content) {
+  return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+/**
+ * Sync workspace files to Slack.
+ * Uploads new/changed files, skips unchanged ones (content-hash dedup).
+ * Returns updated registry.
+ */
+export async function syncFiles(basePath, registry) {
+  const files = scanWorkspace(basePath);
+  logger.info(`Scanned workspace: ${files.length} files match upload globs`);
+
+  let uploaded = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  for (const relPath of files) {
+    const fullPath = path.join(basePath, relPath);
+    let content;
+
+    try {
+      const stat = fs.statSync(fullPath);
+      if (stat.size > config.maxFileSizeBytes) {
+        logger.debug(`Skipping ${relPath} (${stat.size} bytes > ${config.maxFileSizeBytes} limit)`);
+        skipped++;
+        continue;
+      }
+      content = fs.readFileSync(fullPath, 'utf-8');
+    } catch (err) {
+      logger.warn(`Cannot read ${relPath}: ${err.message}`);
+      errors++;
+      continue;
+    }
+
+    const hash = hashContent(content);
+    const existing = registry.files[relPath];
+
+    if (existing && existing.hash === hash) {
+      skipped++;
+      continue;
+    }
+
+    if (config.dryRun) {
+      logger.info(`DRY RUN: Would upload ${relPath} (${content.length} chars, hash ${hash})`);
+      uploaded++;
+      continue;
+    }
+
+    try {
+      const filename = path.basename(relPath);
+      const fileId = await uploadFile(filename, content);
+      registry.files[relPath] = {
+        fileId,
+        hash,
+        title: filename,
+        uploadedAt: new Date().toISOString(),
+        sizeBytes: Buffer.byteLength(content, 'utf-8'),
+      };
+      uploaded++;
+      logger.debug(`Uploaded ${relPath} → ${fileId} (${content.length} chars)`);
+    } catch (err) {
+      logger.error(`Failed to upload ${relPath}: ${err.message}`);
+      errors++;
+    }
+  }
+
+  logger.info(`File sync: ${uploaded} uploaded, ${skipped} unchanged, ${errors} errors`);
+  return registry;
+}
+
+/**
+ * Look up a Slack file ID from the registry by relative path.
+ * Handles paths with or without backticks, leading shared/, etc.
+ */
+export function resolveFileId(registry, specValue) {
+  if (!specValue || specValue === 'N/A') return null;
+  let p = specValue.trim().replace(/^`|`$/g, '');
+  // Try exact match
+  if (registry.files[p]) return registry.files[p].fileId;
+  // Try with shared/ prefix
+  if (registry.files['shared/' + p]) return registry.files['shared/' + p].fileId;
+  // Try prepending specs/
+  if (registry.files['shared/specs/' + path.basename(p)]) {
+    return registry.files['shared/specs/' + path.basename(p)].fileId;
+  }
+  return null;
+}