trekoon 0.1.1 → 0.1.4

package/src/commands/skills.ts

@@ -0,0 +1,265 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { hasFlag, parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+
+const SKILLS_USAGE = "Usage: trekoon skills install [--link --editor opencode|claude] [--to <path>]";
+const EDITOR_NAMES = ["opencode", "claude"] as const;
+
+type EditorName = (typeof EDITOR_NAMES)[number];
+
+interface InstallOutcome {
+  readonly sourcePath: string;
+  readonly installedPath: string;
+  readonly installedDir: string;
+  readonly linkPath: string | null;
+  readonly linkTarget: string | null;
+}
+
+function invalidArgs(message: string): CliResult {
+  return failResult({
+    command: "skills",
+    human: `${message}\n${SKILLS_USAGE}`,
+    data: { message },
+    error: {
+      code: "invalid_args",
+      message,
+    },
+  });
+}
+
+function invalidInput(command: string, message: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human: message,
+    data: {
+      code: "invalid_input",
+      ...data,
+    },
+    error: {
+      code: "invalid_input",
+      message,
+    },
+  });
+}
+
+function resolveBundledSkillFilePath(): string {
+  return fileURLToPath(new URL("../../.agents/skills/trekoon/SKILL.md", import.meta.url));
+}
+
+function toAbsolutePath(cwd: string, pathValue: string): string {
+  if (isAbsolute(pathValue)) {
+    return pathValue;
+  }
+
+  return resolve(cwd, pathValue);
+}
+
+function resolveLinkRoot(cwd: string, editor: EditorName, toOverride: string | undefined): string {
+  if (toOverride !== undefined) {
+    return toAbsolutePath(cwd, toOverride);
+  }
+
+  if (editor === "opencode") {
+    return join(cwd, ".opencode", "skills");
+  }
+
+  return join(cwd, ".claude", "skills");
+}
+
+function replaceOrCreateSymlink(linkPath: string, targetPath: string): CliResult | null {
+  if (!existsSync(linkPath)) {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    symlinkSync(targetPath, linkPath, "dir");
+    return null;
+  }
+
+  const existing = lstatSync(linkPath);
+  if (!existing.isSymbolicLink()) {
+    return failResult({
+      command: "skills.install",
+      human: `Cannot create symlink: path exists and is not a link (${linkPath}).`,
+      data: {
+        code: "path_conflict",
+        linkPath,
+        targetPath,
+      },
+      error: {
+        code: "path_conflict",
+        message: "Symlink destination exists as a non-link path",
+      },
+    });
+  }
+
+  const existingRawTarget: string = readlinkSync(linkPath);
+  const existingAbsoluteTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
+  const expectedTarget: string = resolve(targetPath);
+  if (existingAbsoluteTarget !== expectedTarget) {
+    return failResult({
+      command: "skills.install",
+      human: `Cannot replace existing link at ${linkPath}; it points to ${existingAbsoluteTarget}.`,
+      data: {
+        code: "path_conflict",
+        linkPath,
+        existingTarget: existingAbsoluteTarget,
+        expectedTarget,
+      },
+      error: {
+        code: "path_conflict",
+        message: "Symlink destination points to a different target",
+      },
+    });
+  }
+
+  rmSync(linkPath, { force: true });
+  symlinkSync(targetPath, linkPath, "dir");
+  return null;
+}
+
+function runSkillsInstall(context: CliContext): CliResult {
+  const parsed = parseArgs(context.args);
+  const missingValue = readMissingOptionValue(parsed.missingOptionValues, "editor", "to");
+  if (missingValue !== undefined) {
+    return invalidInput("skills.install", `Option --${missingValue} requires a value.`, {
+      option: missingValue,
+    });
+  }
+
+  if (parsed.positional.length > 1) {
+    return invalidArgs("Unexpected positional arguments for skills install.");
+  }
+
+  const wantsLink: boolean = hasFlag(parsed.flags, "link");
+  const rawEditor: string | undefined = readOption(parsed.options, "editor");
+  const rawTo: string | undefined = readOption(parsed.options, "to");
+
+  if (!wantsLink && rawEditor !== undefined) {
+    return invalidInput("skills.install", "--editor requires --link.", {
+      editor: rawEditor,
+    });
+  }
+
+  if (!wantsLink && rawTo !== undefined) {
+    return invalidInput("skills.install", "--to requires --link.", {
+      to: rawTo,
+    });
+  }
+
+  if (wantsLink && rawEditor === undefined) {
+    return invalidArgs("skills install --link requires --editor opencode|claude.");
+  }
+
+  if (rawEditor !== undefined && !EDITOR_NAMES.includes(rawEditor as EditorName)) {
+    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude", {
+      editor: rawEditor,
+      allowedEditors: EDITOR_NAMES,
+    });
+  }
+
+  const editor: EditorName | undefined = rawEditor as EditorName | undefined;
+
+  const sourcePath: string = resolveBundledSkillFilePath();
+  if (!existsSync(sourcePath)) {
+    return failResult({
+      command: "skills.install",
+      human: `Bundled skill asset not found at ${sourcePath}`,
+      data: {
+        code: "missing_asset",
+        sourcePath,
+      },
+      error: {
+        code: "missing_asset",
+        message: "Bundled skill asset not found",
+      },
+    });
+  }
+
+  const installPath = join(context.cwd, ".agents", "skills", "trekoon", "SKILL.md");
+  const installDir = dirname(installPath);
+
+  let outcome: InstallOutcome;
+
+  try {
+    mkdirSync(installDir, { recursive: true });
+    copyFileSync(sourcePath, installPath);
+
+    let linkPath: string | null = null;
+    let linkTarget: string | null = null;
+
+    if (wantsLink && editor !== undefined) {
+      const linkRoot: string = resolveLinkRoot(context.cwd, editor, rawTo);
+      linkPath = join(linkRoot, "trekoon");
+      linkTarget = installDir;
+      const linkFailure = replaceOrCreateSymlink(linkPath, linkTarget);
+      if (linkFailure) {
+        return linkFailure;
+      }
+    }
+
+    outcome = {
+      sourcePath,
+      installedPath: installPath,
+      installedDir: installDir,
+      linkPath,
+      linkTarget,
+    };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown skills install failure";
+    return failResult({
+      command: "skills.install",
+      human: `Failed to install skill: ${message}`,
+      data: {
+        code: "install_failed",
+        message,
+      },
+      error: {
+        code: "install_failed",
+        message,
+      },
+    });
+  }
+
+  return okResult({
+    command: "skills.install",
+    human: outcome.linkPath
+      ? [
+          "Installed Trekoon skill and linked editor path.",
+          `Source: ${outcome.sourcePath}`,
+          `Installed file: ${outcome.installedPath}`,
+          `Link path: ${outcome.linkPath}`,
+          `Link target: ${outcome.linkTarget}`,
+        ].join("\n")
+      : [
+          "Installed Trekoon skill.",
+          `Source: ${outcome.sourcePath}`,
+          `Installed file: ${outcome.installedPath}`,
+        ].join("\n"),
+    data: {
+      sourcePath: outcome.sourcePath,
+      installedPath: outcome.installedPath,
+      installedDir: outcome.installedDir,
+      linked: outcome.linkPath !== null,
+      linkPath: outcome.linkPath,
+      linkTarget: outcome.linkTarget,
+    },
+  });
+}
+
+export async function runSkills(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+  if (!subcommand) {
+    return invalidArgs("Missing skills subcommand.");
+  }
+
+  switch (subcommand) {
+    case "install":
+      return runSkillsInstall(context);
+    default:
+      return invalidArgs(`Unknown skills subcommand '${subcommand}'.`);
+  }
+}

package/src/commands/subtask.ts

@@ -1,4 +1,4 @@
-import { parseArgs, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
+import { hasFlag, parseArgs, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
 
 import { DomainError, type SubtaskRecord } from "../domain/types";
 import { TrackerDomain } from "../domain/tracker-domain";
@@ -13,6 +13,21 @@ function formatSubtask(subtask: SubtaskRecord): string {
 
 const VIEW_MODES = ["table", "compact"] as const;
 
+function parseIdsOption(rawIds: string | undefined): string[] {
+  if (rawIds === undefined) {
+    return [];
+  }
+
+  return rawIds
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+}
+
+function appendLine(existing: string, line: string): string {
+  return existing.length > 0 ? `${existing}\n${line}` : line;
+}
+
 function formatSubtaskListTable(subtasks: readonly SubtaskRecord[]): string {
   return formatHumanTable(
     ["ID", "TASK", "TITLE", "STATUS"],
@@ -138,6 +153,8 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
       }
       case "update": {
         const missingUpdateOption =
+          readMissingOptionValue(parsed.missingOptionValues, "ids") ??
+          readMissingOptionValue(parsed.missingOptionValues, "append") ??
           readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s");
         if (missingUpdateOption !== undefined) {
@@ -145,10 +162,112 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         }
 
         const subtaskId: string = parsed.positional[1] ?? "";
+        const updateAll: boolean = hasFlag(parsed.flags, "all");
+        const rawIds: string | undefined = readOption(parsed.options, "ids");
+        const ids = parseIdsOption(rawIds);
         const title: string | undefined = readOption(parsed.options, "title");
         const description: string | undefined = readOption(parsed.options, "description", "d");
+        const append: string | undefined = readOption(parsed.options, "append");
         const status: string | undefined = readOption(parsed.options, "status", "s");
-        const subtask = domain.updateSubtask(subtaskId, { title, description, status });
+
+        if (updateAll && ids.length > 0) {
+          return failResult({
+            command: "subtask.update",
+            human: "Use either --all or --ids, not both.",
+            data: { code: "invalid_input", target: ["all", "ids"] },
+            error: {
+              code: "invalid_input",
+              message: "--all and --ids are mutually exclusive",
+            },
+          });
+        }
+
+        if (append !== undefined && description !== undefined) {
+          return failResult({
+            command: "subtask.update",
+            human: "Use either --append or --description, not both.",
+            data: { code: "invalid_input", fields: ["append", "description"] },
+            error: {
+              code: "invalid_input",
+              message: "--append and --description are mutually exclusive",
+            },
+          });
+        }
+
+        const hasBulkTarget = updateAll || ids.length > 0;
+        if (hasBulkTarget) {
+          if (subtaskId.length > 0) {
+            return failResult({
+              command: "subtask.update",
+              human: "Do not pass a subtask id when using --all or --ids.",
+              data: { code: "invalid_input", id: subtaskId },
+              error: {
+                code: "invalid_input",
+                message: "Positional id is not allowed with --all/--ids",
+              },
+            });
+          }
+
+          if (title !== undefined || description !== undefined) {
+            return failResult({
+              command: "subtask.update",
+              human: "Bulk update supports only --append and/or --status.",
+              data: { code: "invalid_input" },
+              error: {
+                code: "invalid_input",
+                message: "Bulk update supports only --append and --status",
+              },
+            });
+          }
+
+          if (append === undefined && status === undefined) {
+            return failResult({
+              command: "subtask.update",
+              human: "Bulk update requires --append and/or --status.",
+              data: { code: "invalid_input" },
+              error: {
+                code: "invalid_input",
+                message: "Missing bulk update fields",
+              },
+            });
+          }
+
+          const targets = updateAll ? [...domain.listSubtasks()] : ids.map((id) => domain.getSubtaskOrThrow(id));
+          const subtasks = targets.map((target) =>
+            domain.updateSubtask(target.id, {
+              status,
+              description: append === undefined ? undefined : appendLine(target.description, append),
+            }),
+          );
+
+          return okResult({
+            command: "subtask.update",
+            human: `Updated ${subtasks.length} subtask(s)`,
+            data: {
+              subtasks,
+              target: updateAll ? "all" : "ids",
+              ids: subtasks.map((subtask) => subtask.id),
+            },
+          });
+        }
+
+        if (subtaskId.length === 0) {
+          return failResult({
+            command: "subtask.update",
+            human: "Provide a subtask id, or use --all/--ids for bulk update.",
+            data: { code: "invalid_input" },
+            error: {
+              code: "invalid_input",
+              message: "Missing subtask id",
+            },
+          });
+        }
+
+        const nextDescription =
+          append === undefined
+            ? description
+            : appendLine(domain.getSubtaskOrThrow(subtaskId).description, append);
+        const subtask = domain.updateSubtask(subtaskId, { title, description: nextDescription, status });
 
         return okResult({
           command: "subtask.update",

package/src/domain/tracker-domain.ts

@@ -522,44 +522,25 @@ export class TrackerDomain {
   }
 
   private wouldCreateCycle(sourceId: string, dependsOnId: string): boolean {
-    const adjacency = new Map<string, string[]>();
-    const rows = this.#db.query("SELECT source_id, depends_on_id FROM dependencies;").all() as Array<{
-      source_id: string;
-      depends_on_id: string;
-    }>;
-
-    for (const row of rows) {
-      const existing = adjacency.get(row.source_id) ?? [];
-      existing.push(row.depends_on_id);
-      adjacency.set(row.source_id, existing);
-    }
-
-    const newEdges = adjacency.get(sourceId) ?? [];
-    newEdges.push(dependsOnId);
-    adjacency.set(sourceId, newEdges);
-
-    const visited = new Set<string>();
-    const queue: string[] = [dependsOnId];
-
-    while (queue.length > 0) {
-      const next = queue.shift();
-      if (!next) {
-        continue;
-      }
-      if (next === sourceId) {
-        return true;
-      }
-      if (visited.has(next)) {
-        continue;
-      }
-      visited.add(next);
-      const outgoing = adjacency.get(next) ?? [];
-      for (const neighbor of outgoing) {
-        queue.push(neighbor);
-      }
-    }
+    const row = this.#db
+      .query(
+        `
+        WITH RECURSIVE reachable(id) AS (
+          SELECT ?
+          UNION
+          SELECT d.depends_on_id
+          FROM dependencies d
+          INNER JOIN reachable r ON d.source_id = r.id
+        )
+        SELECT 1 AS has_cycle
+        FROM reachable
+        WHERE id = ?
+        LIMIT 1;
+        `,
+      )
+      .get(dependsOnId, sourceId) as { has_cycle: number } | null;
 
-    return false;
+    return row !== null;
   }
 }
 

package/src/runtime/cli-shell.ts

@@ -1,8 +1,11 @@
 import { runHelp } from "../commands/help";
 import { runDep } from "../commands/dep";
 import { runEpic } from "../commands/epic";
+import { runEvents } from "../commands/events";
 import { runInit } from "../commands/init";
+import { runMigrate } from "../commands/migrate";
 import { runQuickstart } from "../commands/quickstart";
+import { runSkills } from "../commands/skills";
 import { runSubtask } from "../commands/subtask";
 import { runSync } from "../commands/sync";
 import { runTask } from "../commands/task";
@@ -13,13 +16,17 @@ import { type CliContext, type CliResult, type OutputMode } from "./command-type
 const CLI_VERSION = "0.1.0";
 
 const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
+  "help",
   "init",
   "quickstart",
   "epic",
   "task",
   "subtask",
   "dep",
+  "events",
+  "migrate",
   "sync",
+  "skills",
   "wipe",
 ];
 
@@ -128,6 +135,8 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
   };
 
   switch (parsed.command) {
+    case "help":
+      return runHelp(context);
     case "init":
       return runInit(context);
     case "quickstart":
@@ -142,8 +151,14 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
       return runSubtask(context);
     case "dep":
       return runDep(context);
+    case "events":
+      return runEvents(context);
+    case "migrate":
+      return runMigrate(context);
     case "sync":
       return runSync(context);
+    case "skills":
+      return runSkills(context);
     default:
       return failResult({
         command: "shell",

package/src/storage/database.ts

@@ -11,7 +11,14 @@ export interface TrekoonDatabase {
   close(): void;
 }
 
-export function openTrekoonDatabase(workingDirectory: string = process.cwd()): TrekoonDatabase {
+export interface OpenTrekoonDatabaseOptions {
+  readonly autoMigrate?: boolean;
+}
+
+export function openTrekoonDatabase(
+  workingDirectory: string = process.cwd(),
+  options: OpenTrekoonDatabaseOptions = {},
+): TrekoonDatabase {
   const paths: StoragePaths = resolveStoragePaths(workingDirectory);
 
   mkdirSync(paths.storageDir, { recursive: true });
@@ -22,7 +29,9 @@ export function openTrekoonDatabase(workingDirectory: string = process.cwd()): T
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec("PRAGMA foreign_keys = ON;");
 
-  migrateDatabase(db);
+  if (options.autoMigrate ?? true) {
+    migrateDatabase(db);
+  }
 
   return {
     db,

package/src/storage/events-retention.ts

@@ -0,0 +1,138 @@
+import { type Database } from "bun:sqlite";
+
+export const DEFAULT_EVENT_RETENTION_DAYS = 90;
+const DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;
+
+export interface EventPruneOptions {
+  readonly retentionDays?: number;
+  readonly dryRun?: boolean;
+  readonly archive?: boolean;
+  readonly now?: number;
+}
+
+export interface EventPruneSummary {
+  readonly retentionDays: number;
+  readonly cutoffTimestamp: number;
+  readonly dryRun: boolean;
+  readonly archive: boolean;
+  readonly candidateCount: number;
+  readonly archivedCount: number;
+  readonly deletedCount: number;
+}
+
+function ensureArchiveTable(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS event_archive (
+      id TEXT PRIMARY KEY,
+      entity_kind TEXT NOT NULL,
+      entity_id TEXT NOT NULL,
+      operation TEXT NOT NULL,
+      payload TEXT NOT NULL,
+      git_branch TEXT,
+      git_head TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      version INTEGER NOT NULL DEFAULT 1
+    );
+  `);
+}
+
+function assertRetentionDays(value: number): number {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error("retentionDays must be a positive integer.");
+  }
+
+  return value;
+}
+
+function countCandidates(db: Database, cutoffTimestamp: number): number {
+  const row = db.query("SELECT COUNT(*) AS count FROM events WHERE created_at < ?;").get(cutoffTimestamp) as
+    | { count: number }
+    | null;
+
+  return row?.count ?? 0;
+}
+
+export function pruneEvents(db: Database, options: EventPruneOptions = {}): EventPruneSummary {
+  const retentionDays: number = assertRetentionDays(options.retentionDays ?? DEFAULT_EVENT_RETENTION_DAYS);
+  const dryRun: boolean = options.dryRun ?? false;
+  const archive: boolean = options.archive ?? false;
+  const now: number = options.now ?? Date.now();
+  const cutoffTimestamp: number = now - retentionDays * DAY_IN_MILLISECONDS;
+  const candidateCount: number = countCandidates(db, cutoffTimestamp);
+
+  if (dryRun || candidateCount === 0) {
+    return {
+      retentionDays,
+      cutoffTimestamp,
+      dryRun,
+      archive,
+      candidateCount,
+      archivedCount: 0,
+      deletedCount: 0,
+    };
+  }
+
+  return db.transaction((): EventPruneSummary => {
+    let archivedCount = 0;
+
+    if (archive) {
+      ensureArchiveTable(db);
+      const archived = db
+        .query(
+          `
+          INSERT INTO event_archive (
+            id,
+            entity_kind,
+            entity_id,
+            operation,
+            payload,
+            git_branch,
+            git_head,
+            created_at,
+            updated_at,
+            version
+          )
+          SELECT
+            id,
+            entity_kind,
+            entity_id,
+            operation,
+            payload,
+            git_branch,
+            git_head,
+            created_at,
+            updated_at,
+            version
+          FROM events
+          WHERE created_at < ?
+          ON CONFLICT(id) DO UPDATE SET
+            entity_kind = excluded.entity_kind,
+            entity_id = excluded.entity_id,
+            operation = excluded.operation,
+            payload = excluded.payload,
+            git_branch = excluded.git_branch,
+            git_head = excluded.git_head,
+            created_at = excluded.created_at,
+            updated_at = excluded.updated_at,
+            version = excluded.version;
+          `,
+        )
+        .run(cutoffTimestamp);
+
+      archivedCount = archived.changes;
+    }
+
+    const deleted = db.query("DELETE FROM events WHERE created_at < ?;").run(cutoffTimestamp);
+
+    return {
+      retentionDays,
+      cutoffTimestamp,
+      dryRun,
+      archive,
+      candidateCount,
+      archivedCount,
+      deletedCount: deleted.changes,
+    };
+  })();
+}