@notis_ai/cli 0.2.13 → 0.2.15

package/src/runtime/skill-sync/symlink-manager.ts

@@ -0,0 +1,383 @@
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+
+import {
+  AGENTS_DIR,
+  LEGACY_AGENTS_SKILLS_DIR,
+  NOTIS_SKILL_SYNC_ROOT,
+  safeName,
+} from './local-scanner';
+import { normalizeAgentTargets, type CloudSkill, type NotisSyncState } from './types';
+
+const HOME_DIR = os.homedir();
+
+const EXTERNAL_AGENT_SKILL_DIRS = {
+  claude_code: path.join(HOME_DIR, '.claude', 'skills'),
+  cursor: path.join(HOME_DIR, '.cursor', 'skills'),
+  codex: path.join(HOME_DIR, '.codex', 'skills'),
+} as const;
+
+type ExternalAgent = keyof typeof EXTERNAL_AGENT_SKILL_DIRS;
+
+const EXTERNAL_AGENTS = Object.keys(EXTERNAL_AGENT_SKILL_DIRS) as ExternalAgent[];
+
+export interface DeletedAgentSymlink {
+  skillId: string;
+  skillName: string;
+  agent: ExternalAgent;
+}
+
+type AgentSkillDirs = {
+  notis: string;
+} & typeof EXTERNAL_AGENT_SKILL_DIRS;
+
+export interface SymlinkSyncOptions {
+  agentSkillDirs?: Partial<AgentSkillDirs>;
+  legacyGlobalSkillsDir?: string;
+  removeUndesired?: boolean;
+}
+
+export interface RemoveSkillSymlinkOptions extends SymlinkSyncOptions {
+  ownership?: 'any-managed' | 'exact-skill-dir';
+}
+
+export interface SymlinkSyncResult {
+  linked: number;
+  removed: number;
+  skipped: number;
+}
+
+/** Remove only links into another account's managed mirror. This is safe even
+ * when automatic sync is disabled: it never changes either account mirror and
+ * preserves links owned by the currently authenticated account. */
+export async function removeForeignAccountSymlinks(
+  skillsDir: string,
+  options: SymlinkSyncOptions = {},
+): Promise<number> {
+  const agentSkillDirs = { ...defaultAgentSkillDirs(skillsDir), ...options.agentSkillDirs };
+  const currentRoot = path.resolve(skillsDir);
+  const foreignCapableRoots = [
+    path.join(path.resolve(NOTIS_SKILL_SYNC_ROOT), 'users'),
+    path.join(path.resolve(AGENTS_DIR), 'notis', 'users'),
+    path.dirname(path.dirname(currentRoot)),
+  ];
+  let removed = 0;
+  const legacyGlobalSkillsDir = options.legacyGlobalSkillsDir || LEGACY_AGENTS_SKILLS_DIR;
+  for (const agentDir of new Set([...Object.values(agentSkillDirs), legacyGlobalSkillsDir])) {
+    let entries;
+    try {
+      entries = await fs.readdir(agentDir, { withFileTypes: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!entry.isSymbolicLink()) continue;
+      const entryPath = path.join(agentDir, entry.name);
+      try {
+        const target = await fs.readlink(entryPath);
+        const resolvedTarget = path.resolve(path.dirname(entryPath), target);
+        const belongsToAnyAccount = foreignCapableRoots.some((root) => (
+          resolvedTarget.startsWith(`${root}${path.sep}`)
+        ));
+        const belongsToCurrentAccount = resolvedTarget === currentRoot
+          || resolvedTarget.startsWith(`${currentRoot}${path.sep}`);
+        if (belongsToAnyAccount && !belongsToCurrentAccount) {
+          await fs.unlink(entryPath);
+          removed += 1;
+        }
+      } catch (error) {
+        // A disappearing link is already safe. Permission and I/O failures
+        // must fail closed: otherwise a previous account's link can remain
+        // exposed while the repeating sync reports success.
+        if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error;
+      }
+    }
+  }
+  return removed;
+}
+
+function managedSkillRoots(
+  skillsDir: string,
+  legacyGlobalSkillsDir: string = LEGACY_AGENTS_SKILLS_DIR,
+): string[] {
+  const resolvedSkillsDir = path.resolve(skillsDir);
+  const scopedUsersRoot = path.dirname(path.dirname(resolvedSkillsDir));
+  const roots = [
+    resolvedSkillsDir,
+    path.resolve(legacyGlobalSkillsDir),
+    path.join(path.resolve(NOTIS_SKILL_SYNC_ROOT), 'users'),
+    path.join(path.resolve(AGENTS_DIR), 'notis', 'users'),
+  ];
+  if (path.basename(scopedUsersRoot) === 'users') {
+    roots.push(scopedUsersRoot);
+  }
+  return roots;
+}
+
+async function isManagedSymlink(linkPath: string, managedRoots: string[]): Promise<boolean> {
+  try {
+    const stats = await fs.lstat(linkPath);
+    if (!stats.isSymbolicLink()) {
+      return false;
+    }
+
+    const target = await fs.readlink(linkPath);
+    const resolvedTarget = path.resolve(path.dirname(linkPath), target);
+    return managedRoots.some((root) => (
+      resolvedTarget === root || resolvedTarget.startsWith(`${root}${path.sep}`)
+    ));
+  } catch {
+    return false;
+  }
+}
+
+async function ensureCorrectSymlink(linkPath: string, targetPath: string): Promise<'linked' | 'skipped' | 'blocked'> {
+  try {
+    const stats = await fs.lstat(linkPath);
+    if (stats.isSymbolicLink()) {
+      const currentTarget = await fs.readlink(linkPath);
+      const resolvedTarget = path.resolve(path.dirname(linkPath), currentTarget);
+      if (resolvedTarget === targetPath) {
+        return 'skipped';
+      }
+      await fs.unlink(linkPath);
+    } else {
+      return 'blocked';
+    }
+  } catch {
+    // Missing path is expected.
+  }
+
+  const relativePath = path.relative(path.dirname(linkPath), targetPath);
+  await fs.symlink(relativePath, linkPath);
+  return 'linked';
+}
+
+function defaultAgentSkillDirs(skillsDir: string): AgentSkillDirs {
+  return {
+    notis: skillsDir,
+    ...EXTERNAL_AGENT_SKILL_DIRS,
+  };
+}
+
+async function removeUndesiredManagedSymlinks(
+  agentDir: string,
+  desiredSkills: Set<string>,
+  managedRoots: string[],
+): Promise<number> {
+  let removed = 0;
+  try {
+    await fs.mkdir(agentDir, { recursive: true });
+    const existingEntries = await fs.readdir(agentDir, { withFileTypes: true });
+    for (const entry of existingEntries) {
+      const entryPath = path.join(agentDir, entry.name);
+      if (!desiredSkills.has(entry.name) && await isManagedSymlink(entryPath, managedRoots)) {
+        await fs.unlink(entryPath);
+        removed += 1;
+      }
+    }
+  } catch {
+    // Missing or unreadable agent directories should not block skill sync.
+  }
+  return removed;
+}
+
+export async function removeAllSymlinksForSkill(
+  skillName: string,
+  skillsDir: string = LEGACY_AGENTS_SKILLS_DIR,
+  options: RemoveSkillSymlinkOptions = {},
+): Promise<number> {
+  let removed = 0;
+  const agentSkillDirs = { ...defaultAgentSkillDirs(skillsDir), ...options.agentSkillDirs };
+  const legacyGlobalSkillsDir = options.legacyGlobalSkillsDir || LEGACY_AGENTS_SKILLS_DIR;
+  const managedRoots = managedSkillRoots(skillsDir, legacyGlobalSkillsDir);
+  const agentDirs = new Set([...Object.values(agentSkillDirs), legacyGlobalSkillsDir]);
+  const expectedTarget = path.resolve(skillsDir, safeName(skillName, skillsDir));
+  for (const agentDir of agentDirs) {
+    const linkPath = path.join(agentDir, safeName(skillName, agentDir));
+    const owned = options.ownership === 'exact-skill-dir'
+      ? await isManagedSymlink(linkPath, [expectedTarget])
+      : await isManagedSymlink(linkPath, managedRoots);
+    if (owned) {
+      await fs.unlink(linkPath);
+      removed += 1;
+    }
+  }
+  return removed;
+}
+
+/**
+ * Detect per-agent skill symlinks that we created on a prior sync but that the user has since
+ * deleted locally (e.g. `rm ~/.claude/skills/<skill>`). The caller turns each result into a
+ * per-agent deactivation so the deletion sticks instead of being recreated on the next pass.
+ *
+ * A pair is flagged only when the skill is cloud-active for that agent, the previous sync state
+ * recorded it active for that agent (so we know we created the link), and the link is now truly
+ * absent (lstat ENOENT). Stale/wrong-target links and real files blocking the path are NOT
+ * deletions — those are repaired/skipped by syncSymlinks as before. Only external agents are
+ * considered; `notis` has no symlink (its dir is the source skills folder).
+ */
+export async function detectDeletedAgentSymlinks(
+  cloudSkills: CloudSkill[],
+  previousState: NotisSyncState,
+  skillsDir: string = LEGACY_AGENTS_SKILLS_DIR,
+  options: SymlinkSyncOptions = {},
+): Promise<DeletedAgentSymlink[]> {
+  const agentSkillDirs = { ...defaultAgentSkillDirs(skillsDir), ...options.agentSkillDirs };
+  const deletions: DeletedAgentSymlink[] = [];
+
+  for (const agent of EXTERNAL_AGENTS) {
+    const agentDir = agentSkillDirs[agent];
+    if (path.resolve(agentDir) === path.resolve(skillsDir)) {
+      continue;
+    }
+
+    // A missing (or non-directory) agent skills directory is NOT a per-skill deletion: removing
+    // ~/.claude/skills wholesale would otherwise make every entry's link path ENOENT and
+    // deactivate every skill for that agent. syncSymlinks recreates the directory and its links,
+    // so only absent entries INSIDE an existing agent directory count as explicit user deletions.
+    try {
+      const dirStat = await fs.stat(agentDir);
+      if (!dirStat.isDirectory()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+
+    for (const skill of cloudSkills) {
+      if (skill.status !== 'active') {
+        continue;
+      }
+      if (!skill.id || skill.id.startsWith('local-')) {
+        continue;
+      }
+      const previous = previousState.skills[skill.name];
+      if (!previous) {
+        continue;
+      }
+
+      const cloudTargets = normalizeAgentTargets(skill.agent_targets);
+      const previousTargets = normalizeAgentTargets(previous.agentTargets);
+      if (!cloudTargets[agent] || !previousTargets[agent]) {
+        continue;
+      }
+
+      let safeSkillName: string;
+      try {
+        safeSkillName = safeName(skill.name, skillsDir);
+      } catch {
+        continue;
+      }
+
+      const linkPath = path.join(agentDir, safeName(safeSkillName, agentDir));
+      try {
+        await fs.lstat(linkPath);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+          deletions.push({ skillId: skill.id, skillName: skill.name, agent });
+        }
+      }
+    }
+  }
+
+  return deletions;
+}
+
+export async function syncSymlinks(
+  skills: CloudSkill[],
+  skillsDir: string = LEGACY_AGENTS_SKILLS_DIR,
+  options: SymlinkSyncOptions = {},
+): Promise<SymlinkSyncResult> {
+  await fs.mkdir(skillsDir, { recursive: true });
+
+  const result: SymlinkSyncResult = {
+    linked: 0,
+    removed: 0,
+    skipped: 0,
+  };
+  const agentSkillDirs = { ...defaultAgentSkillDirs(skillsDir), ...options.agentSkillDirs };
+  const legacyGlobalSkillsDir = options.legacyGlobalSkillsDir || LEGACY_AGENTS_SKILLS_DIR;
+  const managedRoots = managedSkillRoots(skillsDir, legacyGlobalSkillsDir);
+
+  const desiredByAgent = {
+    notis: new Set<string>(),
+    claude_code: new Set<string>(),
+    cursor: new Set<string>(),
+    codex: new Set<string>(),
+  };
+
+  for (const skill of skills) {
+    if (skill.status !== 'active') {
+      continue;
+    }
+
+    const safeSkillName = safeName(skill.name, skillsDir);
+    const targets = normalizeAgentTargets(skill.agent_targets);
+    if (targets.notis) {
+      desiredByAgent.notis.add(safeSkillName);
+    }
+    if (targets.claude_code) {
+      desiredByAgent.claude_code.add(safeSkillName);
+    }
+    if (targets.cursor) {
+      desiredByAgent.cursor.add(safeSkillName);
+    }
+    if (targets.codex) {
+      desiredByAgent.codex.add(safeSkillName);
+    }
+  }
+
+  for (const [agent, agentDir] of Object.entries(agentSkillDirs) as Array<[keyof AgentSkillDirs, string]>) {
+    if (path.resolve(agentDir) === path.resolve(skillsDir)) {
+      result.skipped += desiredByAgent[agent].size;
+      continue;
+    }
+
+    await fs.mkdir(agentDir, { recursive: true });
+
+    const desiredSkills = desiredByAgent[agent];
+    if (options.removeUndesired !== false) {
+      result.removed += await removeUndesiredManagedSymlinks(agentDir, desiredSkills, managedRoots);
+    }
+
+    for (const skillName of desiredSkills) {
+      const targetPath = path.join(skillsDir, skillName);
+      const linkPath = path.join(agentDir, safeName(skillName, agentDir));
+      try {
+        await fs.access(targetPath);
+      } catch {
+        result.skipped += 1;
+        continue;
+      }
+      const syncOutcome = await ensureCorrectSymlink(linkPath, targetPath);
+      if (syncOutcome === 'linked') {
+        result.linked += 1;
+      } else if (syncOutcome === 'blocked') {
+        console.warn(
+          `[skill-sync] Could not link "${skillName}" for ${agent}: non-symlink entry blocks ${linkPath}`,
+        );
+        result.skipped += 1;
+      } else {
+        result.skipped += 1;
+      }
+    }
+  }
+
+  if (
+    options.removeUndesired !== false
+    && !Object.values(agentSkillDirs).some(
+      (agentDir) => path.resolve(agentDir) === path.resolve(legacyGlobalSkillsDir),
+    )
+  ) {
+    result.removed += await removeUndesiredManagedSymlinks(
+      legacyGlobalSkillsDir,
+      new Set(),
+      managedRoots,
+    );
+  }
+
+  return result;
+}

package/src/runtime/skill-sync/sync-plan.ts

@@ -0,0 +1,22 @@
+import type { LocalSkill, NotisSyncState } from "./types";
+
+export function getPushCandidates(
+  localSkills: LocalSkill[],
+  syncState: NotisSyncState,
+  cloudCuratedSkillNames: ReadonlySet<string> = new Set(),
+  cloudSkillNames?: ReadonlySet<string>,
+): LocalSkill[] {
+  return localSkills.filter((skill) => {
+    if (cloudCuratedSkillNames.has(skill.name)) {
+      return false;
+    }
+    const previous = syncState.skills[skill.name];
+    if (!previous) {
+      return true;
+    }
+    if (cloudSkillNames && !cloudSkillNames.has(skill.name)) {
+      return false;
+    }
+    return previous.folderHash !== skill.folderHash;
+  });
+}

package/src/runtime/skill-sync/types.ts

@@ -0,0 +1,103 @@
+export interface AgentTargets {
+  notis: boolean;
+  claude_code: boolean;
+  cursor: boolean;
+  codex: boolean;
+}
+
+export interface SyncedSkill {
+  cloudId: string;
+  folderHash: string;
+  agentTargets: AgentTargets;
+  syncedAt: string;
+}
+
+export interface NotisSyncState {
+  version: 1;
+  lastSyncedAt: string | null;
+  skills: Record<string, SyncedSkill>;
+}
+
+export interface LocalSkill {
+  name: string;
+  skillMd: string;
+  description: string;
+  folderHash: string;
+  directoryPath: string;
+  sourceUrl?: string;
+  bundleFiles?: BundleFile[];
+}
+
+export interface BundleFile {
+  path: string;
+  content_b64: string;
+}
+
+export interface CloudSkill {
+  id: string;
+  name: string;
+  description: string | null;
+  skill_md: string | null;
+  agent_targets?: Partial<AgentTargets> | null;
+  skill_folder_hash?: string | null;
+  skill_source_url?: string | null;
+  bundle_files?: BundleFile[] | null;
+  bundle_hydration_failed?: boolean | null;
+  source: string;
+  status: string;
+}
+
+export interface SyncSettings {
+  /** Server-verified canonical Notis account id used to scope local mirrors. */
+  user_id?: string;
+  sync_enabled: boolean;
+  last_synced_at: string | null;
+}
+
+export interface EntitlementAccessDetail {
+  status: "error";
+  code: "entitlement_upgrade_required";
+  upgrade_required: true;
+  entitlement: string;
+  required_plan: string;
+  upgrade_url: string;
+  message: string;
+  next_action: Record<string, unknown>;
+}
+
+export interface SyncPullResponse {
+  skills: CloudSkill[];
+  sync_enabled: boolean;
+  last_synced_at: string | null;
+  /** Legacy servers could return a successful empty denial. Current servers
+   * return HTTP 403; either form must preserve existing local state. */
+  entitlement_access?: EntitlementAccessDetail;
+}
+
+/** A skill the server could not sync, with a user-facing reason (e.g. an invalid
+ * SKILL.md description rejected by OpenAI). One bad skill no longer fails the batch. */
+export interface SkillSyncFailure {
+  name: string;
+  error: string;
+}
+
+export interface SyncPushResponse {
+  skills: unknown[];
+  failed?: SkillSyncFailure[];
+}
+
+export const DEFAULT_AGENT_TARGETS: AgentTargets = {
+  notis: true,
+  claude_code: true,
+  cursor: true,
+  codex: true,
+};
+
+export function normalizeAgentTargets(targets?: Partial<AgentTargets> | null): AgentTargets {
+  return {
+    notis: Boolean(targets?.notis ?? DEFAULT_AGENT_TARGETS.notis),
+    claude_code: Boolean(targets?.claude_code ?? DEFAULT_AGENT_TARGETS.claude_code),
+    cursor: Boolean(targets?.cursor ?? DEFAULT_AGENT_TARGETS.cursor),
+    codex: Boolean(targets?.codex ?? DEFAULT_AGENT_TARGETS.codex),
+  };
+}

package/src/runtime/skill-sync/write-cloud-skill.ts

@@ -0,0 +1,50 @@
+import type { CloudSkill } from './types';
+
+interface WriteCloudSkillDependencies {
+  downloadSkillBundle: (bundleUrl: string) => Promise<Buffer>;
+  writeCloudSkillToDisk: (skill: CloudSkill, bundleBytes?: Buffer) => Promise<boolean>;
+  onWarning?: (message: string, error: unknown) => void;
+}
+
+export async function writeCloudSkillWithBundleFallback(
+  skill: CloudSkill,
+  dependencies: WriteCloudSkillDependencies,
+): Promise<boolean> {
+  if (skill.skill_source_url) {
+    try {
+      const bundleBytes = await dependencies.downloadSkillBundle(skill.skill_source_url);
+      const wroteBundleToDisk = await dependencies.writeCloudSkillToDisk(skill, bundleBytes);
+      if (wroteBundleToDisk) {
+        return true;
+      }
+
+      dependencies.onWarning?.(
+        `Bundle sync for "${skill.name}" produced no local changes, falling back to SKILL.md payload.`,
+        new Error('Bundle write returned false'),
+      );
+    } catch (error) {
+      dependencies.onWarning?.(
+        `Failed to apply bundle sync for "${skill.name}", falling back to SKILL.md payload.`,
+        error,
+      );
+    }
+  }
+
+  if (skill.bundle_hydration_failed) {
+    dependencies.onWarning?.(
+      `Skipping markdown fallback for synced skill "${skill.name}" because its stored bundle could not be hydrated by the server.`,
+      new Error('Bundle hydration failed'),
+    );
+    return false;
+  }
+
+  try {
+    return await dependencies.writeCloudSkillToDisk(skill);
+  } catch (error) {
+    dependencies.onWarning?.(
+      `Failed to write synced skill "${skill.name}" to disk.`,
+      error,
+    );
+    return false;
+  }
+}

package/src/runtime/store-screenshot.js

@@ -1,4 +1,3 @@
-import sharp from 'sharp';
 import { fileURLToPath } from 'node:url';
 
 const STORE_SCREENSHOT_ASPECT = 16 / 10;
@@ -19,6 +18,10 @@ const ACCENT_PALETTES = {
 
 const ACCENT_NAMES = Object.keys(ACCENT_PALETTES);
 
+async function loadSharp() {
+  return (await import('sharp')).default;
+}
+
 function stableHash(value) {
   let hash = 2166136261;
   for (const character of String(value || 'notis-app')) {
@@ -59,6 +62,7 @@ export function storeScreenshotLayout(width = 2000, height = 1250) {
 }
 
 async function backdropImage(layout) {
+  const sharp = await loadSharp();
   return sharp(SHARED_BACKDROP_PATH)
     .resize(layout.width, layout.height, { fit: 'cover', position: 'centre' })
     .png()
@@ -88,6 +92,7 @@ export async function composeStoreScreenshot({
   focused = false,
   theme = 'light',
 }) {
+  const sharp = await loadSharp();
   const resolvedTheme = theme === 'dark' ? 'dark' : 'light';
   const layout = storeScreenshotLayout(width, height);
   const resolvedAccent = resolveStoreScreenshotAccent(accent, seed);

package/src/runtime/sync-skills.d.ts

@@ -0,0 +1,37 @@
+import type { BaseSkillReconcileResult } from './base-skills.js';
+
+export interface ReconcileAllSkillsResult {
+  baseSkills: string[];
+  baseInstalled: number;
+  baseLinked: number;
+  baseBackups: string[];
+}
+
+export interface SkillSyncLockOptions {
+  home?: string;
+  timeoutMs?: number;
+  staleMs?: number;
+  pollMs?: number;
+  now?: () => number;
+}
+
+export function withSkillSyncLock<T>(
+  callback: () => Promise<T> | T,
+  options?: SkillSyncLockOptions,
+): Promise<T>;
+
+export function reconcileAllSkills<T extends object>(options: {
+  serverUrl: string;
+  jwt: string;
+  honorSyncEnabled: boolean;
+  userId?: string | null;
+  home?: string;
+  runAccountSync: (
+    serverUrl: string,
+    jwt: string,
+    dependencies: Record<string, never>,
+    options: { honorSyncEnabled: boolean },
+  ) => Promise<T>;
+  reconcileBase?: (options: { userId?: string | null; home?: string }) => BaseSkillReconcileResult;
+  lockOptions?: Omit<SkillSyncLockOptions, 'home'>;
+}): Promise<T & ReconcileAllSkillsResult>;