skill-flow 1.0.0

package/src/tui/selection-state.ts

@@ -0,0 +1,45 @@
+export type ParentSelectionState = "empty" | "partial" | "full";
+
+export type TreeSelectionState = {
+  allLeafIds: string[];
+  selectedLeafIds: string[];
+};
+
+export function getParentSelectionState(
+  state: TreeSelectionState,
+): ParentSelectionState {
+  if (state.selectedLeafIds.length === 0) {
+    return "empty";
+  }
+  if (state.selectedLeafIds.length === state.allLeafIds.length) {
+    return "full";
+  }
+  return "partial";
+}
+
+// parent
+//   [ ] -> [x] -> [-] transitions come from child toggles
+// children
+//   toggle child recalculates parent from current selected set
+export function toggleParent(state: TreeSelectionState): TreeSelectionState {
+  return getParentSelectionState(state) === "full"
+    ? { ...state, selectedLeafIds: [] }
+    : { ...state, selectedLeafIds: [...state.allLeafIds] };
+}
+
+export function toggleChild(
+  state: TreeSelectionState,
+  leafId: string,
+): TreeSelectionState {
+  const selected = new Set(state.selectedLeafIds);
+  if (selected.has(leafId)) {
+    selected.delete(leafId);
+  } else {
+    selected.add(leafId);
+  }
+
+  return {
+    ...state,
+    selectedLeafIds: state.allLeafIds.filter((id) => selected.has(id)),
+  };
+}

package/src/utils/constants.ts

@@ -0,0 +1,201 @@
+import os from "node:os";
+import path from "node:path";
+import type {
+  DeploymentStrategy,
+  DeploymentTargetName,
+} from "../domain/types.js";
+
+export const SCHEMA_VERSION = 1 as const;
+
+export function getStateRoot(): string {
+  return process.env.SKILL_FLOW_STATE_ROOT
+    ? path.resolve(process.env.SKILL_FLOW_STATE_ROOT)
+    : path.join(os.homedir(), ".skillflow");
+}
+
+export type TargetDefinition = {
+  label: string;
+  strategy: DeploymentStrategy;
+  envVar: string;
+  writerKey: string;
+  writeRootCandidates: string[];
+  compatReadRootCandidates: string[];
+};
+
+export const TARGET_ORDER: DeploymentTargetName[] = [
+  "claude-code",
+  "codex",
+  "cursor",
+  "github-copilot",
+  "gemini-cli",
+  "opencode",
+  "openclaw",
+  "pi",
+  "windsurf",
+  "roo-code",
+  "cline",
+  "amp",
+  "kiro",
+];
+
+export const TARGET_DEFINITIONS: Record<DeploymentTargetName, TargetDefinition> = {
+  "claude-code": {
+    label: "Claude Code",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_CLAUDE_CODE",
+    writerKey: "claude-home",
+    writeRootCandidates: [path.join(os.homedir(), ".claude", "skills")],
+    compatReadRootCandidates: [],
+  },
+  codex: {
+    label: "Codex",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_CODEX",
+    writerKey: "agents-skills",
+    writeRootCandidates: [
+      path.join(os.homedir(), ".agents", "skills"),
+      path.join(os.homedir(), ".codex", ".agents", "skills"),
+    ],
+    compatReadRootCandidates: [path.join("/etc", "codex", "skills")],
+  },
+  cursor: {
+    label: "Cursor",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_CURSOR",
+    writerKey: "cursor-home",
+    writeRootCandidates: [path.join(os.homedir(), ".cursor", "skills")],
+    compatReadRootCandidates: [
+      path.join(os.homedir(), ".agents", "skills"),
+      path.join(os.homedir(), ".claude", "skills"),
+      path.join(os.homedir(), ".codex", "skills"),
+    ],
+  },
+  "github-copilot": {
+    label: "GitHub Copilot",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_GITHUB_COPILOT",
+    writerKey: "copilot-home",
+    writeRootCandidates: [path.join(os.homedir(), ".copilot", "skills")],
+    compatReadRootCandidates: [
+      path.join(os.homedir(), ".claude", "skills"),
+      path.join(os.homedir(), ".agents", "skills"),
+    ],
+  },
+  "gemini-cli": {
+    label: "Gemini CLI",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_GEMINI_CLI",
+    writerKey: "gemini-home",
+    writeRootCandidates: [path.join(os.homedir(), ".gemini", "skills")],
+    compatReadRootCandidates: [path.join(os.homedir(), ".agents", "skills")],
+  },
+  opencode: {
+    label: "OpenCode",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_OPENCODE",
+    writerKey: "opencode-home",
+    writeRootCandidates: [
+      path.join(os.homedir(), ".config", "opencode", "skills"),
+      path.join(os.homedir(), ".opencode", "skills"),
+    ],
+    compatReadRootCandidates: [
+      path.join(os.homedir(), ".claude", "skills"),
+      path.join(os.homedir(), ".agents", "skills"),
+    ],
+  },
+  openclaw: {
+    label: "OpenClaw",
+    strategy: "copy",
+    envVar: "SKILL_FLOW_TARGET_OPENCLAW",
+    writerKey: "openclaw-home",
+    writeRootCandidates: [path.join(os.homedir(), ".openclaw", "skills")],
+    compatReadRootCandidates: [],
+  },
+  pi: {
+    label: "Pi",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_PI",
+    writerKey: "pi-home",
+    writeRootCandidates: [path.join(os.homedir(), ".pi", "agent", "skills")],
+    compatReadRootCandidates: [
+      path.join(os.homedir(), ".agents", "skills"),
+      path.join(os.homedir(), ".claude", "skills"),
+      path.join(os.homedir(), ".codex", "skills"),
+    ],
+  },
+  windsurf: {
+    label: "Windsurf",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_WINDSURF",
+    writerKey: "windsurf-home",
+    writeRootCandidates: [path.join(os.homedir(), ".codeium", "windsurf", "skills")],
+    compatReadRootCandidates: [
+      path.join("/Library", "Application Support", "Windsurf", "skills"),
+    ],
+  },
+  "roo-code": {
+    label: "Roo Code",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_ROO_CODE",
+    writerKey: "roo-home",
+    writeRootCandidates: [path.join(os.homedir(), ".roo", "skills")],
+    compatReadRootCandidates: [],
+  },
+  cline: {
+    label: "Cline",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_CLINE",
+    writerKey: "cline-home",
+    writeRootCandidates: [path.join(os.homedir(), ".cline", "skills")],
+    compatReadRootCandidates: [path.join(os.homedir(), ".claude", "skills")],
+  },
+  amp: {
+    label: "Amp",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_AMP",
+    writerKey: "amp-home",
+    writeRootCandidates: [
+      path.join(os.homedir(), ".config", "agents", "skills"),
+      path.join(os.homedir(), ".config", "amp", "skills"),
+    ],
+    compatReadRootCandidates: [path.join(os.homedir(), ".claude", "skills")],
+  },
+  kiro: {
+    label: "Kiro",
+    strategy: "symlink",
+    envVar: "SKILL_FLOW_TARGET_KIRO",
+    writerKey: "kiro-home",
+    writeRootCandidates: [path.join(os.homedir(), ".kiro", "skills")],
+    compatReadRootCandidates: [],
+  },
+};
+
+export const TARGET_LABELS: Record<DeploymentTargetName, string> = Object.fromEntries(
+  TARGET_ORDER.map((target) => [target, TARGET_DEFINITIONS[target].label]),
+) as Record<DeploymentTargetName, string>;
+
+export const TARGET_STRATEGIES: Record<DeploymentTargetName, DeploymentStrategy> =
+  Object.fromEntries(
+    TARGET_ORDER.map((target) => [target, TARGET_DEFINITIONS[target].strategy]),
+  ) as Record<DeploymentTargetName, DeploymentStrategy>;
+
+export const TARGET_ENV_VARS: Record<DeploymentTargetName, string> = Object.fromEntries(
+  TARGET_ORDER.map((target) => [target, TARGET_DEFINITIONS[target].envVar]),
+) as Record<DeploymentTargetName, string>;
+
+export const TARGET_WRITER_KEYS: Record<DeploymentTargetName, string> = Object.fromEntries(
+  TARGET_ORDER.map((target) => [target, TARGET_DEFINITIONS[target].writerKey]),
+) as Record<DeploymentTargetName, string>;
+
+export const TARGET_PATH_CANDIDATES: Record<DeploymentTargetName, string[]> =
+  Object.fromEntries(
+    TARGET_ORDER.map((target) => [target, TARGET_DEFINITIONS[target].writeRootCandidates]),
+  ) as Record<DeploymentTargetName, string[]>;
+
+export const TARGET_COMPAT_READ_CANDIDATES: Record<DeploymentTargetName, string[]> =
+  Object.fromEntries(
+    TARGET_ORDER.map((target) => [
+      target,
+      TARGET_DEFINITIONS[target].compatReadRootCandidates,
+    ]),
+  ) as Record<DeploymentTargetName, string[]>;

package/src/utils/format.ts

@@ -0,0 +1,59 @@
+import type {
+  DeploymentAction,
+  DeploymentTargetName,
+  DoctorIssue,
+  WorkflowSummary,
+} from "../domain/types.js";
+import { TARGET_LABELS } from "./constants.js";
+
+export function formatWorkflowList(summaries: WorkflowSummary[]): string {
+  if (summaries.length === 0) {
+    return [
+      "No workflow groups yet",
+      "Add a Git source to discover a grouped set of related skills.",
+    ].join("\n");
+  }
+
+  return summaries
+    .map((summary) => {
+      const invalidCount = summary.lock?.invalidLeafs.length ?? 0;
+      const warningCount = summary.leafs.reduce(
+        (count, leaf) => count + leaf.metadataWarnings.length,
+        0,
+      );
+      const suffixParts = [];
+      if (warningCount > 0) {
+        suffixParts.push(`${warningCount} warnings`);
+      }
+      if (invalidCount > 0) {
+        suffixParts.push(`${invalidCount} skipped`);
+      }
+      const suffix = suffixParts.length > 0 ? `, ${suffixParts.join(", ")}` : "";
+      return `${summary.source.id}  ${summary.health}  ${summary.leafs.length} skills  ${summary.activeTargetCount} targets${suffix}`;
+    })
+    .join("\n");
+}
+
+export function countActions(actions: DeploymentAction[]): Record<string, number> {
+  return actions.reduce<Record<string, number>>((acc, action) => {
+    acc[action.kind] = (acc[action.kind] ?? 0) + 1;
+    return acc;
+  }, {});
+}
+
+export function formatActionSummary(actions: DeploymentAction[]): string {
+  const counts = countActions(actions);
+  return ["create", "update", "remove", "noop", "blocked"]
+    .map((kind) => `${kind}:${counts[kind] ?? 0}`)
+    .join("  ");
+}
+
+export function formatTargetName(target: DeploymentTargetName): string {
+  return TARGET_LABELS[target];
+}
+
+export function formatDoctorIssue(issue: DoctorIssue): string {
+  const target = issue.target ? ` ${formatTargetName(issue.target)}` : "";
+  const leaf = issue.leafId ? ` ${issue.leafId}` : "";
+  return `[${issue.severity.toUpperCase()}] ${issue.sourceId}${target}${leaf} ${issue.message}`;
+}

package/src/utils/fs.ts

@@ -0,0 +1,102 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await fs.lstat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(targetPath: string): Promise<void> {
+  await fs.mkdir(targetPath, { recursive: true });
+}
+
+export async function readJsonFile<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  const tempPath = `${filePath}.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await fs.rename(tempPath, filePath);
+}
+
+export async function removePath(targetPath: string): Promise<void> {
+  await fs.rm(targetPath, { recursive: true, force: true });
+}
+
+export async function copyDirectory(sourcePath: string, targetPath: string): Promise<void> {
+  await removePath(targetPath);
+  await fs.cp(sourcePath, targetPath, { recursive: true, dereference: false });
+}
+
+export async function createSymlink(
+  sourcePath: string,
+  targetPath: string,
+): Promise<void> {
+  await removePath(targetPath);
+  await ensureDir(path.dirname(targetPath));
+  await fs.symlink(sourcePath, targetPath, "junction");
+}
+
+export async function isBrokenSymlink(targetPath: string): Promise<boolean> {
+  try {
+    const stats = await fs.lstat(targetPath);
+    if (!stats.isSymbolicLink()) {
+      return false;
+    }
+    const resolved = await fs.readlink(targetPath);
+    const absolute = path.resolve(path.dirname(targetPath), resolved);
+    return !(await pathExists(absolute));
+  } catch {
+    return false;
+  }
+}
+
+export async function hashDirectory(rootPath: string): Promise<string> {
+  const hash = crypto.createHash("sha256");
+
+  async function walk(currentPath: string): Promise<void> {
+    const entries = await fs.readdir(currentPath, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const entry of entries) {
+      if (entry.name === ".git" || entry.name === "node_modules") {
+        continue;
+      }
+
+      const entryPath = path.join(currentPath, entry.name);
+      const relativePath = path.relative(rootPath, entryPath);
+
+      hash.update(relativePath);
+      if (entry.isDirectory()) {
+        hash.update("dir");
+        await walk(entryPath);
+      } else if (entry.isFile()) {
+        hash.update("file");
+        hash.update(await fs.readFile(entryPath));
+      }
+    }
+  }
+
+  await walk(rootPath);
+  return hash.digest("hex");
+}
+
+export function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}

package/src/utils/git.ts

@@ -0,0 +1,16 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export async function git(
+  args: string[],
+  options: { cwd?: string } = {},
+): Promise<string> {
+  const { stdout } = await execFileAsync("git", args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    env: process.env,
+  });
+  return stdout.trim();
+}

package/src/utils/result.ts

@@ -0,0 +1,23 @@
+import type { Failure, Result, Warning } from "../domain/types.js";
+
+export function ok<T>(data: T, warnings: Warning[] = []): Result<T> {
+  return { ok: true, data, warnings, errors: [] };
+}
+
+export function fail<T>(
+  errors: Failure | Failure[],
+  warnings: Warning[] = [],
+  data?: T,
+): Result<T> {
+  const base = {
+    ok: false,
+    warnings,
+    errors: Array.isArray(errors) ? errors : [errors],
+  } as const;
+
+  return data === undefined ? base : { ...base, data };
+}
+
+export function mergeWarnings(...warningSets: Warning[][]): Warning[] {
+  return warningSets.flat();
+}

package/src/utils/source-id.ts

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { slugify } from "./fs.js";
+
+export function deriveDisplayName(locator: string): string {
+  const trimmed = locator.replace(/\/+$/, "");
+  if (/^[^/\s]+\/[^/\s]+$/.test(trimmed)) {
+    return trimmed.split("/")[1] ?? trimmed;
+  }
+
+  if (trimmed.endsWith(".git")) {
+    return path.basename(trimmed, ".git");
+  }
+
+  return path.basename(trimmed) || slugify(locator);
+}
+
+export function deriveSourceId(locator: string): string {
+  return slugify(deriveDisplayName(locator) || locator);
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "declaration": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "jsx": "react-jsx",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["dist", "node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/tests/**/*.test.ts"],
+    exclude: ["dist/**", "node_modules/**"],
+  },
+});