facult 2.13.9 → 2.15.0

package/src/remote.ts

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { mkdir, readdir, readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import {
@@ -10,7 +11,10 @@ import {
   resolve,
 } from "node:path";
 import { isCancel, multiselect, select, text } from "@clack/prompts";
-import { facultBuiltinPackRoot } from "./builtin";
+import {
+  builtinOperatingModelInstallRelPath,
+  facultBuiltinPackRoot,
+} from "./builtin";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import {
   renderBullets,
@@ -21,7 +25,11 @@ import {
   renderTable,
 } from "./cli-ui";
 import { buildIndex } from "./index-builder";
-import { facultRootDir, readFacultConfig } from "./paths";
+import {
+  facultRootDir,
+  projectRootFromAiRoot,
+  readFacultConfig,
+} from "./paths";
 import {
   assertManifestIntegrity,
   assertManifestSignature,
@@ -130,6 +138,7 @@ interface InstallResult {
   sourceTrustLevel: SourceTrustLevel;
   dryRun: boolean;
   changedPaths: string[];
+  skippedPaths?: string[];
 }
 
 interface UpdateCheckResult {
@@ -1298,41 +1307,250 @@ async function listFilesRecursive(rootDir: string): Promise<string[]> {
   return out.sort();
 }
 
+interface BuiltinPackManifest {
+  version: 1;
+  pack: string;
+  updatedAt: string;
+  files: Record<string, { sha256: string }>;
+}
+
+function sha256Text(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function builtinPackManifestPath(rootDir: string): string {
+  return join(rootDir, ".facult", "packs", "facult-operating-model.json");
+}
+
+async function readBuiltinPackManifest(
+  rootDir: string
+): Promise<BuiltinPackManifest | null> {
+  const pathValue = builtinPackManifestPath(rootDir);
+  if (!(await pathExists(pathValue))) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(await Bun.file(pathValue).text());
+    if (
+      parsed?.version === 1 &&
+      parsed.pack === "facult-operating-model" &&
+      isPlainObject(parsed.files)
+    ) {
+      return parsed as BuiltinPackManifest;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function serializeBuiltinPackManifest(manifest: BuiltinPackManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+const OPERATING_MODEL_SNIPPET_FRAME = `## Working mode
+
+<!-- fclty:global/baseline -->
+<!-- /fclty:global/baseline -->
+
+<!-- fclty:global/core/work-units -->
+<!-- /fclty:global/core/work-units -->
+
+<!-- fclty:global/core/feedback-loops -->
+<!-- /fclty:global/core/feedback-loops -->
+
+<!-- fclty:global/core/verification -->
+<!-- /fclty:global/core/verification -->
+
+<!-- fclty:global/core/writeback -->
+<!-- /fclty:global/core/writeback -->
+
+## Shared instruction sources
+
+- For work-unit definition and scope clarification, read \${refs.work_units}.
+- For identifying, improving, and validating feedback loops, read \${refs.feedback_loops}.
+- For verification and anti-false-positive checks, read \${refs.verification}.
+- For checking integration boundaries, read \${refs.integration}.
+- For learning, decisions, and writeback, read \${refs.learning_writeback}.
+- For capability evolution, proposal kinds, and \`facult ai\` workflow, read \${refs.evolution}.
+- For deciding whether something belongs in global or project scope, read \${refs.project_capability}.
+- Add private language, coding, or writing refs in local config only when they belong to the user's own operating layer.
+`;
+
+function appendOperatingModelFrame(seedText: string): string {
+  const normalized = seedText.trimEnd();
+  if (normalized.includes("<!-- fclty:global/baseline -->")) {
+    return `${normalized}\n`;
+  }
+  return `${normalized}\n\n## Facult Operating Model\n\n${OPERATING_MODEL_SNIPPET_FRAME}`;
+}
+
+async function firstExistingFileText(
+  candidates: string[]
+): Promise<string | null> {
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) {
+      return await Bun.file(candidate).text();
+    }
+  }
+  return null;
+}
+
+async function seedAgentsGlobalText(args: {
+  rootDir: string;
+  homeDir?: string;
+  fallbackText: string;
+}): Promise<{ text: string; seededFromExisting: boolean }> {
+  const home = args.homeDir ?? homedir();
+  const projectRoot = projectRootFromAiRoot(args.rootDir, home);
+  const seedText = await firstExistingFileText(
+    projectRoot
+      ? [
+          join(projectRoot, "AGENTS.md"),
+          join(projectRoot, "CLAUDE.md"),
+          join(projectRoot, ".codex", "AGENTS.md"),
+          join(projectRoot, ".claude", "CLAUDE.md"),
+        ]
+      : [
+          join(home, ".codex", "AGENTS.md"),
+          join(home, ".claude", "CLAUDE.md"),
+          join(home, ".cursor", "AGENTS.md"),
+        ]
+  );
+  if (!seedText?.trim()) {
+    return { text: args.fallbackText, seededFromExisting: false };
+  }
+  return {
+    text: appendOperatingModelFrame(seedText),
+    seededFromExisting: true,
+  };
+}
+
 async function scaffoldBuiltinOperatingModelPack(args: {
   rootDir: string;
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
+  update?: boolean;
   installedAs?: string;
 }): Promise<InstallResult> {
   const rootDir = resolve(args.rootDir);
   const packRoot = facultBuiltinPackRoot("facult-operating-model");
   const files = await listFilesRecursive(packRoot);
   const changedPaths: string[] = [];
+  const skippedPaths: string[] = [];
+  const existingManifest = await readBuiltinPackManifest(rootDir);
+  const manifestFiles: BuiltinPackManifest["files"] = {
+    ...(existingManifest?.files ?? {}),
+  };
 
   for (const sourcePath of files) {
     const relPath = relative(packRoot, sourcePath);
     if (!relPath || relPath.startsWith("..")) {
       continue;
     }
-    const targetPath = join(rootDir, relPath);
-    const exists = await pathExists(targetPath);
-    if (exists && !args.force) {
+    const targetRelPath = builtinOperatingModelInstallRelPath(relPath);
+    const targetPath = join(rootDir, targetRelPath);
+    const rawSourceText = await Bun.file(sourcePath).text();
+    const targetExists = await pathExists(targetPath);
+    const seed =
+      targetRelPath === "AGENTS.global.md" && !targetExists
+        ? await seedAgentsGlobalText({
+            rootDir,
+            homeDir: args.homeDir,
+            fallbackText: rawSourceText,
+          })
+        : null;
+    const sourceText = seed?.text ?? rawSourceText;
+    const trackInManifest = !seed?.seededFromExisting;
+    const sourceHash = sha256Text(sourceText);
+    let shouldWrite = !targetExists || Boolean(args.force);
+
+    if (targetExists && !shouldWrite) {
+      const targetText = await Bun.file(targetPath).text();
+      const targetHash = sha256Text(targetText);
+      if (targetHash === sourceHash) {
+        if (trackInManifest) {
+          manifestFiles[targetRelPath] = { sha256: sourceHash };
+        }
+      } else if (
+        args.update &&
+        existingManifest?.files[targetRelPath]?.sha256 === targetHash
+      ) {
+        shouldWrite = true;
+      } else if (args.update) {
+        skippedPaths.push(targetPath);
+      }
+    }
+
+    if (!shouldWrite) {
       continue;
     }
     changedPaths.push(targetPath);
+    if (trackInManifest) {
+      manifestFiles[targetRelPath] = { sha256: sourceHash };
+    } else {
+      delete manifestFiles[targetRelPath];
+    }
     if (!args.dryRun) {
       await mkdir(dirname(targetPath), { recursive: true });
-      await Bun.write(targetPath, await Bun.file(sourcePath).text());
+      await Bun.write(targetPath, sourceText);
     }
   }
 
   const configPath = join(rootDir, "config.toml");
-  if (!(await pathExists(configPath)) || args.force) {
+  const configRelPath = "config.toml";
+  const configText = "version = 1\n";
+  const configHash = sha256Text(configText);
+  const configExists = await pathExists(configPath);
+  let shouldWriteConfig = !configExists || Boolean(args.force);
+  if (configExists && !shouldWriteConfig) {
+    const targetText = await Bun.file(configPath).text();
+    const targetHash = sha256Text(targetText);
+    if (targetHash === configHash) {
+      manifestFiles[configRelPath] = { sha256: configHash };
+    } else if (
+      args.update &&
+      existingManifest?.files[configRelPath]?.sha256 === targetHash
+    ) {
+      shouldWriteConfig = true;
+    } else if (args.update) {
+      skippedPaths.push(configPath);
+    }
+  }
+  if (shouldWriteConfig) {
     changedPaths.push(configPath);
+    manifestFiles[configRelPath] = { sha256: configHash };
     if (!args.dryRun) {
       await mkdir(dirname(configPath), { recursive: true });
-      await Bun.write(configPath, "version = 1\n");
+      await Bun.write(configPath, configText);
+    }
+  }
+
+  const manifestPath = builtinPackManifestPath(rootDir);
+  const sortedManifestFiles = Object.fromEntries(
+    Object.entries(manifestFiles).sort(([a], [b]) => a.localeCompare(b))
+  );
+  const stableManifest = serializeBuiltinPackManifest({
+    version: 1,
+    pack: "facult-operating-model",
+    updatedAt: existingManifest?.updatedAt ?? "",
+    files: sortedManifestFiles,
+  });
+  const existingManifestText = (await pathExists(manifestPath))
+    ? await Bun.file(manifestPath).text()
+    : null;
+  if (existingManifestText !== stableManifest) {
+    const nextManifest = serializeBuiltinPackManifest({
+      version: 1,
+      pack: "facult-operating-model",
+      updatedAt: new Date().toISOString(),
+      files: sortedManifestFiles,
+    });
+    changedPaths.push(manifestPath);
+    if (!args.dryRun) {
+      await mkdir(dirname(manifestPath), { recursive: true });
+      await Bun.write(manifestPath, nextManifest);
     }
   }
 
@@ -1352,6 +1570,7 @@ async function scaffoldBuiltinOperatingModelPack(args: {
     sourceTrustLevel: "trusted",
     dryRun: Boolean(args.dryRun),
     changedPaths: uniqueSorted(changedPaths),
+    skippedPaths: uniqueSorted(skippedPaths),
   };
 }
 
@@ -1360,6 +1579,7 @@ async function scaffoldBuiltinProjectAiPack(args: {
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
+  update?: boolean;
 }): Promise<InstallResult> {
   const cwd = resolve(args.cwd ?? process.cwd());
   return await scaffoldBuiltinOperatingModelPack({
@@ -1367,6 +1587,7 @@ async function scaffoldBuiltinProjectAiPack(args: {
     homeDir: args.homeDir,
     dryRun: args.dryRun,
     force: args.force,
+    update: args.update,
     installedAs: "project-ai",
   });
 }
@@ -2815,9 +3036,11 @@ function printTemplatesHelp() {
             ),
             renderCode("fclt templates init agents [--force] [--dry-run]"),
             renderCode(
-              "fclt templates init operating-model [--global|--project|--root PATH] [--force] [--dry-run]"
+              "fclt templates init operating-model [--global|--project|--root PATH] [--update] [--force] [--dry-run]"
+            ),
+            renderCode(
+              "fclt templates init project-ai [--update] [--force] [--dry-run]"
             ),
-            renderCode("fclt templates init project-ai [--force] [--dry-run]"),
             renderCode(
               "fclt templates init automation <template-id> [--scope global|project|wide] [--name <name>] [--project-root <path>] [--cwds <path1,path2>] [--rrule <RRULE>] [--status PAUSED|ACTIVE] [--yes] [--dry-run]"
             ),
@@ -3322,6 +3545,7 @@ export async function templatesCommand(
   }
   const dryRun = args.includes("--dry-run");
   const force = args.includes("--force");
+  const update = args.includes("--update");
   const json = args.includes("--json");
   const parsedArgs = parseTemplateInitArgs(args);
   const positional = parsedArgs.positional;
@@ -3333,6 +3557,7 @@ export async function templatesCommand(
         homeDir: ctx.homeDir,
         dryRun,
         force,
+        update,
       });
       if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -3348,6 +3573,14 @@ export async function templatesCommand(
               title: "Changed Paths",
               lines: renderBullets(result.changedPaths),
             },
+            ...(result.skippedPaths?.length
+              ? [
+                  {
+                    title: "Skipped Local Edits",
+                    lines: renderBullets(result.skippedPaths),
+                  },
+                ]
+              : []),
           ],
         })
       );
@@ -3378,6 +3611,7 @@ export async function templatesCommand(
         homeDir: ctx.homeDir,
         dryRun,
         force,
+        update,
       });
       if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -3393,6 +3627,14 @@ export async function templatesCommand(
               title: "Changed Paths",
               lines: renderBullets(result.changedPaths),
             },
+            ...(result.skippedPaths?.length
+              ? [
+                  {
+                    title: "Skipped Local Edits",
+                    lines: renderBullets(result.skippedPaths),
+                  },
+                ]
+              : []),
           ],
         })
       );