skill-flow 1.0.0

package/src/services/deployment-planner.ts

@@ -0,0 +1,259 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type {
+  DeploymentAction,
+  DeploymentPlan,
+  DeploymentRecord,
+  DeploymentTargetName,
+  LeafRecord,
+  LockFile,
+  Manifest,
+  Result,
+  Warning,
+} from "../domain/types.js";
+import type { ChannelAdapter } from "../adapters/channel-adapters.js";
+import { fail, ok } from "../utils/result.js";
+
+export class DeploymentPlanner {
+  constructor(private readonly adapters: ChannelAdapter[]) {}
+
+  async planForSource(
+    sourceId: string,
+    manifest: Manifest,
+    lockFile: LockFile,
+  ): Promise<Result<DeploymentPlan>> {
+    const binding = manifest.bindings[sourceId] ?? { targets: {} };
+    const leafs = lockFile.leafInventory.filter((leaf) => leaf.sourceId === sourceId);
+    const previousDeployments = lockFile.deployments.filter(
+      (deployment) => deployment.sourceId === sourceId,
+    );
+    const actions: DeploymentAction[] = [];
+    const warnings: Warning[] = [];
+
+    for (const adapter of this.adapters) {
+      const detection = await adapter.detect();
+      const targetBinding = binding.targets[adapter.target];
+      const desiredLeafIds =
+        targetBinding?.enabled === true ? new Set(targetBinding.leafIds) : new Set<string>();
+      const projectedLinkNames = this.buildProjectedLinkNameMap(
+        manifest,
+        lockFile,
+        adapter.target,
+      );
+
+      const plannedForTarget = await this.planTarget(
+        sourceId,
+        adapter,
+        detection.available,
+        detection.rootPath,
+        detection.reason,
+        desiredLeafIds,
+        leafs,
+        previousDeployments,
+        projectedLinkNames,
+      );
+
+      actions.push(...plannedForTarget.actions);
+      warnings.push(...plannedForTarget.warnings);
+    }
+
+    return ok({
+      actions,
+      warnings,
+      blocked: actions.filter((action) => action.kind === "blocked"),
+    });
+  }
+
+  // fetch -> scan -> diff -> replan -> reapply
+  //
+  // desired bindings + lock state + disk state
+  //     -> create | update | remove | noop | blocked
+  private async planTarget(
+    sourceId: string,
+    adapter: ChannelAdapter,
+    targetAvailable: boolean,
+    rootPath: string,
+    unavailableReason: string | undefined,
+    desiredLeafIds: Set<string>,
+    leafs: LeafRecord[],
+    previousDeployments: DeploymentRecord[],
+    projectedLinkNames: Map<string, string>,
+  ): Promise<DeploymentPlan> {
+    const actions: DeploymentAction[] = [];
+    const warnings: Warning[] = [];
+    const desiredLeafs = leafs.filter((leaf) => desiredLeafIds.has(leaf.id));
+    const deploymentsForTarget = previousDeployments.filter(
+      (deployment) => deployment.target === adapter.target,
+    );
+    const managedByLeafId = new Map(
+      deploymentsForTarget.map((deployment) => [deployment.leafId, deployment]),
+    );
+    const missingDesiredLeafIds = [...desiredLeafIds].filter(
+      (leafId) => !desiredLeafs.some((leaf) => leaf.id === leafId),
+    );
+
+    for (const missingLeafId of missingDesiredLeafIds) {
+      const existing = managedByLeafId.get(missingLeafId);
+      warnings.push({
+        code: "MISSING_LEAF_SELECTION",
+        message: `${missingLeafId} no longer exists in source inventory.`,
+      });
+      if (existing) {
+        actions.push({
+          kind: "remove",
+          sourceId,
+          leafId: missingLeafId,
+          target: existing.target,
+          strategy: existing.strategy,
+          sourcePath: "",
+          targetPath: existing.targetPath,
+          contentHash: existing.contentHash,
+          reason: "Selected leaf no longer exists in source inventory.",
+        });
+      }
+    }
+
+    for (const leaf of desiredLeafs) {
+      const existing = managedByLeafId.get(leaf.id);
+      const projectedLinkName = projectedLinkNames.get(leaf.id) ?? leaf.linkName;
+      const targetPath = adapter.resolveTargetPath(rootPath, projectedLinkName);
+
+      if (!targetAvailable) {
+        const blockedAction: DeploymentAction = {
+          kind: "blocked",
+          sourceId,
+          leafId: leaf.id,
+          target: adapter.target,
+          strategy: adapter.strategy,
+          sourcePath: leaf.absolutePath,
+          targetPath,
+          contentHash: leaf.contentHash,
+          ...(unavailableReason ? { reason: unavailableReason } : {}),
+        };
+        actions.push(blockedAction);
+        continue;
+      }
+
+      const diskState = await this.inspectTargetPath(targetPath, leaf.absolutePath);
+      if (diskState.foreign && !existing) {
+        actions.push({
+          kind: "blocked",
+          sourceId,
+          leafId: leaf.id,
+          target: adapter.target,
+          strategy: adapter.strategy,
+          sourcePath: leaf.absolutePath,
+          targetPath,
+          reason: "Foreign content already exists at target path.",
+          contentHash: leaf.contentHash,
+        });
+        continue;
+      }
+
+      const kind = this.resolveDesiredAction(existing, diskState.matchesExpected, leaf);
+      actions.push({
+        kind,
+        sourceId,
+        leafId: leaf.id,
+        target: adapter.target,
+        strategy: adapter.strategy,
+        sourcePath: leaf.absolutePath,
+        targetPath,
+        ...(existing && existing.targetPath !== targetPath
+          ? { previousTargetPath: existing.targetPath }
+          : {}),
+        contentHash: leaf.contentHash,
+      });
+    }
+
+    for (const deployment of deploymentsForTarget) {
+      if (desiredLeafIds.has(deployment.leafId)) {
+        continue;
+      }
+
+      actions.push({
+        kind: "remove",
+        sourceId,
+        leafId: deployment.leafId,
+        target: deployment.target,
+        strategy: deployment.strategy,
+        sourcePath: "",
+        targetPath: deployment.targetPath,
+        contentHash: deployment.contentHash,
+      });
+    }
+
+    return { actions, warnings, blocked: actions.filter((item) => item.kind === "blocked") };
+  }
+
+  private resolveDesiredAction(
+    existing: DeploymentRecord | undefined,
+    matchesExpected: boolean,
+    leaf: LeafRecord,
+  ): DeploymentAction["kind"] {
+    if (!existing) {
+      return matchesExpected ? "noop" : "create";
+    }
+
+    if (!matchesExpected) {
+      return "update";
+    }
+
+    return existing.contentHash === leaf.contentHash ? "noop" : "update";
+  }
+
+  private async inspectTargetPath(
+    targetPath: string,
+    expectedSourcePath: string,
+  ): Promise<{ exists: boolean; matchesExpected: boolean; foreign: boolean }> {
+    try {
+      const stats = await fs.lstat(targetPath);
+      if (stats.isSymbolicLink()) {
+        const linked = await fs.readlink(targetPath);
+        const resolved = path.resolve(path.dirname(targetPath), linked);
+        const matchesExpected = resolved === expectedSourcePath;
+        return { exists: true, matchesExpected, foreign: !matchesExpected };
+      }
+      return { exists: true, matchesExpected: false, foreign: true };
+    } catch {
+      return { exists: false, matchesExpected: false, foreign: false };
+    }
+  }
+
+  private buildProjectedLinkNameMap(
+    manifest: Manifest,
+    lockFile: LockFile,
+    target: DeploymentTargetName,
+  ): Map<string, string> {
+    const selectedLeafs = manifest.sources.flatMap((source) => {
+      const targetBinding = manifest.bindings[source.id]?.targets[target];
+      if (!targetBinding?.enabled) {
+        return [];
+      }
+
+      return targetBinding.leafIds
+        .map((leafId) => lockFile.leafInventory.find((leaf) => leaf.id === leafId))
+        .filter((leaf): leaf is LeafRecord => Boolean(leaf));
+    });
+
+    const byLinkName = new Map<string, LeafRecord[]>();
+    for (const leaf of selectedLeafs) {
+      const group = byLinkName.get(leaf.linkName) ?? [];
+      group.push(leaf);
+      byLinkName.set(leaf.linkName, group);
+    }
+
+    const result = new Map<string, string>();
+    for (const leaf of selectedLeafs) {
+      const collisions = byLinkName.get(leaf.linkName) ?? [];
+      if (collisions.length <= 1) {
+        result.set(leaf.id, leaf.linkName);
+        continue;
+      }
+
+      result.set(leaf.id, `${leaf.sourceId}-${leaf.linkName}`);
+    }
+
+    return result;
+  }
+}

package/src/services/doctor-service.ts

@@ -0,0 +1,156 @@
+import fs from "node:fs/promises";
+import { createChannelAdapters } from "../adapters/channel-adapters.js";
+import type {
+  DoctorIssue,
+  DoctorReport,
+  LockFile,
+  Manifest,
+  Result,
+} from "../domain/types.js";
+import { hashDirectory, isBrokenSymlink, pathExists } from "../utils/fs.js";
+import { ok } from "../utils/result.js";
+
+export class DoctorService {
+  private readonly adapters = createChannelAdapters();
+
+  async run(manifest: Manifest, lockFile: LockFile): Promise<Result<DoctorReport>> {
+    const issues: DoctorIssue[] = [];
+
+    for (const source of manifest.sources) {
+      const binding = manifest.bindings[source.id] ?? { targets: {} };
+
+      for (const adapter of this.adapters) {
+        const configured = binding.targets[adapter.target];
+        if (!configured?.enabled) {
+          continue;
+        }
+
+        const detection = await adapter.detect();
+        if (!detection.available) {
+          issues.push({
+            severity: "error",
+            sourceId: source.id,
+            target: adapter.target,
+            code: "TARGET_UNAVAILABLE",
+            message: detection.reason ?? "Target is unavailable.",
+          });
+          continue;
+        }
+
+        for (const leafId of configured.leafIds) {
+          const leaf = lockFile.leafInventory.find((item) => item.id === leafId);
+          const deployment = lockFile.deployments.find(
+            (item) =>
+              item.sourceId === source.id &&
+              item.leafId === leafId &&
+              item.target === adapter.target,
+          );
+
+          if (!leaf) {
+            issues.push({
+              severity: "error",
+              sourceId: source.id,
+              target: adapter.target,
+              leafId,
+              code: "LEAF_MISSING",
+              message: "This saved selection no longer exists in the source inventory.",
+            });
+            continue;
+          }
+
+          const targetPath = deployment?.targetPath ?? adapter.resolveTargetPath(
+            detection.rootPath,
+            leaf.linkName,
+          );
+          if (!deployment) {
+            issues.push({
+              severity: "warning",
+              sourceId: source.id,
+              target: adapter.target,
+              leafId,
+              code: "DRIFT_NOT_DEPLOYED",
+              message: "This selected skill is not currently projected to disk.",
+            });
+            continue;
+          }
+
+          if (!(await pathExists(targetPath))) {
+            issues.push({
+              severity: "error",
+              sourceId: source.id,
+              target: adapter.target,
+              leafId,
+              code: "TARGET_MISSING",
+              message: "Projected target is missing on disk.",
+            });
+            continue;
+          }
+
+          if (deployment.strategy === "symlink") {
+            const stats = await fs.lstat(targetPath);
+            if (!stats.isSymbolicLink()) {
+              issues.push({
+                severity: "warning",
+                sourceId: source.id,
+                target: adapter.target,
+                leafId,
+                code: "DRIFT_TYPE",
+                message: "Expected a symlink, but found foreign content.",
+              });
+              continue;
+            }
+
+            if (await isBrokenSymlink(targetPath)) {
+              issues.push({
+                severity: "error",
+                sourceId: source.id,
+                target: adapter.target,
+                leafId,
+                code: "BROKEN_SYMLINK",
+                message: "Projected symlink is broken.",
+              });
+            }
+          } else {
+            const onDiskHash = await hashDirectory(targetPath);
+            if (onDiskHash !== deployment.contentHash) {
+              issues.push({
+                severity: "warning",
+                sourceId: source.id,
+                target: adapter.target,
+                leafId,
+                code: "DRIFT_COPY",
+                message: "Projected copy no longer matches saved state.",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    for (const deployment of lockFile.deployments) {
+      const sourceStillExists = manifest.sources.some(
+        (source) => source.id === deployment.sourceId,
+      );
+      if (!sourceStillExists) {
+        issues.push({
+          severity: "warning",
+          sourceId: deployment.sourceId,
+          target: deployment.target,
+          leafId: deployment.leafId,
+          code: "STALE_DEPLOYMENT",
+          message: "Saved deployment exists for a workflow group that is no longer registered.",
+        });
+      }
+    }
+
+    const hasError = issues.some((issue) => issue.severity === "error");
+    const hasWarning = issues.some((issue) => issue.severity === "warning");
+    const status: DoctorReport["status"] = hasError
+      ? "BLOCKED"
+      : hasWarning
+        ? "PARTIAL"
+        : "HEALTHY";
+
+    return ok({ status, issues });
+  }
+}

package/src/services/inventory-service.ts

@@ -0,0 +1,251 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { InvalidLeafRecord, LeafRecord } from "../domain/types.js";
+import { hashDirectory, slugify } from "../utils/fs.js";
+
+type InventoryScan = {
+  leafs: LeafRecord[];
+  invalidLeafs: InvalidLeafRecord[];
+};
+
+type ParsedSkillFile =
+  | {
+      valid: true;
+      name: string;
+      title: string;
+      description: string;
+      metadataWarnings: string[];
+    }
+  | { valid: false; reason: string };
+
+export class InventoryService {
+  private static readonly IGNORED_DIRECTORIES = new Set([
+    ".git",
+    "node_modules",
+  ]);
+
+  async scanSource(sourceId: string, checkoutPath: string): Promise<InventoryScan> {
+    const skillFiles = await this.findSkillFiles(checkoutPath);
+    const candidates: Array<LeafRecord & { dedupeKey: string }> = [];
+    const invalidLeafs: InvalidLeafRecord[] = [];
+
+    for (const skillFilePath of skillFiles) {
+      const leafRoot = path.dirname(skillFilePath);
+      const relativePath = path.relative(checkoutPath, leafRoot) || ".";
+      const raw = await fs.readFile(skillFilePath, "utf8");
+      const linkName = path.basename(leafRoot) || sourceId;
+      const parsed = this.parseSkillFile(raw, linkName);
+
+      if (!parsed.valid) {
+        invalidLeafs.push({
+          path: relativePath,
+          reason: parsed.reason,
+        });
+        continue;
+      }
+
+      const safeName = slugify(parsed.name) || linkName || sourceId;
+
+      candidates.push({
+        id: `${sourceId}:${relativePath}`,
+        sourceId,
+        name: safeName,
+        linkName,
+        title: parsed.title,
+        description: parsed.description,
+        relativePath,
+        absolutePath: leafRoot,
+        skillFilePath,
+        contentHash: await hashDirectory(leafRoot),
+        metadataWarnings: parsed.metadataWarnings,
+        valid: true,
+        dedupeKey: `${parsed.name}\n${parsed.description}`,
+      });
+    }
+
+    const leafs = this.dedupeCandidates(candidates, invalidLeafs);
+    leafs.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    invalidLeafs.sort((left, right) => left.path.localeCompare(right.path));
+
+    return { leafs, invalidLeafs };
+  }
+
+  private async findSkillFiles(rootPath: string): Promise<string[]> {
+    const discovered: string[] = [];
+
+    async function walk(currentPath: string): Promise<void> {
+      const entries = await fs.readdir(currentPath, { withFileTypes: true });
+      const files = entries
+        .filter((entry) => entry.isFile())
+        .sort((left, right) => left.name.localeCompare(right.name));
+      const visibleDirectories = entries
+        .filter(
+          (entry) =>
+            entry.isDirectory() &&
+            !InventoryService.IGNORED_DIRECTORIES.has(entry.name) &&
+            !entry.name.startsWith("."),
+        )
+        .sort((left, right) => left.name.localeCompare(right.name));
+      const hiddenDirectories = entries
+        .filter(
+          (entry) =>
+            entry.isDirectory() &&
+            !InventoryService.IGNORED_DIRECTORIES.has(entry.name) &&
+            entry.name.startsWith("."),
+        )
+        .sort((left, right) => left.name.localeCompare(right.name));
+
+      for (const entry of files) {
+        if (entry.name === "SKILL.md") {
+          discovered.push(path.join(currentPath, entry.name));
+        }
+      }
+
+      for (const entry of [...visibleDirectories, ...hiddenDirectories]) {
+        await walk(path.join(currentPath, entry.name));
+      }
+    }
+
+    await walk(rootPath);
+    return discovered;
+  }
+
+  private parseSkillFile(raw: string, parentDirName: string): ParsedSkillFile {
+    const lines = raw.split(/\r?\n/);
+    const frontmatter = this.parseFrontmatter(lines);
+    if (!frontmatter) {
+      return { valid: false, reason: "SKILL.md must start with YAML frontmatter" };
+    }
+
+    if (!Object.hasOwn(frontmatter.data, "name")) {
+      return {
+        valid: false,
+        reason: "SKILL.md frontmatter must include required field 'name'",
+      };
+    }
+
+    if (!Object.hasOwn(frontmatter.data, "description")) {
+      return {
+        valid: false,
+        reason: "SKILL.md frontmatter must include required field 'description'",
+      };
+    }
+
+    const bodyLines = lines.slice(frontmatter.bodyStartLine);
+    const firstHeading = bodyLines.find((line) => line.trim().startsWith("# "));
+    const rawName = (frontmatter.data.name ?? "").trim();
+    const rawDescription = frontmatter.data.description ?? "";
+    const metadataWarnings: string[] = [];
+
+    if (
+      rawName.length < 1 ||
+      rawName.length > 64 ||
+      !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(rawName)
+    ) {
+      metadataWarnings.push(
+        "name should be 1-64 chars, lowercase letters/numbers/hyphens only, with no leading/trailing hyphen or consecutive '--'",
+      );
+    }
+
+    if (rawName !== parentDirName) {
+      metadataWarnings.push(
+        `name should match parent directory name '${parentDirName}'`,
+      );
+    }
+
+    if (rawDescription.trim().length === 0) {
+      metadataWarnings.push("description should be non-empty");
+    }
+
+    if (rawDescription.length > 1024) {
+      metadataWarnings.push("description should be at most 1024 characters");
+    }
+
+    const title = firstHeading?.trim().slice(2).trim() || rawName || "Untitled skill";
+
+    return {
+      valid: true,
+      name: rawName,
+      title,
+      description: rawDescription.trim(),
+      metadataWarnings,
+    };
+  }
+
+  private dedupeCandidates(
+    candidates: Array<LeafRecord & { dedupeKey: string }>,
+    invalidLeafs: InvalidLeafRecord[],
+  ): LeafRecord[] {
+    const keptByKey = new Map<string, LeafRecord>();
+    for (const candidate of candidates) {
+      if (keptByKey.has(candidate.dedupeKey)) {
+        const kept = keptByKey.get(candidate.dedupeKey)!;
+        invalidLeafs.push({
+          path: candidate.relativePath,
+          reason: `Duplicate skill content skipped because ${kept.relativePath} was discovered first`,
+        });
+        continue;
+      }
+      const { dedupeKey: _dedupeKey, ...leaf } = candidate;
+      keptByKey.set(candidate.dedupeKey, leaf);
+    }
+
+    return [...keptByKey.values()];
+  }
+
+  private parseFrontmatter(
+    lines: string[],
+  ): { data: Record<string, string>; bodyStartLine: number } | undefined {
+    if (lines[0]?.trim() !== "---") {
+      return undefined;
+    }
+
+    const data: Record<string, string> = {};
+    let index = 1;
+
+    while (index < lines.length) {
+      const line = lines[index] ?? "";
+      if (line.trim() === "---") {
+        return { data, bodyStartLine: index + 1 };
+      }
+
+      const pair = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+      if (!pair) {
+        index += 1;
+        continue;
+      }
+
+      const key = pair[1];
+      const rest = pair[2];
+      if (!key || rest === undefined) {
+        index += 1;
+        continue;
+      }
+
+      if (rest === "|" || rest === ">") {
+        const blockLines: string[] = [];
+        index += 1;
+        while (index < lines.length) {
+          const blockLine = lines[index] ?? "";
+          if (blockLine.length === 0) {
+            blockLines.push("");
+            index += 1;
+            continue;
+          }
+          if (!blockLine.startsWith("  ")) {
+            break;
+          }
+          blockLines.push(blockLine.slice(2));
+          index += 1;
+        }
+        data[key] = blockLines.join("\n").trim();
+        continue;
+      }
+
+      data[key] = rest.trim();
+      index += 1;
+    }
+
+    return undefined;
+  }
+}