@stackmemoryai/stackmemory 1.10.5 → 1.14.0

package/dist/src/cli/commands/state.js

@@ -0,0 +1,265 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { Command } from "commander";
+import chalk from "chalk";
+import {
+  canonicalStateStore
+} from "../../core/shared-state/canonical-store.js";
+import {
+  getCurrentRepoGitHubInfo,
+  refreshCurrentRepoPullRequestState
+} from "../../integrations/github/pr-state.js";
+function parseJsonObject(input) {
+  if (!input) {
+    return {};
+  }
+  const parsed = JSON.parse(input);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Expected a JSON object");
+  }
+  return parsed;
+}
+function createStateCommand() {
+  const cmd = new Command("state").description(
+    "Manage canonical user-scoped shared state across instances and sessions"
+  );
+  const instance = cmd.command("instance").description("Manage instance state");
+  instance.command("upsert").requiredOption("--id <id>", "Instance identifier").requiredOption(
+    "--tool <tool>",
+    "Tool name (claude|codex|opencode|stackmemory)"
+  ).option("--session <id>", "Session identifier").option("--project <id>", "Project identifier").option("--project-path <path>", "Project path").option("--branch <branch>", "Git branch").option("--worktree-path <path>", "Worktree path").option("--pid <pid>", "Process id").option("--status <status>", "Status", "active").option("--metadata <json>", "Metadata JSON object").action(async (options) => {
+    const record = await canonicalStateStore.upsertInstance({
+      instanceId: options.id,
+      tool: options.tool,
+      sessionId: options.session,
+      projectId: options.project,
+      projectPath: options.projectPath,
+      branch: options.branch,
+      worktreePath: options.worktreePath,
+      pid: options.pid ? Number(options.pid) : void 0,
+      status: options.status,
+      metadata: parseJsonObject(options.metadata)
+    });
+    console.log(JSON.stringify(record, null, 2));
+  });
+  instance.command("end").requiredOption("--id <id>", "Instance identifier").action(async (options) => {
+    await canonicalStateStore.endInstance(options.id);
+    console.log(chalk.green(`Ended instance ${options.id}`));
+  });
+  const session = cmd.command("session").description("Manage session state");
+  session.command("upsert").requiredOption("--id <id>", "Session identifier").requiredOption(
+    "--tool <tool>",
+    "Tool name (claude|codex|opencode|stackmemory)"
+  ).option("--project <id>", "Project identifier").option("--project-path <path>", "Project path").option("--branch <branch>", "Git branch").option("--instance <id>", "Associated instance identifier").option("--status <status>", "Status", "active").option("--metadata <json>", "Metadata JSON object").action(async (options) => {
+    const record = await canonicalStateStore.upsertSession({
+      sessionId: options.id,
+      tool: options.tool,
+      projectId: options.project,
+      projectPath: options.projectPath,
+      branch: options.branch,
+      instanceId: options.instance,
+      status: options.status,
+      metadata: parseJsonObject(options.metadata)
+    });
+    console.log(JSON.stringify(record, null, 2));
+  });
+  session.command("end").requiredOption("--id <id>", "Session identifier").option("--status <status>", "Status", "closed").action(async (options) => {
+    await canonicalStateStore.endSession(options.id, options.status);
+    console.log(chalk.green(`Ended session ${options.id}`));
+  });
+  cmd.command("event").description("Append a shared-state event").requiredOption("--type <type>", "Event type").option("--tool <tool>", "Tool name (claude|codex|opencode|stackmemory)").option("--instance <id>", "Instance identifier").option("--session <id>", "Session identifier").option("--project <id>", "Project identifier").option("--project-path <path>", "Project path").option("--branch <branch>", "Git branch").option("--payload <json>", "Payload JSON object").action(async (options) => {
+    const event = await canonicalStateStore.appendEvent({
+      type: options.type,
+      tool: options.tool,
+      instanceId: options.instance,
+      sessionId: options.session,
+      projectId: options.project,
+      projectPath: options.projectPath,
+      branch: options.branch,
+      payload: parseJsonObject(options.payload)
+    });
+    console.log(JSON.stringify(event, null, 2));
+  });
+  cmd.command("show").description("Show canonical shared state for a project").option("--project <id>", "Project identifier").option("--project-path <path>", "Project path").option("--limit <count>", "Recent event limit", "10").option("--json", "Emit JSON output").action(async (options) => {
+    const summary = await canonicalStateStore.getProjectSummary({
+      projectId: options.project,
+      projectPath: options.projectPath,
+      eventLimit: Number(options.limit)
+    });
+    if (options.json) {
+      console.log(JSON.stringify(summary, null, 2));
+      return;
+    }
+    console.log(chalk.bold("Canonical Shared State"));
+    console.log(
+      `  Active sessions: ${summary.activeSessions.length} | Active instances: ${summary.activeInstances.length} | Active claims: ${summary.activeClaims.length}`
+    );
+    if (summary.projectId) {
+      console.log(`  Project: ${summary.projectId}`);
+    }
+    if (summary.activeSessions.length > 0) {
+      console.log(chalk.bold("\nSessions"));
+      for (const record of summary.activeSessions) {
+        console.log(
+          `  ${record.sessionId.slice(0, 8)} ${record.tool} ${record.branch || ""}`.trim()
+        );
+      }
+    }
+    if (summary.activeInstances.length > 0) {
+      console.log(chalk.bold("\nInstances"));
+      for (const record of summary.activeInstances) {
+        console.log(
+          `  ${record.instanceId} ${record.tool} ${record.branch || ""}`.trim()
+        );
+      }
+    }
+    if (summary.activeClaims.length > 0) {
+      console.log(chalk.bold("\nClaims"));
+      for (const claim of summary.activeClaims) {
+        const scopes = [
+          claim.branch ? `branch:${claim.branch}` : "",
+          ...claim.paths.map((item) => `path:${item}`)
+        ].filter(Boolean).join(", ");
+        console.log(
+          `  ${claim.claimId.slice(0, 8)} ${claim.tool} ${scopes || "(no scope)"}`.trim()
+        );
+      }
+    }
+    if (summary.recentEvents.length > 0) {
+      console.log(chalk.bold("\nRecent events"));
+      for (const event of summary.recentEvents) {
+        console.log(
+          `  ${event.type} ${new Date(event.timestamp).toISOString()}`
+        );
+      }
+    }
+  });
+  const claims = cmd.command("claims").description("Manage shared ownership claims");
+  claims.command("claim").requiredOption(
+    "--tool <tool>",
+    "Tool name (claude|codex|opencode|stackmemory)"
+  ).option("--session <id>", "Session identifier").option("--instance <id>", "Instance identifier").option("--project <id>", "Project identifier").option("--project-path <path>", "Project path").option("--branch <branch>", "Git branch").option("--path <path...>", "Claimed file or directory path(s)").option("--ttl-ms <ttl>", "Time to live in milliseconds", "86400000").option("--metadata <json>", "Metadata JSON object").option("--json", "Emit JSON output").action(async (options) => {
+    const result = await canonicalStateStore.claimPaths({
+      tool: options.tool,
+      sessionId: options.session,
+      instanceId: options.instance,
+      projectId: options.project,
+      projectPath: options.projectPath,
+      branch: options.branch,
+      paths: options.path || [],
+      ttlMs: Number(options.ttlMs),
+      metadata: parseJsonObject(options.metadata)
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(chalk.green(`Claimed ${result.record.claimId.slice(0, 8)}`));
+    if (result.conflicts.length > 0) {
+      console.log(chalk.yellow(`Conflicts: ${result.conflicts.length}`));
+      for (const conflict of result.conflicts) {
+        console.log(
+          `  ${conflict.claimId.slice(0, 8)} ${conflict.branch || ""} ${conflict.paths.join(", ")}`.trim()
+        );
+      }
+    }
+  });
+  claims.command("release").option("--claim <id>", "Claim identifier").option("--session <id>", "Session identifier").option("--instance <id>", "Instance identifier").option("--project <id>", "Project identifier").option("--project-path <path>", "Project path").option("--branch <branch>", "Git branch").option("--reason <reason>", "Release reason").action(async (options) => {
+    const released = await canonicalStateStore.releaseClaims({
+      claimId: options.claim,
+      sessionId: options.session,
+      instanceId: options.instance,
+      projectId: options.project,
+      projectPath: options.projectPath,
+      branch: options.branch,
+      reason: options.reason
+    });
+    console.log(chalk.green(`Released ${released} claim(s)`));
+  });
+  claims.command("show").option("--project <id>", "Project identifier").option("--project-path <path>", "Project path").option("--all", "Show released and expired claims too").option("--json", "Emit JSON output").action(async (options) => {
+    const records = await canonicalStateStore.listPathClaims({
+      projectId: options.project,
+      projectPath: options.projectPath,
+      activeOnly: !options.all
+    });
+    if (options.json) {
+      console.log(JSON.stringify(records, null, 2));
+      return;
+    }
+    if (records.length === 0) {
+      console.log(chalk.yellow("No claims found"));
+      return;
+    }
+    for (const claim of records) {
+      const scopes = [
+        claim.branch ? `branch:${claim.branch}` : "",
+        ...claim.paths.map((item) => `path:${item}`)
+      ].filter(Boolean).join(", ");
+      console.log(
+        `${claim.claimId.slice(0, 8)} ${claim.status} ${claim.tool} ${scopes || "(no scope)"}`
+      );
+    }
+  });
+  const github = cmd.command("github").description("GitHub projection state");
+  github.command("refresh").description("Refresh current repo branch PR state from GitHub CLI").option("--json", "Emit JSON output").action(async (options) => {
+    const projection = await refreshCurrentRepoPullRequestState();
+    if (!projection) {
+      console.log(
+        chalk.yellow(
+          "No GitHub PR projection available for current repo/branch"
+        )
+      );
+      return;
+    }
+    if (options.json) {
+      console.log(JSON.stringify(projection, null, 2));
+      return;
+    }
+    console.log(chalk.green(`Refreshed PR #${projection.prNumber}`));
+    console.log(`${projection.state} ${projection.title}`);
+    console.log(projection.url);
+  });
+  github.command("show").description("Show cached current repo branch PR projection").option("--json", "Emit JSON output").action(async (options) => {
+    const info = getCurrentRepoGitHubInfo();
+    if (!info) {
+      console.log(chalk.yellow("Not in a GitHub repository"));
+      return;
+    }
+    const projection = await canonicalStateStore.getGitHubPullRequest({
+      repo: info.repo,
+      branch: info.branch
+    });
+    if (!projection) {
+      console.log(
+        chalk.yellow("No cached GitHub PR projection for current branch")
+      );
+      return;
+    }
+    if (options.json) {
+      console.log(JSON.stringify(projection, null, 2));
+      return;
+    }
+    console.log(chalk.bold(`PR #${projection.prNumber}`));
+    console.log(`${projection.state} ${projection.title}`);
+    console.log(`Repo: ${projection.repo}`);
+    console.log(
+      `Branch: ${projection.headRefName} -> ${projection.baseRefName}`
+    );
+    if (projection.reviewDecision) {
+      console.log(`Review: ${projection.reviewDecision}`);
+    }
+    if (projection.statusCheckRollup) {
+      console.log(`Checks: ${projection.statusCheckRollup}`);
+    }
+    console.log(`Synced: ${new Date(projection.lastSyncedAt).toISOString()}`);
+    console.log(projection.url);
+  });
+  return cmd;
+}
+var state_default = createStateCommand;
+export {
+  createStateCommand,
+  state_default as default
+};

package/dist/src/cli/commands/sync.js

@@ -0,0 +1,253 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { Command } from "commander";
+import chalk from "chalk";
+import { homedir, hostname } from "os";
+import { join } from "path";
+import { existsSync, readFileSync } from "fs";
+import { createHash } from "crypto";
+import Database from "better-sqlite3";
+import { CloudSyncEngine } from "../../core/storage/cloud-sync.js";
+const DEFAULT_ENDPOINT = "https://provenant-api.jpwu03.workers.dev";
+function loadSyncConfig(projectDir) {
+  const envKey = process.env["PROVENANT_API_KEY"];
+  const envProject = process.env["PROVENANT_PROJECT_ID"];
+  if (envKey) {
+    return buildConfig(
+      envKey,
+      envProject || createHash("sha256").update(projectDir).digest("hex").slice(0, 16),
+      process.env["PROVENANT_API_URL"] || DEFAULT_ENDPOINT,
+      projectDir
+    );
+  }
+  const cfgPath = join(homedir(), ".stackmemory", "config.json");
+  if (!existsSync(cfgPath)) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+    if (!cfg.auth?.apiKey) return null;
+    return buildConfig(
+      cfg.auth.apiKey,
+      cfg.auth.projectId || createHash("sha256").update(projectDir).digest("hex").slice(0, 16),
+      cfg.auth.apiUrl || DEFAULT_ENDPOINT,
+      projectDir
+    );
+  } catch {
+    return null;
+  }
+}
+function buildConfig(apiKey, projectId, endpoint, projectDir) {
+  return {
+    enabled: true,
+    endpoint,
+    apiKey,
+    projectId,
+    clientId: createHash("sha256").update(hostname() + projectDir).digest("hex").slice(0, 16),
+    batchSize: 100,
+    conflictResolution: "newest_wins",
+    generationalPolicy: {
+      youngMaxAgeDays: 1,
+      matureMaxAgeDays: 7
+    },
+    timeoutMs: 3e4,
+    retryAttempts: 3,
+    retryBaseDelayMs: 1e3
+  };
+}
+function getDbPath(projectDir) {
+  const contextDb = join(projectDir, ".stackmemory", "context.db");
+  if (existsSync(contextDb)) return contextDb;
+  const localDb = join(projectDir, ".stackmemory", "stackmemory.db");
+  if (existsSync(localDb)) return localDb;
+  const globalDb = join(homedir(), ".stackmemory", "stackmemory.db");
+  if (existsSync(globalDb)) return globalDb;
+  return contextDb;
+}
+function createLoginCommand() {
+  const cmd = new Command("login").description("Connect to Provenant cloud sync").argument("<email>", "Your email address").option("--workspace <name>", "Workspace name (for new accounts)").option("--reset", "Reset API key (revokes existing keys)").action(
+    async (email, options) => {
+      const endpoint = process.env["PROVENANT_API_URL"] || DEFAULT_ENDPOINT;
+      try {
+        const path = options.reset ? "/v1/setup/reset" : "/v1/setup";
+        const body = { email };
+        if (!options.reset) {
+          body["workspaceName"] = options.workspace ?? email.split("@")[0];
+        }
+        const res = await fetch(`${endpoint}${path}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body)
+        });
+        const data = await res.json();
+        if (res.status === 409 && !options.reset) {
+          console.log(
+            chalk.yellow("Workspace already exists for this email.")
+          );
+          console.log(chalk.dim("  Run: stackmemory login <email> --reset"));
+          console.log(chalk.dim(`  Workspace ID: ${data.workspaceId}`));
+          console.log(chalk.dim(`  Project ID:   ${data.projectId}`));
+          return;
+        }
+        if (!res.ok || !data.apiKey) {
+          console.error(
+            chalk.red(`Login failed: ${data.error || res.statusText}`)
+          );
+          process.exit(1);
+        }
+        const smDir = join(homedir(), ".stackmemory");
+        const cfgPath = join(smDir, "config.json");
+        let cfg = {};
+        if (existsSync(cfgPath)) {
+          try {
+            cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+          } catch {
+          }
+        }
+        cfg["auth"] = {
+          apiKey: data.apiKey,
+          apiUrl: endpoint,
+          projectId: data.projectId,
+          workspaceId: data.workspaceId,
+          email
+        };
+        const { writeFileSync, mkdirSync } = await import("fs");
+        mkdirSync(smDir, { recursive: true });
+        writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
+        console.log(chalk.green("Logged in to Provenant cloud sync."));
+        console.log(chalk.dim(`  Workspace: ${data.workspaceId}`));
+        console.log(chalk.dim(`  Project:   ${data.projectId}`));
+        console.log(chalk.dim(`  Config:    ${cfgPath}`));
+      } catch (err) {
+        console.error(
+          chalk.red(
+            `Login failed: ${err instanceof Error ? err.message : err}`
+          )
+        );
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+function createSyncCommand() {
+  const cmd = new Command("sync").description(
+    "Provenant cloud sync operations"
+  );
+  cmd.command("push").description("Push local changes to Provenant cloud").option("--force", "Push all data, ignoring cursors").option("--json", "Output as JSON").action(async (options) => {
+    const projectDir = process.cwd();
+    const config = loadSyncConfig(projectDir);
+    if (!config) {
+      console.error(
+        chalk.yellow(
+          "Cloud sync not configured. Run `stackmemory login` to connect."
+        )
+      );
+      process.exit(1);
+    }
+    const dbPath = getDbPath(projectDir);
+    if (!existsSync(dbPath)) {
+      console.error(chalk.red("No StackMemory database found."));
+      process.exit(1);
+    }
+    const db = new Database(dbPath);
+    const engine = new CloudSyncEngine(db, config);
+    try {
+      const result = await engine.push();
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else if (result.success) {
+        console.log(
+          chalk.green(`Pushed ${result.pushed} entities.`) + (result.conflicts > 0 ? chalk.yellow(` ${result.conflicts} conflicts.`) : "")
+        );
+      } else {
+        console.error(chalk.red(`Push failed: ${result.error}`));
+      }
+    } finally {
+      db.close();
+    }
+  });
+  cmd.command("pull").description("Pull changes from Provenant cloud").option("--tables <tables...>", "Only pull specific tables").option("--json", "Output as JSON").action(async (options) => {
+    const projectDir = process.cwd();
+    const config = loadSyncConfig(projectDir);
+    if (!config) {
+      console.error(
+        chalk.yellow(
+          "Cloud sync not configured. Run `stackmemory login` to connect."
+        )
+      );
+      process.exit(1);
+    }
+    const dbPath = getDbPath(projectDir);
+    if (!existsSync(dbPath)) {
+      console.error(chalk.red("No StackMemory database found."));
+      process.exit(1);
+    }
+    const db = new Database(dbPath);
+    const engine = new CloudSyncEngine(db, config);
+    try {
+      const result = await engine.pull(options.tables);
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else if (result.success) {
+        console.log(
+          chalk.green(
+            `Pulled ${result.pulled} entities, applied ${result.applied}.`
+          ) + (result.conflicts > 0 ? chalk.yellow(` ${result.conflicts} conflicts.`) : "")
+        );
+      } else {
+        console.error(chalk.red(`Pull failed: ${result.error}`));
+      }
+    } finally {
+      db.close();
+    }
+  });
+  cmd.command("status").description("Show cloud sync status").option("--json", "Output as JSON").action(async (options) => {
+    const projectDir = process.cwd();
+    const config = loadSyncConfig(projectDir);
+    if (!config) {
+      if (options.json) {
+        console.log(
+          JSON.stringify({ connected: false, message: "Not configured" })
+        );
+      } else {
+        console.log(
+          chalk.dim("Cloud sync not configured. Run `stackmemory login`.")
+        );
+      }
+      return;
+    }
+    const dbPath = getDbPath(projectDir);
+    if (!existsSync(dbPath)) {
+      console.log(chalk.dim("No StackMemory database found."));
+      return;
+    }
+    const db = new Database(dbPath);
+    const engine = new CloudSyncEngine(db, config);
+    try {
+      const status = engine.status();
+      if (options.json) {
+        console.log(JSON.stringify(status, null, 2));
+      } else {
+        console.log(chalk.bold("Cloud Sync Status"));
+        console.log(
+          `  Connected:  ${status.connected ? chalk.green("yes") : chalk.red("no")}`
+        );
+        console.log(`  Endpoint:   ${status.endpoint ?? "none"}`);
+        console.log(`  Last push:  ${status.lastPushAt ?? "never"}`);
+        console.log(`  Last pull:  ${status.lastPullAt ?? "never"}`);
+        console.log(`  Pending:    ${status.pendingPushCount} items`);
+        console.log(
+          `  Conflicts:  ${status.conflictCount > 0 ? chalk.yellow(String(status.conflictCount)) : "0"}`
+        );
+      }
+    } finally {
+      db.close();
+    }
+  });
+  return cmd;
+}
+export {
+  createLoginCommand,
+  createSyncCommand
+};

package/dist/src/cli/commands/tasks.js

@@ -5,10 +5,20 @@ const __dirname = __pathDirname(__filename);
 import { Command } from "commander";
 import Database from "better-sqlite3";
 import { join } from "path";
-import { existsSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
 import {
   LinearTaskManager
 } from "../../features/tasks/linear-task-manager.js";
+import {
+  parseMasterTasks,
+  getNextTask,
+  addTaskToFile,
+  updateTaskInFile
+} from "../../core/tasks/md-task-parser.js";
+import {
+  MASTER_TASKS_TEMPLATE,
+  TASKS_CONFIG_TEMPLATE
+} from "../../core/tasks/master-tasks-template.js";
 function getTaskStore(projectRoot) {
   const dbPath = join(projectRoot, ".stackmemory", "context.db");
   if (!existsSync(dbPath)) {
@@ -191,8 +201,127 @@ Tags: ${tags.join(", ")}`);
       console.error("\u274C Failed to show task:", error.message);
     }
   });
+  tasks.command("init").description("Scaffold .stackmemory/tasks/master-tasks.md").action(() => {
+    const projectRoot = process.cwd();
+    const tasksDir = join(projectRoot, ".stackmemory", "tasks");
+    const mdPath = join(tasksDir, "master-tasks.md");
+    const configPath = join(tasksDir, "config.json");
+    if (existsSync(mdPath)) {
+      console.log(`Already exists: ${mdPath}`);
+      return;
+    }
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(mdPath, MASTER_TASKS_TEMPLATE, "utf-8");
+    writeFileSync(
+      configPath,
+      JSON.stringify(TASKS_CONFIG_TEMPLATE, null, 2),
+      "utf-8"
+    );
+    console.log(`Created: ${mdPath}`);
+    console.log(`Created: ${configPath}`);
+  });
+  const md = new Command("md").description(
+    "Local-first task management via master-tasks.md"
+  );
+  md.command("list").alias("ls").description("List tasks from master-tasks.md").option("-p, --priority <P>", "Filter by priority (P0, P1, P2, P3)").option(
+    "-s, --status <status>",
+    "Filter by status (todo, active, done, blocked, cut)"
+  ).option("-o, --owner <owner>", "Filter by owner (@me, @agent, @defer)").option("--json", "Output as JSON").action((options) => {
+    const mdPath = resolveMdPath();
+    if (!mdPath) return;
+    let tasks2 = parseMasterTasks(readFileSync(mdPath, "utf-8"));
+    if (options.priority)
+      tasks2 = tasks2.filter((t) => t.priority === options.priority);
+    if (options.status)
+      tasks2 = tasks2.filter((t) => t.status === options.status);
+    if (options.owner) tasks2 = tasks2.filter((t) => t.owner === options.owner);
+    if (options.json) {
+      console.log(JSON.stringify(tasks2, null, 2));
+      return;
+    }
+    if (tasks2.length === 0) {
+      console.log("No tasks found");
+      return;
+    }
+    console.log(`
+Tasks (${tasks2.length})
+`);
+    for (const t of tasks2) {
+      const pColor = t.priority === "P0" ? "\x1B[31m" : t.priority === "P1" ? "\x1B[33m" : "\x1B[90m";
+      const sIcon = t.status === "done" ? "[x]" : t.status === "active" ? "[>]" : t.status === "blocked" ? "[!]" : "[ ]";
+      console.log(
+        `${sIcon} ${pColor}${t.priority}\x1B[0m ${t.id} ${t.task} ${t.owner} ${t.branchPr ? `(${t.branchPr})` : ""}`
+      );
+    }
+    console.log("");
+  });
+  md.command("next").description("Show the next task to work on").option("--json", "Output as JSON").action((options) => {
+    const mdPath = resolveMdPath();
+    if (!mdPath) return;
+    const tasks2 = parseMasterTasks(readFileSync(mdPath, "utf-8"));
+    const next = getNextTask(tasks2);
+    if (!next) {
+      console.log("No actionable tasks");
+      return;
+    }
+    if (options.json) {
+      console.log(JSON.stringify(next));
+      return;
+    }
+    console.log(`
+Next: ${next.id} [${next.priority}] ${next.task}`);
+    console.log(`  Owner: ${next.owner} | Sync: ${next.sync}`);
+    if (next.notes) console.log(`  Notes: ${next.notes}`);
+    console.log("");
+  });
+  md.command("add <description>").description("Add a task to master-tasks.md").option("-p, --priority <P>", "Priority (P0-P3)", "P1").option("-o, --owner <owner>", "Owner (@me, @agent, @defer)", "@me").option("-s, --sync <sync>", "Sync target (local, linear, gh)", "local").option("-b, --branch <branch>", "Branch or PR").option("-n, --notes <notes>", "Notes").action((description, options) => {
+    const mdPath = resolveMdPath();
+    if (!mdPath) return;
+    const id = addTaskToFile(mdPath, {
+      priority: options.priority,
+      status: "todo",
+      owner: options.owner,
+      sync: options.sync,
+      task: description,
+      branchPr: options.branch || "",
+      notes: options.notes || ""
+    });
+    console.log(`Added: ${id} ${description}`);
+  });
+  md.command("update <taskId>").description("Update a task in master-tasks.md").option(
+    "-s, --status <status>",
+    "New status (todo, active, done, blocked, cut)"
+  ).option("-p, --priority <P>", "New priority (P0-P3)").option("-o, --owner <owner>", "New owner").option("-b, --branch <branch>", "Branch or PR").option("-n, --notes <notes>", "Notes").option("--sync <sync>", "Sync target (local, linear, gh)").action((taskId, options) => {
+    const mdPath = resolveMdPath();
+    if (!mdPath) return;
+    try {
+      const updates = {};
+      if (options.status) updates.status = options.status;
+      if (options.priority) updates.priority = options.priority;
+      if (options.owner) updates.owner = options.owner;
+      if (options.branch) updates.branchPr = options.branch;
+      if (options.notes) updates.notes = options.notes;
+      if (options.sync) updates.sync = options.sync;
+      updateTaskInFile(mdPath, taskId.toUpperCase(), updates);
+      console.log(`Updated: ${taskId.toUpperCase()}`);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+    }
+  });
+  tasks.addCommand(md);
   return tasks;
 }
+function resolveMdPath() {
+  const projectRoot = process.cwd();
+  const smPath = join(projectRoot, ".stackmemory", "tasks", "master-tasks.md");
+  if (existsSync(smPath)) return smPath;
+  const rootPath = join(projectRoot, "master-tasks.md");
+  if (existsSync(rootPath)) return rootPath;
+  console.error(
+    'No master-tasks.md found. Run "stackmemory tasks init" first.'
+  );
+  return null;
+}
 function findTaskByPartialId(projectRoot, partialId) {
   const dbPath = join(projectRoot, ".stackmemory", "context.db");
   if (!existsSync(dbPath)) return null;