trekoon 0.1.6 → 0.1.7

package/README.md

@@ -52,7 +52,7 @@ npm i -g trekoon
 - `trekoon subtask <create|list|update|delete>`
 - `trekoon dep <add|remove|list>`
 - `trekoon sync <status|pull|resolve>`
-- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>]`
+- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]`
 - `trekoon skills update`
 - `trekoon wipe --yes`
 
@@ -161,6 +161,15 @@ trekoon sync pull --from main
 trekoon sync resolve <conflict-id> --use ours
 ```
 
+`sync pull` machine output includes diagnostics counters and hints so agents can
+react deterministically:
+
+- `diagnostics.malformedPayloadEvents`
+- `diagnostics.applyRejectedEvents`
+- `diagnostics.quarantinedEvents`
+- `diagnostics.conflictEvents`
+- `diagnostics.errorHints`
+
 ### 6) Install project-local Trekoon skill for agents
 
 `trekoon skills install` always writes the bundled skill file into the current
@@ -186,6 +195,10 @@ Path behavior:
 - Default pi link path: `.pi/skills/trekoon`
 - `--to <path>` overrides the editor root for link creation only.
 - `--to` does **not** move or copy `SKILL.md` to that path.
+- By default, link targets must resolve inside the repository root.
+- Use `--allow-outside-repo` only for intentional external links.
+- When override is used, install prints a warning and includes confirmation
+  fields in machine output.
 - Re-running install is idempotent: it refreshes `SKILL.md` and reuses/replaces
   the same symlink target.
 - `trekoon skills update` is idempotent: it refreshes canonical

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",

package/src/commands/help.ts

@@ -42,7 +42,7 @@ const COMMAND_HELP: Record<string, string> = {
   migrate: "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
   sync: "Usage: trekoon sync <subcommand> [options]",
   skills:
-    "Usage: trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] | trekoon skills update (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md; update refreshes canonical SKILL and reports default link states)",
+    "Usage: trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo] | trekoon skills update (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md; links must resolve inside repo unless --allow-outside-repo is set; update refreshes canonical SKILL and reports default link states)",
   help: "Usage: trekoon help [command] [--json|--toon]",
 };
 

package/src/commands/skills.ts

@@ -1,5 +1,5 @@
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { hasFlag, parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
@@ -9,10 +9,11 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 
 const SKILLS_USAGE = [
   "Usage:",
-  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>]",
+  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
   "  trekoon skills update",
 ].join("\n");
 const EDITOR_NAMES = ["opencode", "claude", "pi"] as const;
+const ALLOW_OUTSIDE_REPO_FLAG = "allow-outside-repo";
 
 type EditorName = (typeof EDITOR_NAMES)[number];
 type LinkStateStatus = "missing" | "valid" | "conflict";
@@ -23,6 +24,12 @@ interface InstallOutcome {
   readonly installedDir: string;
   readonly linkPath: string | null;
   readonly linkTarget: string | null;
+  readonly outsideRepoLink: boolean;
+}
+
+interface LinkTargetValidation {
+  readonly linkRoot: string;
+  readonly outsideRepoLink: boolean;
 }
 
 interface LinkState {
@@ -96,6 +103,114 @@ function resolveLinkRoot(cwd: string, editor: EditorName, toOverride: string | u
   return join(cwd, ".pi", "skills");
 }
 
+function isPathInsideRoot(pathValue: string, rootPath: string): boolean {
+  const normalizedPath: string = resolve(pathValue);
+  const normalizedRoot: string = resolve(rootPath);
+  const relativePath: string = relative(normalizedRoot, normalizedPath);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function realpathNearestExistingAncestor(pathValue: string): string {
+  let cursor: string = resolve(pathValue);
+
+  while (!existsSync(cursor)) {
+    const parent: string = dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+
+    cursor = parent;
+  }
+
+  return realpathSync(cursor);
+}
+
+function validateLinkRoot(
+  cwd: string,
+  editor: EditorName,
+  toOverride: string | undefined,
+  allowOutsideRepo: boolean,
+): CliResult | LinkTargetValidation {
+  const linkRoot: string = resolveLinkRoot(cwd, editor, toOverride);
+  const repoRoot: string = realpathSync(cwd);
+  const effectiveTargetRoot: string = realpathNearestExistingAncestor(linkRoot);
+  const insideRepo: boolean = isPathInsideRoot(effectiveTargetRoot, repoRoot);
+
+  if (insideRepo) {
+    return {
+      linkRoot,
+      outsideRepoLink: false,
+    };
+  }
+
+  if (!allowOutsideRepo) {
+    return failResult({
+      command: "skills.install",
+      human: [
+        "Refusing to link skills outside repository root by default.",
+        `Requested link root: ${linkRoot}`,
+        `Resolved existing target ancestor: ${effectiveTargetRoot}`,
+        `Repository root: ${repoRoot}`,
+        `If intentional, re-run with --${ALLOW_OUTSIDE_REPO_FLAG} to override.`,
+      ].join("\n"),
+      data: {
+        code: "outside_repo_target",
+        linkRoot,
+        effectiveTargetRoot,
+        repoRoot,
+        overrideFlag: `--${ALLOW_OUTSIDE_REPO_FLAG}`,
+      },
+      error: {
+        code: "outside_repo_target",
+        message: "Link target is outside repository root",
+      },
+    });
+  }
+
+  return {
+    linkRoot,
+    outsideRepoLink: true,
+  };
+}
+
+function revalidateLinkParentBoundary(
+  repoRoot: string,
+  linkPath: string,
+  allowOutsideRepo: boolean,
+): CliResult | null {
+  if (allowOutsideRepo) {
+    return null;
+  }
+
+  const linkParentRealpath: string = realpathSync(dirname(linkPath));
+  const insideRepo: boolean = isPathInsideRoot(linkParentRealpath, repoRoot);
+  if (insideRepo) {
+    return null;
+  }
+
+  return failResult({
+    command: "skills.install",
+    human: [
+      "Refusing to link skills outside repository root by default.",
+      `Requested link root: ${dirname(linkPath)}`,
+      `Resolved existing target ancestor: ${linkParentRealpath}`,
+      `Repository root: ${repoRoot}`,
+      `If intentional, re-run with --${ALLOW_OUTSIDE_REPO_FLAG} to override.`,
+    ].join("\n"),
+    data: {
+      code: "outside_repo_target",
+      linkRoot: dirname(linkPath),
+      effectiveTargetRoot: linkParentRealpath,
+      repoRoot,
+      overrideFlag: `--${ALLOW_OUTSIDE_REPO_FLAG}`,
+    },
+    error: {
+      code: "outside_repo_target",
+      message: "Link target is outside repository root",
+    },
+  });
+}
+
 function resolveDefaultLinkPath(cwd: string, editor: EditorName): string {
   return join(resolveLinkRoot(cwd, editor, undefined), "trekoon");
 }
@@ -146,9 +261,18 @@ function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; i
   };
 }
 
-function replaceOrCreateSymlink(linkPath: string, targetPath: string): CliResult | null {
+function replaceOrCreateSymlink(
+  linkPath: string,
+  targetPath: string,
+  repoRoot: string,
+  allowOutsideRepo: boolean,
+): CliResult | null {
   if (!existsSync(linkPath)) {
     mkdirSync(dirname(linkPath), { recursive: true });
+    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+    if (boundaryFailure) {
+      return boundaryFailure;
+    }
     symlinkSync(targetPath, linkPath, "dir");
     return null;
   }
@@ -191,6 +315,10 @@ function replaceOrCreateSymlink(linkPath: string, targetPath: string): CliResult
   }
 
   rmSync(linkPath, { force: true });
+  const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+  if (boundaryFailure) {
+    return boundaryFailure;
+  }
   symlinkSync(targetPath, linkPath, "dir");
   return null;
 }
@@ -259,9 +387,16 @@ function runSkillsInstall(context: CliContext): CliResult {
   }
 
   const wantsLink: boolean = hasFlag(parsed.flags, "link");
+  const allowOutsideRepo: boolean = hasFlag(parsed.flags, ALLOW_OUTSIDE_REPO_FLAG);
   const rawEditor: string | undefined = readOption(parsed.options, "editor");
   const rawTo: string | undefined = readOption(parsed.options, "to");
 
+  if (allowOutsideRepo && !wantsLink) {
+    return invalidInput("skills.install", `--${ALLOW_OUTSIDE_REPO_FLAG} requires --link.`, {
+      allowOutsideRepo,
+    });
+  }
+
   if (!wantsLink && rawEditor !== undefined) {
     return invalidInput("skills.install", "--editor requires --link.", {
       editor: rawEditor,
@@ -299,22 +434,42 @@ function runSkillsInstall(context: CliContext): CliResult {
     let linkTarget: string | null = null;
 
     if (wantsLink && editor !== undefined) {
-      const linkRoot: string = resolveLinkRoot(context.cwd, editor, rawTo);
+      const validation = validateLinkRoot(context.cwd, editor, rawTo, allowOutsideRepo);
+      if ("ok" in validation) {
+        return validation;
+      }
+
+      const linkRoot: string = validation.linkRoot;
       linkPath = join(linkRoot, "trekoon");
       linkTarget = installResult.installedDir;
-      const linkFailure = replaceOrCreateSymlink(linkPath, linkTarget);
+      const linkFailure = replaceOrCreateSymlink(
+        linkPath,
+        linkTarget,
+        realpathSync(context.cwd),
+        allowOutsideRepo,
+      );
       if (linkFailure) {
         return linkFailure;
       }
-    }
 
-    outcome = {
-      sourcePath: installResult.sourcePath,
-      installedPath: installResult.installedPath,
-      installedDir: installResult.installedDir,
-      linkPath,
-      linkTarget,
-    };
+      outcome = {
+        sourcePath: installResult.sourcePath,
+        installedPath: installResult.installedPath,
+        installedDir: installResult.installedDir,
+        linkPath,
+        linkTarget,
+        outsideRepoLink: validation.outsideRepoLink,
+      };
+    } else {
+      outcome = {
+        sourcePath: installResult.sourcePath,
+        installedPath: installResult.installedPath,
+        installedDir: installResult.installedDir,
+        linkPath,
+        linkTarget,
+        outsideRepoLink: false,
+      };
+    }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Unknown skills install failure";
     return failResult({
@@ -335,6 +490,11 @@ function runSkillsInstall(context: CliContext): CliResult {
     command: "skills.install",
     human: outcome.linkPath
       ? [
+          ...(outcome.outsideRepoLink
+            ? [
+                `WARNING: Linking outside repository root because --${ALLOW_OUTSIDE_REPO_FLAG} was provided.`,
+              ]
+            : []),
           "Installed Trekoon skill and linked editor path.",
           `Source: ${outcome.sourcePath}`,
           `Installed file: ${outcome.installedPath}`,
@@ -353,6 +513,9 @@ function runSkillsInstall(context: CliContext): CliResult {
       linked: outcome.linkPath !== null,
       linkPath: outcome.linkPath,
       linkTarget: outcome.linkTarget,
+      outsideRepoLink: outcome.outsideRepoLink,
+      outsideRepoOverrideUsed: outcome.outsideRepoLink,
+      outsideRepoOverrideFlag: outcome.outsideRepoLink ? `--${ALLOW_OUTSIDE_REPO_FLAG}` : null,
     },
   });
 }

package/src/commands/sync.ts

@@ -113,6 +113,10 @@ export async function runSync(context: CliContext): Promise<CliResult> {
           `Scanned events: ${summary.scannedEvents}`,
           `Applied events: ${summary.appliedEvents}`,
           `Created conflicts: ${summary.createdConflicts}`,
+          `Malformed payloads: ${summary.diagnostics.malformedPayloadEvents}`,
+          `Quarantined events: ${summary.diagnostics.quarantinedEvents}`,
+          `Conflict events: ${summary.diagnostics.conflictEvents}`,
+          ...summary.diagnostics.errorHints,
         ].join("\n"),
         data: summary,
       });

package/src/storage/migrations.ts

@@ -278,11 +278,58 @@ function recordMigration(db: Database, migration: Migration): void {
   );
 }
 
+function isSchemaCurrentFastPath(db: Database, latestVersion: number): boolean {
+  if (latestVersion === 0 || !migrationTableExists(db) || !hasMigrationVersionColumn(db)) {
+    return false;
+  }
+
+  const row = db
+    .query(
+      `
+      SELECT
+        COALESCE(MIN(version), 0) AS min_version,
+        COALESCE(MAX(version), 0) AS max_version,
+        COUNT(DISTINCT version) AS distinct_versions,
+        SUM(CASE WHEN version IS NULL THEN 1 ELSE 0 END) AS null_versions
+      FROM schema_migrations;
+      `,
+    )
+    .get() as
+    | {
+        min_version: number;
+        max_version: number;
+        distinct_versions: number;
+        null_versions: number;
+      }
+    | null;
+
+  if (!row) {
+    return false;
+  }
+
+  return (
+    row.null_versions === 0 &&
+    row.min_version === 1 &&
+    row.max_version === latestVersion &&
+    row.distinct_versions === latestVersion
+  );
+}
+
 export function migrateDatabase(db: Database): void {
+  validateMigrationPlan();
+
+  const latestVersion: number = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+
+  // Fast path: avoid BEGIN EXCLUSIVE when schema is already current.
+  // This reduces startup lock contention while keeping the explicit
+  // transactional migration path for non-current/legacy schemas.
+  if (isSchemaCurrentFastPath(db, latestVersion)) {
+    return;
+  }
+
   runExclusive(db, (): void => {
     ensureMigrationTable(db);
     ensureMigrationVersionColumn(db);
-    validateMigrationPlan();
 
     const version: number = currentVersion(db);
 

package/src/sync/service.ts

@@ -225,17 +225,55 @@ function countBehind(remoteDb: Database, cursorToken: string): number {
   return row?.count ?? 0;
 }
 
-function listRemoteEventIds(remoteDb: Database): Set<string> {
-  const rows = remoteDb.query("SELECT id FROM events;").all() as Array<{ id: string }>;
-  return new Set(rows.map((row) => row.id));
+function countAhead(localDb: Database, currentBranch: string | null, remoteDbPath: string): number {
+  if (!currentBranch) {
+    return 0;
+  }
+
+  localDb.query("ATTACH DATABASE ? AS sync_remote;").run(remoteDbPath);
+
+  try {
+    const row = localDb
+      .query(
+        `
+        SELECT COUNT(*) AS count
+        FROM events AS local_events
+        WHERE local_events.git_branch = @branch
+          AND NOT EXISTS (
+            SELECT 1
+            FROM sync_remote.events AS remote_events
+            WHERE remote_events.id = local_events.id
+          );
+        `,
+      )
+      .get({ "@branch": currentBranch }) as { count: number } | null;
+
+    return row?.count ?? 0;
+  } finally {
+    localDb.query("DETACH DATABASE sync_remote;").run();
+  }
 }
 
-function countAhead(localDb: Database, currentBranch: string | null, remoteEventIds: Set<string>): number {
-  const rows = localDb
-    .query("SELECT id, git_branch FROM events WHERE git_branch = ?;")
-    .all(currentBranch) as Array<{ id: string; git_branch: string | null }>;
+function buildSyncErrorHints(diagnostics: {
+  malformedPayloadEvents: number;
+  applyRejectedEvents: number;
+  conflictEvents: number;
+}): string[] {
+  const hints: string[] = [];
+
+  if (diagnostics.malformedPayloadEvents > 0) {
+    hints.push("Malformed event payloads were quarantined; inspect sync conflicts with field '__payload__'.");
+  }
+
+  if (diagnostics.applyRejectedEvents > 0) {
+    hints.push("Some events were quarantined as invalid; inspect sync conflicts with field '__apply__'.");
+  }
+
+  if (diagnostics.conflictEvents > 0) {
+    hints.push("Field-level conflicts detected; run 'trekoon sync conflicts list' and resolve pending entries.");
+  }
 
-  return rows.filter((row) => !remoteEventIds.has(row.id)).length;
+  return hints;
 }
 
 function readFieldValue(payload: EventPayload, field: string): unknown {
@@ -631,7 +669,7 @@ export function syncStatus(cwd: string, sourceBranch: string): SyncStatusSummary
     try {
       return {
         sourceBranch,
-        ahead: countAhead(storage.db, git.branchName, listRemoteEventIds(remote.db)),
+        ahead: countAhead(storage.db, git.branchName, remote.path),
         behind: countBehind(remote.db, cursorToken),
         pendingConflicts: countPendingConflicts(storage.db),
         git,
@@ -658,6 +696,10 @@ export function syncPull(cwd: string, sourceBranch: string): PullSummary {
 
     let appliedEvents = 0;
     let createdConflicts = 0;
+    let malformedPayloadEvents = 0;
+    let applyRejectedEvents = 0;
+    let quarantinedEvents = 0;
+    let conflictEvents = 0;
     let lastToken: string | null = null;
     let lastEventAt: number | null = cursor?.last_event_at ?? null;
 
@@ -666,6 +708,8 @@ export function syncPull(cwd: string, sourceBranch: string): PullSummary {
         const payloadValidation = parsePayload(incoming.payload);
 
         if (!payloadValidation.ok) {
+          malformedPayloadEvents += 1;
+          quarantinedEvents += 1;
           createConflict(
             storage.db,
             incoming,
@@ -688,6 +732,7 @@ export function syncPull(cwd: string, sourceBranch: string): PullSummary {
           const conflict = entityFieldConflict(storage.db, sourceBranch, incoming, fieldName, value);
 
           if (conflict) {
+            conflictEvents += 1;
             createConflict(storage.db, incoming, fieldName, conflict.oursValue, conflict.theirsValue);
             createdConflicts += 1;
             continue;
@@ -699,6 +744,8 @@ export function syncPull(cwd: string, sourceBranch: string): PullSummary {
         if (applyEntityFields(storage.db, incoming, fieldsToApply)) {
           appliedEvents += 1;
         } else if (incoming.operation !== "resolve_conflict") {
+          applyRejectedEvents += 1;
+          quarantinedEvents += 1;
           createConflict(
             storage.db,
             incoming,
@@ -726,6 +773,17 @@ export function syncPull(cwd: string, sourceBranch: string): PullSummary {
       appliedEvents,
       createdConflicts,
       cursorToken: lastToken,
+      diagnostics: {
+        malformedPayloadEvents,
+        applyRejectedEvents,
+        quarantinedEvents,
+        conflictEvents,
+        errorHints: buildSyncErrorHints({
+          malformedPayloadEvents,
+          applyRejectedEvents,
+          conflictEvents,
+        }),
+      },
     };
   } finally {
     remote.close();

package/src/sync/types.ts

@@ -21,6 +21,15 @@ export interface PullSummary {
   readonly appliedEvents: number;
   readonly createdConflicts: number;
   readonly cursorToken: string | null;
+  readonly diagnostics: SyncPullDiagnostics;
+}
+
+export interface SyncPullDiagnostics {
+  readonly malformedPayloadEvents: number;
+  readonly applyRejectedEvents: number;
+  readonly quarantinedEvents: number;
+  readonly conflictEvents: number;
+  readonly errorHints: readonly string[];
 }
 
 export interface ResolveSummary {